peach.tl.setup_cellrank

Contents

peach.tl.setup_cellrank#

peach.tl.setup_cellrank(adata, high_purity_threshold=0.8, n_neighbors=30, n_pcs=11, compute_paga=True, solver='gmres', tol=1e-06, terminal_obs_key='archetypes', verbose=True)[source]#

Set up CellRank workflow for archetypal or centroid-based trajectory analysis.

This function orchestrates the complete pipeline from terminal state assignments to fate probabilities, including neighbors computation, UMAP, PAGA, and GPCCA.

Parameters:

  • adata (AnnData) – Annotated data matrix. Must contain: - adata.obs[terminal_obs_key] : Terminal state assignments - adata.obsm[‘X_pca’] : PCA coordinates If using archetypes (default): - adata.obsm[‘cell_archetype_weights’] : Barycentric weights - adata.obsm[‘archetype_distances’] : Distances to archetypes

  • high_purity_threshold (float, optional (default: 0.80)) – Percentile threshold for defining high-purity cells. 0.80 means top 20% of cells per archetype. Only used when terminal_obs_key=’archetypes’.

  • n_neighbors (int, optional (default: 30)) – Number of neighbors for k-NN graph construction

  • n_pcs (int, optional (default: 11)) – Number of principal components to use

  • compute_paga (bool, optional (default: True)) – Whether to compute PAGA connectivity

  • solver (str, optional (default: 'gmres')) – Solver for fate probability computation (‘gmres’, ‘direct’, etc.)

  • tol (float, optional (default: 1e-6)) – Tolerance for iterative solver

  • terminal_obs_key (str, optional (default: 'archetypes')) – Key in adata.obs containing terminal state assignments. Use ‘archetypes’ for standard archetype-based analysis or ‘centroid_assignments’ for treatment phase centroid trajectories (requires running pc.tl.assign_to_centroids() first).

  • verbose (bool, optional (default: True)) – Print progress messages

Returns:

  • ck (cellrank.kernels.ConnectivityKernel) – Computed transition kernel

  • g (cellrank.estimators.GPCCA) – GPCCA estimator with fate probabilities

  • Stores in adata

  • —————

  • adata.obs[‘terminal_states’] (pd.Series) – Terminal state assignments for high-purity cells

  • adata.obsm[‘fate_probabilities’] (np.ndarray) – Fate probability matrix (n_obs × n_lineages)

  • adata.uns[‘lineage_names’] (list) – List of lineage names (archetype or centroid names)

  • adata.uns[‘cellrank_gpcca’] (GPCCA) – GPCCA estimator object for downstream functions

  • adata.obsm[‘X_umap’] (np.ndarray) – UMAP coordinates (if not already present)

  • adata.uns[‘neighbors’] (dict) – k-NN graph (if not already present)

  • adata.uns[‘paga’] (dict) – PAGA results (if compute_paga=True)

Examples

Basic archetype-based analysis:

>>> import peach as pc
>>> ck, g = pc.tl.setup_cellrank(adata)

Treatment phase centroid-based analysis:

>>> # First compute centroids and assign cells
>>> pc.tl.compute_conditional_centroids(adata, condition_column="treatment_phase")
>>> pc.tl.assign_to_centroids(adata, condition_column="treatment_phase")
>>> # Then run CellRank with centroid assignments
>>> ck, g = pc.tl.setup_cellrank(adata, terminal_obs_key="centroid_assignments")

Access results:

>>> fate_probs = adata.obsm["fate_probabilities"]
>>> lineages = adata.uns["lineage_names"]
>>> terminal_states = adata.obs["terminal_states"]

Customize parameters:

>>> ck, g = pc.tl.setup_cellrank(
...     adata,
...     high_purity_threshold=0.90,  # Top 10% of cells
...     n_neighbors=50,
...     compute_paga=False,
... )

Notes

  • Requires CellRank installation: pip install cellrank

  • For GAMR models, set R_HOME before importing cellrank: ```python import os

    os.environ[“R_HOME”] = “/Library/Frameworks/R.framework/Resources” ```

See also

assign_to_centroids

Assign cells to treatment phase centroids

compute_lineage_pseudotimes

Convert fate probabilities to pseudotime

compute_lineage_drivers

Identify genes driving lineage commitment

References

Contents