mantispy.tl.edistance

Contents

mantispy.tl.edistance#

mantispy.tl.edistance(adata, groupby='Metadata_Perturbation', reference='negcon', use_rep=None, n_permutations=1000, threshold=0.05, max_reference=2000, seed=0, key_added='edistance', copy=False)#

Energy distance between each group and the controls, or between every pair.

Energy distance, 2E|a-b| - E|a-a'| - E|b-b'|, compares whole distributions and is zero only when they are equal. It makes no distributional assumption and responds to changes in spread or shape as well as shifts, which suits single-cell resolution, where a perturbation is a population.

Parameters:

  • adata (AnnData) – Object to score. Most informative at cell resolution.

  • groupby (str (default: 'Metadata_Perturbation')) – Column defining the populations.

  • reference (str | None (default: 'negcon')) – Rows to compare against. Each group is compared with them and gets a permutation p-value in uns["mantispy"][key_added]. With None, the group-by-group distance matrix is written to uns["mantispy"][key_added + "_pairwise"] as a square frame labeled by group, without p-values. Its cost is quadratic in the number of groups, which is expensive for a whole screen at cell level. max_reference and seed apply on this path too, capping the rows taken from each group.

  • use_rep (str | None (default: None)) – Score obsm[use_rep] instead of X.

  • n_permutations (int (default: 1000)) – Number of label permutations in the null.

  • threshold (float (default: 0.05)) – q-value below which a group is marked is_hit.

  • max_reference (int (default: 2000)) – Maximum number of rows sampled from the reference and, separately, from each group. The pooled distance matrix is quadratic in their sum; 2000 of each takes 128 MB.

  • seed (int (default: 0)) – Seed for the subsampling and the permutations.

  • key_added (str (default: 'edistance')) – Name for the outputs.

  • copy (bool (default: False)) – Return a modified copy instead of mutating in place.

Return type:

AnnData | None

Returns:

None, or the modified copy. With a reference, writes uns["mantispy"][key_added] with group, n_obs, distance, pvalue, qvalue and is_hit, where n_obs counts the rows the statistic actually used, after any subsampling and after splitting the reference. With reference=None, writes only the square, group-labeled matrix at uns["mantispy"][key_added + "_pairwise"].

Raises:

ValueError – reference selects fewer than two rows.

Notes

The null permutes the group and reference labels over the pooled rows and recomputes the statistic, the standard permutation test for a two-sample quantity.

A group that is the reference itself is scored by splitting its rows in half. A group with fewer than two rows on either side, or a reference group with fewer than four rows, gets a NaN p-value and a warning.

Check the false positive rate on your own screen with diagnose_testing(), which relabels control wells as pseudo-treatments of the same size and reports the fraction that are called.

Contents