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)[source]#

Correct an embedding for batch with Harmony.

Harmony performed best in the batch-correction benchmark for image-based profiling of Arevalo et al. (2024), and is the last step of the JUMP consortium’s recipe. 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].

Notes

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

harmonypy can report convergence and return the embedding unchanged; this wrapper warns when it does. On 50 640 JUMP TARGET2 wells across ten imaging sites it corrected the embedding, but it returned every small synthetic embedding tried (48 to 768 wells, with and without an explicit nclust) unchanged.

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