mantispy.pp.harmony

Contents

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)#

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 sc.pp.pca’s output.

  • 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 corrected the embedding of 50 640 JUMP TARGET2 wells across ten 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 36% closer together (mean separation 300 to 192, with unchanged overall spread) but lowered iLISI from 2.01 to 1.02, so the sites moved together globally while neighborhoods stayed site-pure. Batch metrics often disagree like this, which is why evaluate_correction() reports several and takes a map_key.

Contents