peach.tl.single_trajectory_analysis

peach.tl.single_trajectory_analysis#

peach.tl.single_trajectory_analysis(adata, trajectory, trajectories=None, selection_method='discrete', source_weight_threshold=0.4, target_fate_threshold=0.4, verbose=True)[source]#

Analyze single archetype-to-archetype trajectory.

Filters cells based on source archetype assignment/weight and target fate probability. Returns a subset AnnData ready for CellRank gene trends analysis.

IMPORTANT: This function requires CellRank setup to be run first:
>>> ck, g = pc.tl.setup_cellrank(adata, high_purity_threshold=0.80)
>>> pc.tl.compute_lineage_pseudotimes(adata)
For driver genes, use CellRank directly:
>>> drivers = g.compute_lineage_drivers(lineages="archetype_3")
Parameters:

  • adata (AnnData) – Annotated data matrix. Must contain (from setup_cellrank): - adata.obsm[‘fate_probabilities’] : Fate probability matrix - adata.uns[‘lineage_names’] : List of lineage names - adata.obs[‘pseudotime_to_{archetype}’] : Pseudotime from compute_lineage_pseudotimes - adata.obs[‘archetypes’] : Discrete archetype assignments (for selection_method=’discrete’) - adata.obsm[‘cell_archetype_weights’] : Barycentric weights (for selection_method=’weight’)

  • trajectory (tuple) – Archetype pair as (source_idx, target_idx), e.g., (0, 3) for archetype_0 → archetype_3.

  • trajectories (list of tuple, optional) – Multiple trajectory pairs to analyze sequentially. If provided, trajectory is ignored and returns list of results.

  • selection_method (str, default: 'discrete') – How to select source cells: - ‘discrete’ : Filter by adata.obs[‘archetypes’] == source_archetype - ‘weight’ : Filter by weights[:, source_idx] >= source_weight_threshold - ‘both’ : Compute both and report comparison (uses ‘discrete’ for subset)

  • source_weight_threshold (float, default: 0.4) – Minimum barycentric weight for source archetype (only used if selection_method=’weight’).

  • target_fate_threshold (float, default: 0.4) – Minimum fate probability for target archetype selection.

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

Returns:

  • Tuple[SingleTrajectoryResult, AnnData] –

    • result : SingleTrajectoryResult with trajectory metadata

    • adata_traj : Subset AnnData containing only trajectory cells, ready for CellRank gene trends. If trajectories list provided, returns list of tuples.

  • Stores in adata

  • —————

  • adata.obs[‘trajectory_{src}_to_{tgt}_cells’] (bool) – Boolean mask for cells in trajectory.

  • adata.uns[‘trajectory_{src}_to_{tgt}’] (dict) – Trajectory analysis metadata.

Examples

Complete workflow with CellRank:

>>> import peach as pc
>>> import cellrank as cr
>>>
>>> # 1. Setup CellRank (computes fate probabilities)
>>> ck, g = pc.tl.setup_cellrank(adata, high_purity_threshold=0.80)
>>> pc.tl.compute_lineage_pseudotimes(adata)
>>>
>>> # 2. Analyze trajectory (returns subset AnnData)
>>> result, adata_traj = pc.tl.single_trajectory_analysis(adata, trajectory=(4, 5), selection_method="discrete")
>>> print(f"Found {result.n_trajectory_cells} cells")
>>>
>>> # 3. Get drivers from CellRank
>>> drivers = g.compute_lineage_drivers(lineages="archetype_5")
>>> top_genes = drivers.index[:5].tolist()
>>>
>>> # 4. Plot gene trends using subset
>>> cr.pl.gene_trends(adata_traj, model=cr.models.GAMR(adata_traj), genes=top_genes, time_key=result.pseudotime_key)

Compare selection methods:

>>> result, adata_traj = pc.tl.single_trajectory_analysis(adata, trajectory=(1, 2), selection_method="both")
>>> print(f"Discrete: {result.n_discrete_cells} cells")
>>> print(f"Weight-based: {result.n_weight_cells} cells")

Notes

  • Requires setup_cellrank() and compute_lineage_pseudotimes() to be run first

  • Driver computation is NOT included - use CellRank’s g.compute_lineage_drivers() directly

  • Pseudotime uses CellRank-computed values from compute_lineage_pseudotimes()

See also

setup_cellrank

Complete CellRank workflow setup (computes fate probabilities)

compute_lineage_pseudotimes

Compute pseudotime to each lineage