mantispy.metrics.evaluate_integration

mantispy.metrics.evaluate_integration#

mantispy.metrics.evaluate_integration(adata, *, reps=('X_pca',), label_key='Metadata_Perturbation', batch_key='Metadata_Batch', min_max_scale=False, map_mode='replicability', map_kwargs=None, ax=None)[source]#

Score one or more representations against a batch and draw the integration benchmark as a heatmap.

The numbers come from scib-metrics, the field’s implementation of the integration panel, which mantispy reads through its public get_results rather than reimplements. mantispy renders its own heatmap from them and, when copairs is installed, adds the cross-replicate mean average precision (mAP) as its own block. The columns are grouped left to right into bio conservation, batch correction, retrieval (mAP) and the aggregate scores, each block under its own header.

The bio-conservation metrics measure whether a representation keeps the biology (cLISI is how label-pure a well’s neighbourhood is); the batch-correction metrics whether it mixes the batches (iLISI is how batch-mixed that neighbourhood is, PCR comparison how much less of the variance the batch explains after correction). Total is scib’s own weighted score, 0.4 batch correction and 0.6 bio conservation, left exactly as scib computes it. Total+mAP is mantispy’s: it folds mAP into the bio group as one more bio signal, bio' = mean(bio metrics + mAP), then reweights 0.4 batch correction and 0.6 bio’. The mAP is measured over the treated wells only (controls left out), while scib’s bio, batch and Total columns use every well, so Total and Total+mAP are not strictly apples-to-apples on a control-heavy screen.

The return type is uniform across install states, so the numbers are always reachable:

  • With mantispy[integration] (scib-metrics) and copairs, the frame holds every metric, the mAP column and both totals; the heatmap has all four blocks.

  • With only scib-metrics, the frame and heatmap drop the retrieval block and Total+mAP.

  • With only copairs, the frame and heatmap hold the per-representation mAP alone, and a warning notes that scib-metrics adds the full panel.

  • With neither, this raises ImportError.

This function computes no native PC-regression of its own. To audit what a representation spends its variance on besides the label, such as the cell count or the plate position, whose better direction is context-dependent and so is deliberately not in this table, use pc_regression() for a single covariate or batch_variance_explained() to stack several.

Parameters:

  • adata (AnnData) – Object holding the representations in obsm and the label and batch in obs.

  • reps (Sequence[str] (default: ('X_pca',))) – obsm keys to compare, e.g. ("X_pca", "X_pca_harmony").

  • label_key (str (default: 'Metadata_Perturbation')) – obs column with the biological grouping.

  • batch_key (str (default: 'Metadata_Batch')) – obs column with the nuisance grouping.

  • min_max_scale (bool (default: False)) – Colour and score each metric column scaled across the representations, as scib does by default. Off by default so a single representation still has honest absolute values to colour by.

  • map_mode (str (default: 'replicability')) – The copairs pairing for mAP, "replicability" (the Arevalo mAP-nonrep default) or "cross_plate". See _map_settings.

  • map_kwargs (dict[str, Any] | None (default: None)) – Overrides for any of the four copairs pair arguments, on top of map_mode.

  • ax (Axes | None (default: None)) – Axes to draw the heatmap on, or None for a new figure.

Return type:

DataFrame

Returns:

The numeric results, one row per representation and one column per metric, the mAP and both totals.

Raises:

  • ImportError – Neither scib-metrics nor copairs is installed.

  • ValueError – The object has one row per perturbation, which has no replicate pairs to score.

  • KeyError – obs is missing label_key or batch_key.