atlas.tl.terminal_state_silhouette

atlas.tl.terminal_state_silhouette(mudata, fate_key='fate_probabilities', soft_assignment=True, time_key=None, alpha=1)

Compute the silhouette score for terminal states.

This metric evaluates whether cells committed to the same lineage are more similar to each other than to cells belonging to other lineages. It extends the classical silhouette score to probabilistic fate assignments.

Two strategies are supported to handle partially committed cells:

• Soft assignment: cells are not assigned to a single lineage, and distances are weighted by fate probabilities.

• Pseudotime weighting: silhouette scores are weighted by pseudotime, giving more importance to committed cells.

The silhouette score is computed as:

$$s_i = \\frac{b_i - a_i}{\\max(a_i, b_i)}$$

where $a_i$ is the intra-terminal distance and $b_i$ is the nearest-terminal distance.

When soft_assignment=False, the final score is computed as:

S = \\frac{\\sum_i \\tau_i^\\alpha s_i}{\\sum_i \\tau_i^\\alpha}

where $\\tau_i$ is the pseudotime of cell $i$.

Parameters:

• mudata (MuData) – Annotated multimodal data object.

• fate_key (str (default: 'fate_probabilities')) – Key in mudata.obsm containing fate probabilities (cells × terminal states).

• soft_assignment (bool (default: True)) – Whether to use the soft assignment strategy. If False, hard assignment with pseudotime weighting is used.

• time_key (str | None (default: None)) – Key in mudata.obs containing pseudotime values. Required when soft_assignment=False.

• alpha (float (default: 1)) – Exponent used to weight pseudotime in the silhouette aggregation.

Return type:

float

Returns:

Terminal state silhouette score.