harmony-batch-correction

What it does

Harmony batch correction takes a PCA embedding (cells × PCs) and returns a corrected embedding with batch effects regressed out via iterative soft-clustering and per-cluster linear regression. The corrected embedding is then used to compute neighbors, UMAP, and downstream clustering, without modifying the raw counts. It is applicable to scRNA-seq, ATAC-seq, and other omics modalities that provide a PCA-like embedding. The skill covers various integration scenarios and recommends alternative methods for probabilistic, graph-based, or Seurat-based workflows.

How it works

The skill describes running Harmony in three modes:

• Via Scanpy integration: sc.external.pp.harmony_integrate modifies adata.obsm["X_pca"] in place and stores corrected results in adata.obsm["X_pca_harmony"], followed by building a neighbor graph on the corrected embedding and computing UMAP and Leiden clustering.
• Via harmonypy directly: uses harmonypy.run_harmony on the PCA embedding with a metadata DataFrame for variables to correct (e.g., batch); stores corrected embedding in adata.obsm["X_pca_harmony"].
• R integration with Seurat: RunHarmony adds a corrected reduction ("harmony"), then FindNeighbors, FindClusters, and RunUMAP using that reduction. Key steps include preparing an AnnData object with PCA already computed, selecting the columns for batch correction, and then downstream visualization and clustering on the corrected embedding.

When to use it

Use Harmony when integrating multiple scRNA-seq datasets across samples, donors, sequencing runs, or technical batches to remove batch variation while preserving biology. It is suitable for large datasets (millions of cells) and supports correcting for multiple confounding variables. The workflow favors using the corrected embedding for neighborhood graph construction and visualization rather than altering the gene expression matrix.

What it can touch

The tool interacts with:

• Python environment and packages: harmonypy, scanpy, anndata, pandas, matplotlib (explicit in prerequisites).
• Data structures: adata.obsm keys "X_pca" and "X_pca_harmony"; adata.obs with batch metadata; adata.layers["counts"] for raw counts storage.
• Optional R workflow: Seurat objects and RunHarmony via Seurat harmony integration.

Caveats

The skill notes that Harmony corrects the embedding, not the count matrix, and that differential expression should rely on raw or normalized counts. It also mentions that HVG selection and PCA should be batch-aware in Scanpy (batch_key usage). The text provides guidance on parameter options (theta, sigma, nclust, max_iter_harmony, tau, etc.) and warnings about potential over-correction in multi-variable scenarios. No licensing or usage restrictions beyond MIT in the provided material.