harmonypy-batch-integration

Correct batch effects on PCA, LSI, or spectral embeddings using harmonypy via scanpy.external.harmony_integrate.

1|Updated Nov 20, 2025
One-click install
npx skills add https://github.com/tony-zhelonkin/scio --skill harmonypy-batch-integration-tony-zhelonkin
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: harmonypy-batch-integration
Source: https://github.com/tony-zhelonkin/scio/tree/main/skills/harmonypy-batch-integration
Command: npx skills add https://github.com/tony-zhelonkin/scio --skill harmonypy-batch-integration-tony-zhelonkin

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires harmonypy, scanpy, snapatac2, muon, numpy.

What problem does it solve? When combining single-cell data from multiple samples or donors, batch effects create artificial structure on UMAPs that confounds clustering and label transfer. This Skill applies the Harmony algorithm to remove batch effects directly on a per-cell embedding without touching the expression matrix. ## Core Features & Use Cases - RNA batch correction: Run harmony_integrate on X_pca after standard scanpy preprocessing, then build neighbors, UMAP, and Leiden clusters on the integrated embedding. - ATAC batch correction: Apply Harmony to spectral or LSI embeddings from snapatac2, with guidance on dropping depth-correlated LSI components. - Joint RNA+ATAC integration: Concatenate per-modality integrated embeddings or use muon's WNN to combine modalities across common cells. - Use Case: You merged six donor samples into one AnnData and the UMAP separates by donor instead of cell type. Run harmony_integrate with key="sample" on X_pca, then recompute neighbors on X_pca_harmony to recover biologically meaningful clusters. ## Quick Start Use the harmonypy batch integration skill to remove sample batch effects from my AnnData object's PCA embedding and recompute neighbors and UMAP on the corrected embedding.

Frequently Asked Questions about harmonypy-batch-integration

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run Harmony batch correction in scanpy?▼

Call scanpy.external.pp.harmony_integrate with your batch key, basis="X_pca", and adjusted_basis="X_pca_harmony". Then pass the adjusted embedding to sc.pp.neighbors via use_rep before computing UMAP and Leiden clustering.

Harmony vs scVI for single-cell batch correction?▼

Harmony is CPU-only, fast, and deterministic, correcting only the embedding without touching the expression matrix. scVI is a generative deep-learning model that is slower and stochastic but models count data directly; use scvi-basic when you need a generative model.

Can I use Harmony on ATAC-seq data?▼

Yes, run harmony_integrate on the spectral or LSI embedding from snapatac2 by setting basis="X_spectral" or basis="X_lsi". For LSI, drop the first component if it correlates with sequencing depth before integration.

Why is Harmony over-correcting my cell types?▼

Over-correction happens when theta is too high, causing distinct cell types to mix. Lower theta via harmony_kwargs and verify the batch key is correct; if batch mixing is poor instead, raise theta or the number of input components.

When should I not use harmonypy for integration?▼

Avoid harmonypy when you need a generative model of the data, where scVI or scANVI is appropriate, or for unpaired cross-modality alignment, where scglue-unpaired-multiomics-integration is the right tool.