harmony

Harmony: Single-Cell Data Integration

Overview

Harmony is a fast and accurate method for integrating single-cell data from multiple batches, conditions, or modalities. It uses a soft clustering approach and iterative alignment to remove batch effects while preserving biological variation.

When to Use This Skill

This skill should be used when:

• Integrating single-cell datasets from multiple batches
• Removing technical variation while preserving biology
• Combining data from different sequencing technologies
• Integrating datasets with different cell type compositions
• Working with large datasets (scales well to millions of cells)
• Using R-based workflows (for Python, see scanorama or bbknn)

Quick Start

Installation

# Install from CRAN
install.packages("harmony")

# Or from GitHub
devtools::install_github("immunogenomics/harmony")

Basic Integration in Seurat

library(Seurat)
library(harmony)

# Load and preprocess each dataset
pbmc1 <- ReadH5AD("dataset1.h5ad")
pbmc2 <- ReadH5AD("dataset2.h5ad")

# Create combined object
pbmc.combined <- merge(pbmc1, y = pbmc2, add.cell.ids = c("batch1", "batch2"))

# Run standard Seurat pipeline
pbmc.combined <- NormalizeData(pbmc.combined)
pbmc.combined <- FindVariableFeatures(pbmc.combined)
pbmc.combined <- ScaleData(pbmc.combined)
pbmc.combined <- RunPCA(pbmc.combined, npcs = 30)

# Run Harmony integration
pbmc.combined <- RunHarmony(pbmc.combined, group.by.vars = "batch", reduction = "pca")

# Use Harmony reduction for clustering
pbmc.combined <- RunUMAP(pbmc.combined, reduction = "harmony", dims = 1:30)
pbmc.combined <- FindNeighbors(pbmc.combined, reduction = "harmony", dims = 1:30)
pbmc.combined <- FindClusters(pbmc.combined, resolution = 0.5)

# Visualize
DimPlot(pbmc.combined, reduction = "umap", group.by = "batch")
DimPlot(pbmc.combined, reduction = "umap", group.by = "seurat_clusters")

Parameters

RunHarmony Parameters

pbmc <- RunHarmony(
  object,                    # Seurat object
  group.by.vars,             # Variable(s) to integrate (batch)
  reduction = "pca",         # Reduction to use
  dims.use = NULL,          # Dimensions to use
  theta = 2,                # Clustering diversity parameter (higher = more diverse)
  lambda = 1,               # Regularization parameter
  sigma = 0.1,              # Smoothness penalty
  nclust = NULL,            # Number of clusters (NULL = auto)
  tau = 0,                  # Protection against over-clustering
  block.size = 0.05,        # Fraction of cells to update per iteration
  max.iter.harmony = 10,    # Maximum Harmony iterations
  max.iter.cluster = 20,    # Maximum clustering iterations
  epsilon.harmony = 1e-5,    # Convergence threshold
  epsilon.cluster = 1e-8,   # Cluster convergence threshold
  plot_convergence = FALSE   # Plot convergence
)