mantispy.metrics.evaluate_integration#

mantispy.metrics.evaluate_integration(adata, *, reps=('X_pca',), label_key='Metadata_Perturbation', batch_key='Metadata_Batch', min_max_scale=False, metrics=None, map_mode='replicability', map_kwargs=None, svd_solver=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.

metrics Sequence[str] | None (default: None)

Which metrics to run, to control cost. None runs the full scib panel plus the mAP. A list names exactly what to run: "map" for the mAP, and any scib metric flag ("ilisi_knn", "clisi_knn", "kbet_per_label", "pcr_comparison", "graph_connectivity", "isolated_labels", "silhouette_label", …). metrics=["map"] skips scib entirely, the cheapest option. The full panel is expensive: expect several minutes and many GB on tens of thousands of cells, since kBET and the clustering metrics dominate.

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.

svd_solver str | None (default: None)

How the unintegrated baseline PCA is decomposed. None eigendecomposes the feature covariance when the screen has many more wells than features and otherwise uses arpack; any scanpy solver name forces one. The baseline matches either way.

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 – A requested family is missing its extra (neither installed, or metrics asks for one that is not installed).

  • ValueError – The scib panel is requested with no features in adata.X; the mAP is requested but label_key has no replicates or is confounded with batch_key; or metrics names an unknown metric or selects nothing runnable.

  • KeyError – obs is missing label_key or batch_key.