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, *, replicate=None)

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, so large values need a lot of memory.

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.

replicate str | Sequence[str] | None (default: None)

obs column, or sequence of columns, whose groups are the design’s exchangeable unit: the well in an arrayed screen, the guide ("Metadata_sgRNA") in a pooled one. The permutation null then draws whole replicates rather than cells, since cells within a well are not independent replicates (see Notes). Left None, it defaults to the physical well on an object stamped cell resolution with replicated wells; it warns and permutes cells when no complete well column is present, and raises on a pooled design, where some well holds both reference and tested cells.

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, the profiles hold missing values, which cannot be scored, or replicate is not given on a pooled design at cell resolution.

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. At cell resolution the exchangeable unit is the well, not the cell, so replicate draws whole wells for the pseudo-group instead; without a usable well column it warns and permutes cells, which is anti-conservative. In a pooled screen every well holds every perturbation, so drawing whole wells cannot separate a group from the reference; the exchangeable unit is the guide, and the call raises until replicate names it.

A group that is the reference itself is scored by splitting its rows in half, by whole replicates when one is in use. 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.