atlas.tl.terminal_pseudotime_enrichment

atlas.tl.terminal_pseudotime_enrichment(mudata, time_key='pseudotime', rank=False)

Compute the average pseudotime enrichment across terminal states.

This function quantifies whether terminal states are enriched toward higher (or lower) pseudotime values. For each terminal state, it computes the difference between the median pseudotime of the cells in that state and the global median pseudotime across all cells:

$$E_{ts} = \\mathrm{median}(m_{ts}) - \\mathrm{median}(m_{all})$$

where $m$ is either the raw pseudotime or its normalized rank transformation. The final score is the average enrichment across all terminal states:

$$E = \\frac{1}{T} \\sum_{ts} E_{ts}$$

where $T$ is the number of terminal states.

Positive values indicate that terminal states are enriched toward higher pseudotime (i.e., later stages), while negative values indicate enrichment toward lower pseudotime.

Parameters:

• mudata (MuData) – Annotated multimodal dataset containing pseudotime values and terminal state annotations.

• time_key (str (default: 'pseudotime')) – Key in mudata.obs where pseudotime values are stored.

• rank (bool (default: False)) – If True, pseudotime values are converted to normalized ranks in the interval [0, 1] before computing enrichment. This makes the score robust to non-linear scaling of pseudotime.

Return type:

float

Returns:

Mean enrichment score across all terminal states. Returns NaN if enrichment cannot be computed (e.g., no valid cells in terminal states).

Raises:

KeyError – If time_key is not present in mudata.obs.

Notes

Terminal states are expected to be stored in mudata.uns["terminal_states"] as a dictionary mapping each terminal state name to a list of cell identifiers. Returns NaN if no terminal states are found.