atlas.tl.spearman_correlation

atlas.tl.spearman_correlation#

atlas.tl.spearman_correlation(mudata, key1, key2, seed=42, n_resamples=10000, confidence_level=0.95)#

Compute the Spearman rank correlation between two variables stored in mudata.obs.

Parameters:

  • mudata (MuData) – Multimodal annotated data object containing observations in .obs.

  • key1 (str) – Column name in mudata.obs for the first variable.

  • key2 (str) – Column name in mudata.obs for the second variable.

  • seed (int (default: 42)) – Random seed used for permutation testing 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.

-pvalue (float)

Two-sided p-value. Computed via permutation test for small sample sizes, otherwise using the asymptotic approximation from scipy.stats.spearmanr.

cituple[float, float] | None

Confidence interval as (low, high). Returns None if input contains NaNs.

Raises:

KeyError – If key1 and key2 are not in mudata.obs.

Warns:

  • UserWarning – If input contains NaN values.

  • UserWarning – If the number of samples is smaller than 500 (permutation test is used).

  • UserWarning – If the correlation is exactly ±1, the confidence interval may be undefined.

Notes

Spearman correlation as implemented in scipy.stats.spearmanr() does not have a simple closed-form confidence interval, thereby bootstrap resampling is used to estimate uncertainty.

Permutation test was used to provide more accurate pvalues as described in scipy.stats.spearmanr().

When the correlation is exactly ±1, the bootstrap distribution becomes degenerate and the confidence interval may contain NaN values.