System requirements

Harmony has been tested on R versions >= 4.2. Please consult the DESCRIPTION file for more details on required R packages. Harmony has been tested on Linux, OS X, and Windows platforms.

Installation

To run Harmony, open R and install harmony from CRAN (15 seconds):

install.packages("harmony")

If you’d like the latest development version, install from this github directly:

devtools::install_github("immunogenomics/harmony", build_vignettes=TRUE)

Usage

Harmony is designed to be user-friendly and supports some SingleCellExperiment and Seurat R analysis pipelines. Alternatively, it can be used in standalone mode.

Quick Start

Standalone Mode

Check out this vignette for a quick start tutorial which demonstrates the usage of the tool in standalone mode (~4 seconds).

At minimum the following parameters need to be specified to achieve an integration. For a few samples < 100K cells integration should finish within seconds.

library(harmony)
my_harmony_embeddings <- RunHarmony(my_pca_embeddings, meta_data, "dataset")

Seurat Objects

By default, the harmony API works on Seurats PCA cell embeddings and corrects them. You can run Harmony within your Seurat workflow with RunHarmony(). Prior RunHarmony() the PCA cell embeddings need to be precomputed through Seurat’s API. For downstream analyses, use the harmony embeddings instead of pca.

For example, the following snippet run Harmony and then calculates UMAP of the corrected input embeddings:

seuratObj <- RunHarmony(seuratObj, "dataset")
seuratObj <- RunUMAP(seuratObj, reduction = "harmony")

For a more detailed overview of the RunHarmony() Seurat interface check, the Seurat vignette

Harmony with two or more covariates

Harmony can integrate over multiple covariates. To do this, specify a vector covariates to integrate.

my_harmony_embeddings <- RunHarmony(
  my_pca_embeddings, meta_data, c("dataset", "donor", "batch_id")
)

Do the same with your Seurat object:

seuratObject <- RunHarmony(seuratObject, c("dataset", "donor", "batch_id"))

Advanced tutorial

The examples above all return integrated PCA embeddings. We created a detailed walkthrough that explores the internal data structures and mechanics of the Harmony algorithm.

Performance Notes

OpenBLAS will make a huge performance difference. If you are not using this version of BLAS have a look at the PERFORMANCE.md

If you are using R in windows, to use OpenBLAS you need to modify build flags. PERFORMANCE.md will show you how to increase the performance.

To get the most performance with large datasets (>10M cells) see the OpenMP notes in PERFORMANCE.md.