ocelli.tl.transitions_graph

ocelli.tl.transitions_graph#

ocelli.tl.transitions_graph(adata: AnnData, x: str, transitions: str, n_edges: int = 10, timestamps: str | None = None, out: str = 'graph', n_jobs: int = -1, verbose: bool = False, copy: bool = False)#

Transitions-based graph construction

Constructs a transitions-based graph using transition probabilities between cells, such as RNA velocity. The graph connects each cell to its n_edges nearest neighbors with the highest transition probabilities stored in adata.uns[transitions]. Optionally, cell timestamps can be used to constrain neighbors to specific temporal steps.

Note

Before using this function, you must run ocelli.pp.neighbors to compute the nearest neighbors for the specified embedding.

Parameters:

  • adata (anndata.AnnData) – The annotated data matrix.

  • x (str) – Key in adata.obsm corresponding to the embedding for which nearest neighbors were computed.

  • transitions (str) – Key in adata.uns storing the transition probability matrix (shape (n_cells, n_cells)).

  • n_edges (int) – Number of edges (connections) per graph node. (default: 10)

  • timestamps (str or None) – Key in adata.obs storing numerical timestamps. If None, no temporal constraints are applied. (default: None)

  • out (str) – Key in adata.obsm where the constructed graph is saved. (default: ‘graph’)

  • n_jobs (int) – Number of parallel jobs to use. If -1, all CPUs are used. (default: -1)

  • verbose (bool) – Whether to print progress notifications. (default: False)

  • copy (bool) – Whether to return a copy of adata. If False, updates are made in-place. (default: False)

Returns:

  • If copy=False: Updates adata with the constructed graph stored in adata.obsm[out].

  • If copy=True: Returns a modified copy of adata with the constructed graph.

Return type:

anndata.AnnData or None

Example:
import ocelli as oci
from anndata import AnnData
import numpy as np

# Example data
adata = AnnData(X=np.random.rand(100, 50))
adata.obsm['embedding'] = np.random.rand(100, 10)
adata.uns['transitions'] = np.random.rand(100, 100)
adata.obs['timestamps'] = np.random.choice([0, 1, 2], size=100)

# Compute nearest neighbors
oci.pp.neighbors(adata, x=['embedding'], n_neighbors=20)

# Construct transitions-based graph
oci.tl.transitions_graph(
    adata,
    x='embedding',
    transitions='transitions',
#   timestamps='timestamps',
    n_edges=10,
    verbose=True
)