scCS.bifurcation

bifurcation.py — Cluster-level fate map construction for scCS.

In scCS, the bifurcation point is explicitly defined by the user as a single cluster (e.g., leiden cluster ‘17’). There is no automatic fate detection — the user supplies:

root : the progenitor/root cluster label branches : list of terminal fate cluster labels

This module builds a standardized FateMap from those labels, computing centroids in the scCS star embedding space (X_sccs) and collecting per-fate cell indices.

The FateMap is the single source of truth consumed by SingleScorer.score().

Classes

FateMap

Standardized description of k cell fates for commitment scoring.

Functions

build_fate_map(→ FateMap)

Build a FateMap from user-supplied cluster labels.

Module Contents

class scCS.bifurcation.FateMap

Standardized description of k cell fates for commitment scoring.

root

Label of the progenitor/root cluster supplied by the user.

Type:

str

fate_names

Human-readable labels for each terminal fate (length k).

Type:

list of str

fate_centroids

Mean 2D position of each fate’s cells in the scCS embedding.

Type:

np.ndarray, shape (k, 2)

root_centroid

Mean 2D position of the bifurcation cluster cells. In the scCS star embedding this is always near (0, 0).

Type:

np.ndarray, shape (2,)

root_cells

Indices of bifurcation cluster cells in adata.

Type:

np.ndarray of int

fate_cell_indices

Per-fate arrays of cell indices.

Type:

list of np.ndarray

arm_angles_deg

Angle (degrees) of each fate’s radial arm in the star embedding.

Type:

np.ndarray, shape (k,)

obs_key

The obs column used for cluster labels.

Type:

str

k

Number of fates (read-only property).

Type:

int

root: str

fate_names: List[str]

fate_centroids: numpy.ndarray

root_centroid: numpy.ndarray

root_cells: numpy.ndarray

fate_cell_indices: List[numpy.ndarray]

arm_angles_deg: numpy.ndarray

obs_key: str

property k: int

summary() → str

scCS.bifurcation.build_fate_map(adata, root: str, branches: List[str], obs_key: str = 'leiden', verbose: bool = True) → FateMap

Build a FateMap from user-supplied cluster labels.

This is the only fate-detection strategy in scCS. The user explicitly names the bifurcation cluster and all terminal fate clusters.

Parameters:

• adata (AnnData) – Must have X_sccs in obsm (built by build_star_embedding).

• root (str) – Label of the progenitor cluster in adata.obs[obs_key]. Example: ‘17’ (leiden cluster 17)

• branches (list of str) – Labels of the k terminal fate clusters. Example: [‘Monocyte’, ‘DC’, ‘Neutrophil’]

• obs_key (str) – Column in adata.obs with cluster labels.

• verbose (bool)

Return type:

FateMap