mantispy.tl.effect_size

Contents

mantispy.tl.effect_size#

mantispy.tl.effect_size(adata, groupby='Metadata_Perturbation', reference='negcon', method='cohens_d', pvalues=True, exact='auto', min_obs=2, key_added='effect', copy=False)[source]#

Per-feature effect size of each group against the reference.

Parameters:

  • adata (AnnData) – Object to score, at cell or profile resolution.

  • groupby (str (default: 'Metadata_Perturbation')) – Column defining the groups to score.

  • reference (str | None (default: 'negcon')) – Rows to compare against: "negcon", None for everything, or a boolean obs column. The reference group is also scored against itself as a calibration check; its effects should be near zero.

  • method (str (default: 'cohens_d')) – "cohens_d" is the difference in means over the pooled standard deviation. "robust_z" is the difference in medians in units of control MAD, which a few extreme cells cannot move.

  • pvalues (bool (default: True)) – Compute a Mann-Whitney p-value for each effect. At single-cell resolution nearly every feature is significant, so turn them off when ranking by effect.

  • exact (bool | Literal['auto'] (default: 'auto')) – How to compute the p-value’s null for a group’s untied features. "auto" uses the exact null when the smaller of the group and the reference has eight or fewer measured rows and the fast normal approximation otherwise, which is the sample size at which scipy’s own method="auto" switches. False always uses the normal approximation, which is the fast path and the sensible choice for a screen with many small groups, where the exact null dominates the runtime for no change a reader would see. True always uses the exact null. Tied features take the normal approximation whatever this is set to, because the exact null is only defined without ties.

  • min_obs (int (default: 2)) – Groups with fewer rows than this are left unscored as NaN.

  • key_added (str (default: 'effect')) – 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. Writes varm[key_added], a (n_vars, n_groups) float32 array with columns in the order of uns["mantispy"][key_added + "_groups"], and uns["mantispy"][key_added], a tidy frame with group, feature, effect, pvalue (Mann-Whitney U, two-sided, NaN when pvalues=False) and qvalue (Benjamini-Hochberg over the whole table, since it is one family of tests).

Raises:

ValueError – method is not one of METHODS, exact is not True, False or "auto", or reference selects fewer than two rows.

Notes

The p-value tests whether the distributions differ, and its significance grows with the number of rows. The effect size measures by how much, and does not grow with the number of rows. At single-cell resolution nearly everything is significant, so rank by effect and use the q-value only to filter. The exact null depends only on the two sample sizes, so it is built once per pair of sizes and reused across every feature that shares them.

Contents