mantispy.pp.harmony#

mantispy.pp.harmony(adata, batch_key='Metadata_Batch', use_rep='X_pca', key_added='X_harmony', max_iter=20, seed=0, copy=False, **harmony_kwargs)[source]#

Correct an embedding for batch with Harmony.

Harmony ranked in the top three in every scenario of the batch-correction benchmark of Arevalo et al. [2024], as did Seurat RPCA. It is the last step of the JUMP profiling recipe for compound and ORF profiles. It iterates soft clustering and per-cluster linear correction on an embedding, so it writes a corrected obsm and leaves X unchanged.

Parameters:
adata AnnData

Object holding the embedding to correct.

batch_key str (default: 'Metadata_Batch')

obs column naming the nuisance grouping, such as the batch, plate or imaging site.

use_rep str (default: 'X_pca')

Embedding to correct, normally the output of scanpy.pp.pca().

key_added str (default: 'X_harmony')

obsm key for the corrected embedding.

max_iter int (default: 20)

Harmony iterations.

seed int (default: 0)

Seed, passed through as random_state.

copy bool (default: False)

Return a modified copy instead of writing in place.

harmony_kwargs Any

Passed to harmonypy.run_harmony, for example theta, nclust or sigma.

Return type:

AnnData | None

Returns:

None, or the modified copy. Writes obsm[key_added].

Raises:

  • ImportError – If harmonypy is not installed.

  • KeyError – If use_rep is not in obsm, or batch_key is not an obs column.

  • ValueError – If batch_key has a single level, leaving nothing to correct for.

Notes

Requires harmonypy: pip install 'mantispy[harmony]'.

harmonypy can report convergence and return the embedding unchanged; this wrapper warns when it does. What decides this is separability rather than size: it corrects the embedding of JUMP TARGET2 wells across imaging sites, and returns the input untouched when the batches occupy disjoint regions of the embedding, because every soft cluster then holds a single batch.

Check the result with more than one metric. On those JUMP wells Harmony moved the site centroids closer together but lowered iLISI, so the sites moved together globally while neighborhoods stayed site-pure. Batch metrics often disagree like this, which is why evaluate_integration() reports the whole scib-metrics panel rather than one number.