peach.tl.compute_transition_frequencies

peach.tl.compute_transition_frequencies#

peach.tl.compute_transition_frequencies(adata, start_weight_threshold=0.5, fate_prob_threshold=0.3, lineages=None)[source]#

Compute frequency of transitions between archetypal states.

Identifies cells transitioning from one archetype to another based on their starting archetypal weights and fate probabilities from CellRank.

A transition is counted when a cell has: - High barycentric weight for source archetype (> start_weight_threshold) - High fate probability for target archetype (> fate_prob_threshold)

Parameters:

adata (AnnData) – Annotated data object with CellRank results. Must contain: - adata.obsm[‘cell_archetype_weights’]: Barycentric weights [n_obs, n_archetypes] - adata.obs[‘archetypes’]: Categorical archetype assignments - adata.obsm[‘fate_probabilities’]: Fate probability matrix [n_obs, n_lineages] - adata.uns[‘lineage_names’]: List of lineage/archetype names - adata.uns[‘cellrank_gpcca’]: GPCCA estimator object (from setup_cellrank)
start_weight_threshold (float, default=0.5) – Minimum barycentric weight to consider a cell as “starting” from an archetype. - 0.5 = top 50% cells per archetype (balanced) - 0.7 = top 30% cells (more stringent) - 0.3 = top 70% cells (more permissive)
fate_prob_threshold (float, default=0.3) – Minimum fate probability to consider a cell as “transitioning to” an archetype. - 0.3 = 30% commitment probability (standard) - 0.5 = 50% commitment (stringent) - 0.2 = 20% commitment (permissive)
lineages (list of str, optional) – Specific lineages/archetypes to analyze. If None, uses all lineages from adata.uns[‘lineage_names’] that start with ‘archetype_’.

Returns:

Transition frequency matrix with shape [n_archetypes, n_archetypes]. - Index: Source archetypes (starting weight) - Columns: Target archetypes (fate probability) - Values: Integer counts of cells satisfying both thresholds - Diagonal: Cells maintaining their archetype identity - Off-diagonal: Cross-archetype transitions

Example:: archetype_0 archetype_1 archetype_2 archetype_3

archetype_0 150 45 23 12 archetype_1 12 200 67 8 archetype_2 8 34 180 45 archetype_3 5 15 30 190

Return type:

pd.DataFrame

Raises:

ValueError – If required CellRank results are missing (run setup_cellrank() first)

Notes

archetype_0 (centroid) uses categorical assignment instead of weight threshold
Returns raw counts (not normalized probabilities)
Cells can appear in multiple transitions if they meet multiple criteria
Use with PAGA connectivity for complete trajectory analysis

Examples

Basic usage with default thresholds:

>>> import peach as pc
>>> # After running setup_cellrank()
>>> transitions = pc.tl.compute_transition_frequencies(adata)
>>> print(transitions)

Stringent thresholds for high-confidence transitions:

>>> transitions = pc.tl.compute_transition_frequencies(
...     adata,
...     start_weight_threshold=0.7,  # Top 30% cells
...     fate_prob_threshold=0.5,  # 50% commitment
... )

Analyze specific archetypes only:

>>> transitions = pc.tl.compute_transition_frequencies(
...     adata, lineages=["archetype_1", "archetype_2", "archetype_3"]
... )

Visualize with seaborn:

>>> import seaborn as sns
>>> import matplotlib.pyplot as plt
>>> sns.heatmap(transitions, annot=True, fmt="d", cmap="YlOrRd")
>>> plt.title("Archetype Transition Frequencies")
>>> plt.show()

peach.tl.compute_transition_frequencies

Contents

peach.tl.compute_transition_frequencies#