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, label_sep=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. When annotation_key holds a list of labels per row, a pair is positive if the two lists share any label, and a perturbation with several labels is scored toward each of its classes. This multilabel scoring is supported through mode="consistency".

    "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. A column holding a list of labels per row is scored as multilabel (see the mode description); a scalar column is a single label. A list-valued obs column does not survive write_h5ad, so store the labels as a delimited string, which does survive, and split it with label_sep.

  • label_sep (str | None (default: None)) – Split a string annotation_key on this separator into a list of labels per row, so a stored "MEK|ERK" is scored as multilabel. None leaves the column as it is. An entry that is already a list, or is missing, is left untouched.

  • 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. A group with one member has no within-group pair to score, so it is absent from the table. A multilabel annotation has no single score per row, so it writes the per-class table to uns only and clears obs[key_added] and obs[key_added + "_qvalue"].

Raises:

  • ImportError – copairs is not installed; it is an optional extra.

  • 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, the profiles hold missing values, which cannot be ranked, a label column mixes list-valued and scalar entries, or more than one positive-pair column is list-valued.

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

Contents