mantispy.tl.guide_activity#

mantispy.tl.guide_activity(adata, *, reference, group='Metadata_Gene', use_rep=None, layer=None, key_added='guide_activity', copy=False)[source]#

Score each guide for how far it sits from a reference control class, as a one-sided p-value.

This produces the per-guide score aggregate_guides() reads: a one-sided p-value, small when the guide shows a phenotype. Each feature is standardized by the reference guides’ median and median absolute deviation, so a guide’s activity is the size of its standardized profile, how far it moves from the reference centre in control units. The p-value is the share of reference guides whose activity reaches the guide’s or beyond, with one added to the count and the total, so it is one-sided and small for a strong phenotype.

The reference class sets the scale and is not scored, so for aggregate_guides() the reference here and the control null there must be two different control classes. A pooled screen that carries both intergenic and non-targeting guides can set the scale with one and keep the other as the null, so the calibration is not circular.

Parameters:
adata AnnData

One row per guide, with the class label in obs and the profiles in X (or use_rep/layer).

reference str

The value of group that marks the reference control guides, such as "intergenic".

group str (default: 'Metadata_Gene')

obs column holding the class label, the gene or control name per guide.

use_rep str | None (default: None)

Read obsm[use_rep] instead of X; cannot be combined with layer.

layer str | None (default: None)

Read this layer instead of X.

key_added str (default: 'guide_activity')

obs column the per-guide p-value is written to.

copy bool (default: False)

Return a modified copy instead of mutating in place.

Return type:

AnnData | None

Returns:

None, or the modified copy. Writes obs[key_added], the one-sided per-guide p-value, with the reference guides left missing since they set the scale rather than being scored.

Raises:

  • ValueError – reference is absent from obs[group], or every feature is constant across the reference guides.

  • KeyError – group is not an obs column.

Notes

A feature that does not vary across the reference guides carries no information and is dropped, so a profile of all-constant features cannot be scored.