mantispy.tl.map#

mantispy.tl.map(adata, pos_sameby=None, pos_diffby=(), neg_sameby=(), neg_diffby=(), mode=None, label=None, batch='Metadata_Plate', annotation_key=None, label_sep=None, reference='negcon', use_rep=None, null_size=10000, threshold=0.05, seed=0, distance='cosine', null='copied', n_jobs=None, batch_size=None, 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 the batch column; queries on a plate without controls are left out, with a warning. In a CRISPR screen, non-targeting controls do not cut DNA, so nearly every knockout can come out active from the cutting response alone; guides against genes the cell line does not express (unexpressed_genes()) are a cutting control to retrieve against instead, and empirical_fdr() calibrates the calls.

"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.

label str | None (default: None)

The obs column naming the perturbation, which the presets group replicates by. Defaults to the perturbation column the object records, else Metadata_Perturbation.

batch str (default: 'Metadata_Plate')

The obs column naming the plate or batch, which the presets draw negatives from.

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.

null str (default: 'copied')

The null model of the group mAP, passed to copairs: "copied", "permutation" or "joint". "copied" is the model of Kalinin et al. [2025] and copairs before 0.6. "permutation" relabels profiles and recomputes the mAP from their similarities. It needs every profile holding a label in the scored table, so it fails on a multilabel annotation where a profile has no negative pair.

n_jobs int | None (default: None)

Threads for the null permutations (copairs’ max_workers). None lets copairs size its own pool from os.cpu_count(), which over-subscribes a job allocated only a few CPUs; set it to the cores you were given.

batch_size int | None (default: None)

Pair-distance batch size copairs scores at, which caps peak memory. None uses copairs’ default (20000).

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.

Notes

An explicit pair query that pairs across a high-cardinality column (a large pos_diffby or neg_diffby fan-out, such as every compound against every other) materializes a pair set that grows with the product of the group sizes and can reach tens of gigabytes on a few thousand wells, separately from batch_size, which only caps the distance step. Run such a query on consensus profiles (one row per perturbation, via consensus()) rather than on every well, and set batch_size to cap the distance memory. Before copairs runs, the pair count is bounded from the group sizes, and a query with too many pairs warns.