mantispy.tl.map

Contents

mantispy.tl.map#

mantispy.tl.map(adata, pos_sameby=None, pos_diffby=(), neg_sameby=(), neg_diffby=(), mode=None, annotation_key=None, reference='negcon', use_rep=None, null_size=10000, threshold=0.05, seed=0, distance='cosine', key_added='map', copy=False)[source]#

Mean average precision per group, with a permutation null.

Parameters:

  • adata (AnnData) – Profiles to score, normally well-level.

  • pos_sameby (Sequence[str] | None (default: None)) – obs columns a positive pair must share, in copairs’ terms. Pass the four pair arguments or mode, not both.

  • pos_diffby (Sequence[str] (default: ())) – obs columns in which a positive pair must differ.

  • neg_sameby (Sequence[str] (default: ())) – obs columns a negative pair must share.

  • neg_diffby (Sequence[str] (default: ())) – obs columns in which a negative pair must differ.

  • mode (str | None (default: None)) –

    A preset for the pair definitions, one of the following.

    "activity"

    Is this perturbation distinguishable from the negative controls it was plated with? Its replicates are retrieved against the control profiles on the query’s own plate only. This is the phenotypic activity of Kalinin et al. [2025]. Needs reference and Metadata_Plate; queries on a plate without controls are left out, with a warning.

    "consistency"

    Do perturbations sharing an annotation look more alike than those that do not? This is the phenotypic consistency of Kalinin et al. [2025]. Needs annotation_key (a mechanism, target or gene column) and is meant for consensus profiles of perturbations already known to be active.

    "replicability"

    Do a perturbation’s replicates retrieve each other against the other perturbations on the query’s plate? This is the mAP-nonrep of Arevalo et al. [2024], which leaves the controls out; reference=None keeps them in.

    "cross_plate"

    Do a perturbation’s replicates on other plates retrieve each other against all other profiles? A replicate counts only if it is on a different plate, which separates reproducible biology from plate effects.

  • annotation_key (str | None (default: None)) – The obs column mode="consistency" groups by.

  • reference (str | None (default: 'negcon')) – Which rows are the negative controls, which mode="activity" retrieves against and mode="replicability" leaves out: "negcon", the name of a boolean obs column, or None for none.

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

  • null_size (int (default: 10000)) – Size of the permutation null. No p-value falls below 1 / (null_size + 1), so the correction over many groups needs a large one, and a warning says when it is too small to call a group on its own.

  • threshold (float (default: 0.05)) – Significance threshold passed to copairs.

  • seed (int (default: 0)) – Seed for the permutation null.

  • distance (str (default: 'cosine')) – Distance copairs ranks by.

  • key_added (str (default: 'map')) – Where to store results.

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

Return type:

AnnData | None

Returns:

None, or the modified copy. Writes the per-group table to uns["mantispy"][key_added] and joins obs[key_added] and obs[key_added + "_qvalue"] back onto the rows.

Raises:

  • ImportError – copairs is not installed, which it is not by default because it needs Python < 3.13.

  • ValueError – mode was passed together with explicit pair arguments or neither was passed, mode is not one of MODES, mode="consistency" came without annotation_key, mode="activity" found no controls, no profile has a negative pair to be ranked against, or the profiles hold missing values, which cannot be ranked.

  • KeyError – obs is missing a column the pair definitions or reference name.

Contents