Introduction

Harmony is an algorithm for performing integration of single cell genomics datasets. Please check out our latest manuscript on Nature Methods.

Installation

Install Harmony with standard commands.

install.packages('harmony')

Once Harmony is installed, load it up!

library(harmony)

## Loading required package: Rcpp

Integrating cell line datasets from 10X

The example below follows Figure 2 in the manuscript.

We downloaded 3 cell line datasets from the 10X website. The first two (jurkat and 293t) come from pure cell lines while the half dataset is a 50:50 mixture of Jurkat and HEK293T cells. We inferred cell type with the canonical marker XIST, since the two cell lines come from 1 male and 1 female donor.

We library normalized the cells, log transformed the counts, and scaled the genes. Then we performed PCA and kept the top 20 PCs. The PCA embeddings and meta data are available as part of this package.

data(cell_lines)
V <- cell_lines$scaled_pcs
meta_data <- cell_lines$meta_data

Initially, the cells cluster by both dataset (left) and cell type (right).

p1 <- do_scatter(V, meta_data, 'dataset') + 
    labs(title = 'Colored by dataset')

## Warning: `group_by_()` is deprecated as of dplyr 0.7.0.
## Please use `group_by()` instead.
## See vignette('programming') for more help
## This warning is displayed once every 8 hours.
## Call `lifecycle::last_warnings()` to see where this warning was generated.

## Warning: Ignoring unknown parameters: segment.size

p2 <- do_scatter(V, meta_data, 'cell_type') + 
    labs(title = 'Colored by cell type')

## Warning: Ignoring unknown parameters: segment.size

cowplot::plot_grid(p1, p2)

Let’s run Harmony to remove the influence of dataset-of-origin from the embedding. By default, Harmony accepts a normalized gene expression matrix and performs PCA. Since here we already have the PCs, we specify do_pca=FALSE. The matrix harmony_embeddings is the matrix of Harmony corrected PCA embeddings.

harmony_embeddings <- harmony::HarmonyMatrix(
    V, meta_data, 'dataset', do_pca = FALSE, verbose=FALSE
)

After Harmony, the datasets are now mixed (left) and the cell types are still separate (right).

p1 <- do_scatter(harmony_embeddings, meta_data, 'dataset') + 
    labs(title = 'Colored by dataset')

## Warning: Ignoring unknown parameters: segment.size

p2 <- do_scatter(harmony_embeddings, meta_data, 'cell_type') + 
    labs(title = 'Colored by cell type')

## Warning: Ignoring unknown parameters: segment.size

cowplot::plot_grid(p1, p2, nrow = 1)

Next Steps

Interfacing to software packages

You can also run Harmony as part of an established pipeline in several packages, such as Seurat, MUDAN, and scran. For these vignettes, please visit our website.

Detailed breakdown of the Harmony algorithm

For more details on how each part of Harmony works, consult our more detailed vignette “Detailed Walkthrough of Harmony Algorithm”.

Session Info

sessionInfo()

## R version 4.0.3 (2020-10-10)
## Platform: x86_64-apple-darwin17.0 (64-bit)
## Running under: macOS Big Sur 10.16
## 
## Matrix products: default
## BLAS:   /Library/Frameworks/R.framework/Versions/4.0/Resources/lib/libRblas.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/4.0/Resources/lib/libRlapack.dylib
## 
## locale:
## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] harmony_0.1.0 Rcpp_1.0.6    ggplot2_3.3.3
## 
## loaded via a namespace (and not attached):
##  [1] highr_0.8        pillar_1.4.7     compiler_4.0.3   tools_4.0.3     
##  [5] digest_0.6.27    evaluate_0.14    lifecycle_0.2.0  tibble_3.0.5    
##  [9] gtable_0.3.0     pkgconfig_2.0.3  rlang_0.4.10     DBI_1.1.1       
## [13] yaml_2.2.1       xfun_0.23        withr_2.4.0      dplyr_1.0.3     
## [17] stringr_1.4.0    knitr_1.33       generics_0.1.0   vctrs_0.3.6     
## [21] grid_4.0.3       tidyselect_1.1.0 cowplot_1.1.1    glue_1.4.2      
## [25] R6_2.5.0         rmarkdown_2.8    tidyr_1.1.2      purrr_0.3.4     
## [29] farver_2.0.3     magrittr_2.0.1   scales_1.1.1     codetools_0.2-18
## [33] ellipsis_0.3.1   htmltools_0.5.1  assertthat_0.2.1 colorspace_2.0-0
## [37] labeling_0.4.2   stringi_1.5.3    munsell_0.5.0    crayon_1.3.4