atlas.tl.fate_concentration_index

atlas.tl.fate_concentration_index(mudata, fate_key='fate_probabilities', time_key='pseudotime', seed=42, n_resamples=10000, confidence_level=0.95)

Compute the correlation between fate concentration and pseudotime.

The fate concentration index is defined as the sum of squared fate probabilities for each observation:

$$C_i = \\sum_{j} p_{ij}^2$$

where $p_{ij}$ represents the probability of cell $i$ belonging to fate $j$. This metric captures how concentrated or committed a cell is toward specific fates (higher values indicate stronger commitment).

The function computes the Spearman rank correlation between the concentration index and pseudotime, along with a p-value and a bootstrap confidence interval.

For small sample sizes (< 500 observations), a permutation test is used to estimate the p-value, as suggested by scipy.stats.spearmanr().

Parameters:

• mudata (MuData) – Multi-modal annotated data object containing fate probabilities and pseudotime annotations.

• fate_key (str (default: 'fate_probabilities')) – Key in mudata.obsm where the fate probability matrix is stored. Rows correspond to observations and columns to different fates.

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

• seed (int (default: 42)) – Random seed used for permutation tests and bootstrap resampling.

• n_resamples (int (default: 10000)) – Number of resampling iterations for permutation test and bootstrap.

• confidence_level (float (default: 0.95)) – Confidence level for the bootstrap confidence interval.

Return type:

tuple

Returns:

-statistic (float)

Spearman correlation coefficient between fate concentration index and pseudotime.

-pvalue (float)

Two-sided p-value associated with the correlation. Computed via permutation test if sample size is small, otherwise from scipy.stats.spearmanr.

cituple[float, float]

Lower and upper bounds of the bootstrap confidence interval.

-concentration_index (Series)

Computed concentration index for each observation.

Raises:

KeyError – If fate_key is not found in mudata.obsm or time_key is not found in mudata.obs.

Warns:

• UserWarning – If the fate probability matrix is empty.

• UserWarning – If the correlation is ±1, making the confidence interval unreliable.

• UserWarning – If the sample size is small (< 500), triggering permutation-based p-value estimation.