Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/satijalab/seurat-wrappers/llms.txt

Use this file to discover all available pages before exploring further.

Harmony is a fast, sensitive method for integrating single-cell data by iteratively correcting PCA embeddings. It operates on an existing PCA reduction and produces a corrected low-dimensional embedding suitable for downstream clustering and visualization.
The RunHarmony() function is provided directly by the harmony package — not by SeuratWrappers. SeuratWrappers coordinates usage but the wrapper itself ships with Harmony. You do not need SeuratWrappers to call RunHarmony().

​
Citation

If you use Harmony in your work, please cite:
Fast, sensitive, and flexible integration of single cell data with Harmony Ilya Korsunsky, Jean Fan, Kamil Slowikowski, Fan Zhang, Kevin Wei, Yuriy Baglaenko, Michael Brenner, Po-Ru Loh, Soumya Raychaudhuri bioRxiv, 2019 / Nature Methods, 2019 doi: 10.1101/461954v2

​
Installation

# Install Harmony from GitHub
remotes::install_github('immunogenomics/harmony')

# Supporting packages
install.packages('Seurat')
remotes::install_github('satijalab/seurat-data')

​
Workflow

1

Load libraries and data

library(harmony)
library(Seurat)
library(SeuratData)

InstallData("pbmcsca")
data("pbmcsca")
2

Normalize and reduce dimensions

Run standard Seurat preprocessing through PCA before calling Harmony.
pbmcsca <- NormalizeData(pbmcsca) %>%
  FindVariableFeatures() %>%
  ScaleData() %>%
  RunPCA(verbose = FALSE)
3

Run Harmony integration

Harmony corrects the PCA embedding using the grouping variable you specify. The result is stored as a new harmony reduction.
pbmcsca <- RunHarmony(pbmcsca, group.by.vars = "Method")
4

Downstream analysis on corrected embedding

Use the harmony reduction for UMAP, neighbor finding, and clustering.
pbmcsca <- RunUMAP(pbmcsca, reduction = "harmony", dims = 1:30)
pbmcsca <- FindNeighbors(pbmcsca, reduction = "harmony", dims = 1:30)
pbmcsca <- FindClusters(pbmcsca)
DimPlot(pbmcsca, group.by = c("Method", "ident", "CellType"), ncol = 3)

​
Examples

​
Interferon-stimulated and control PBMC

InstallData("ifnb")
data("ifnb")
ifnb <- NormalizeData(ifnb) %>%
  FindVariableFeatures() %>%
  ScaleData() %>%
  RunPCA(verbose = FALSE)
ifnb <- RunHarmony(ifnb, group.by.vars = "stim")
ifnb <- RunUMAP(ifnb, reduction = "harmony", dims = 1:30)
ifnb <- FindNeighbors(ifnb, reduction = "harmony", dims = 1:30) %>% FindClusters()
DimPlot(ifnb, group.by = c("stim", "ident", "seurat_annotations"), ncol = 3)

​
Eight human pancreatic islet datasets

InstallData("panc8")
data("panc8")
panc8 <- NormalizeData(panc8) %>%
  FindVariableFeatures() %>%
  ScaleData() %>%
  RunPCA(verbose = FALSE)
panc8 <- RunHarmony(panc8, group.by.vars = "replicate")
panc8 <- RunUMAP(panc8, reduction = "harmony", dims = 1:30)
panc8 <- FindNeighbors(panc8, reduction = "harmony", dims = 1:30) %>% FindClusters()
DimPlot(panc8, group.by = c("replicate", "ident", "celltype"), ncol = 3)

​
Key Parameters

​
group.by.vars
character
required
One or more metadata column names specifying the batch or grouping variables to integrate across. For example, "orig.ident", "Method", or c("donor", "batch").
​
dims.use
integer vector
default:"NULL"
Which PCA dimensions to use. Defaults to all available dimensions in the PCA reduction.
​
theta
numeric
default:"2"
Diversity clustering penalty parameter. Higher values enforce greater dataset mixing. One value per group.by.vars variable.
​
lambda
numeric
default:"1"
Ridge regression penalty. Larger values produce more conservative correction.
​
sigma
numeric
default:"0.1"
Width of soft k-means clusters. Larger values assign cells to more clusters, increasing smoothing.
​
reduction
character
default:"pca"
Name of the existing dimensional reduction to correct. Must be run before calling RunHarmony().
​
reduction.save
character
default:"harmony"
Name under which the corrected embedding is stored in the Seurat object.

Build docs developers (and LLMs) love

Get started for freeTalk to us