# Quick start to Harmony

# 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 from CRAN with standard commands.

Code

    install.packages('harmony')

Once Harmony is installed, load it up!

Code

    library(harmony)

# 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.

- support.10xgenomics.com/single-cell-gene-expression/datasets/1.1.0/jurkat
- support.10xgenomics.com/single-cell-gene-expression/datasets/1.1.0/293t
- support.10xgenomics.com/single-cell-gene-expression/datasets/1.1.0/jurkat:293t_50:50

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.

Code

    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).

Code

    library(ggplot2)

    do_scatter <- function(xy, meta_data, label_name, base_size = 12) {
        palette_use <- c(`jurkat` = '#810F7C', `t293` = '#D09E2D',`half` = '#006D2C')
        xy <- xy[, 1:2]
        colnames(xy) <- c('X1', 'X2')
        plt_df <- xy %>% data.frame() %>% cbind(meta_data)
        plt <- ggplot(plt_df, aes(X1, X2, col = !!rlang::sym(label_name), fill = !!rlang::sym(label_name))) +
            theme_test(base_size = base_size) +
            guides(color = guide_legend(override.aes = list(stroke = 1, alpha = 1,
                                                            shape = 16, size = 4))) +
            scale_color_manual(values = palette_use) +
            scale_fill_manual(values = palette_use) +
            theme(plot.title = element_text(hjust = .5)) +
            labs(x = "PC 1", y = "PC 2") +
            theme(legend.position = "none") +
            geom_point(shape = '.')

        ## Add labels
        data_labels <- plt_df %>%
            dplyr::group_by(!!rlang::sym(label_name)) %>%
            dplyr::summarise(X1 = mean(X1), X2 = mean(X2)) %>%
            dplyr::ungroup()
        plt + geom_label(data = data_labels, aes(label = !!rlang::sym(label_name)),
                                color = "white", size = 4)
    }
    p1 <- do_scatter(V, meta_data, 'dataset') +
        labs(title = 'Colored by dataset')
    p2 <- do_scatter(V, meta_data, 'cell_type') +
        labs(title = 'Colored by cell type')

    cowplot::plot_grid(p1, p2)

Let’s run Harmony to remove the influence of dataset-of-origin from the cell embeddings.

Code

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

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

Code

    p1 <- do_scatter(harmony_embeddings, meta_data, 'dataset') +
        labs(title = 'Colored by dataset')
    p2 <- do_scatter(harmony_embeddings, meta_data, 'cell_type') +
        labs(title = 'Colored by cell type')
    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. For these vignettes, please visit our github page.

## 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

Code

    sessionInfo()

    ## R version 4.5.2 (2025-10-31)
    ## Platform: x86_64-conda-linux-gnu
    ## Running under: Arch Linux
    ##
    ## Matrix products: default
    ## BLAS/LAPACK: /home/main/miniconda3/envs/R2026/lib/libopenblasp-r0.3.30.so;  LAPACK version 3.12.0
    ##
    ## locale:
    ##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    ##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=C
    ##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    ##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    ##  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    ## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    ##
    ## time zone: America/New_York
    ## tzcode source: system (glibc)
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ##  [1] patchwork_1.3.2    ggrepel_0.9.6      ggthemes_5.2.0     lubridate_1.9.4
    ##  [5] forcats_1.0.1      stringr_1.6.0      purrr_1.2.1        readr_2.1.6
    ##  [9] tidyr_1.3.2        tibble_3.3.1       ggplot2_4.0.1      tidyverse_2.0.0
    ## [13] data.table_1.17.8  future_1.69.0      cowplot_1.2.0      dplyr_1.1.4
    ## [17] Seurat_5.4.0       SeuratObject_5.3.0 sp_2.2-0           harmony_2.0.3
    ## [21] Rcpp_1.1.1
    ##
    ## loaded via a namespace (and not attached):
    ##   [1] RColorBrewer_1.1-3     jsonlite_2.0.0         magrittr_2.0.4
    ##   [4] spatstat.utils_3.2-1   ggbeeswarm_0.7.3       farver_2.1.2
    ##   [7] rmarkdown_2.30         vctrs_0.7.1            ROCR_1.0-12
    ##  [10] spatstat.explore_3.7-0 htmltools_0.5.9        sass_0.4.10
    ##  [13] sctransform_0.4.3      parallelly_1.46.1      KernSmooth_2.23-26
    ##  [16] bslib_0.9.0            htmlwidgets_1.6.4      ica_1.0-3
    ##  [19] plyr_1.8.9             plotly_4.12.0          zoo_1.8-15
    ##  [22] cachem_1.1.0           igraph_2.1.4           mime_0.13
    ##  [25] lifecycle_1.0.5        pkgconfig_2.0.3        Matrix_1.7-4
    ##  [28] R6_2.6.1               fastmap_1.2.0          fitdistrplus_1.2-6
    ##  [31] shiny_1.12.1           digest_0.6.39          tensor_1.5.1
    ##  [34] RSpectra_0.16-2        irlba_2.3.5.1          labeling_0.4.3
    ##  [37] progressr_0.18.0       spatstat.sparse_3.1-0  timechange_0.3.0
    ##  [40] httr_1.4.7             polyclip_1.10-7        abind_1.4-8
    ##  [43] compiler_4.5.2         withr_3.0.2            S7_0.2.1
    ##  [46] fastDummies_1.7.5      MASS_7.3-65            tools_4.5.2
    ##  [49] vipor_0.4.7            lmtest_0.9-40          otel_0.2.0
    ##  [52] beeswarm_0.4.0         httpuv_1.6.16          future.apply_1.20.1
    ##  [55] goftest_1.2-3          glue_1.8.0             nlme_3.1-168
    ##  [58] promises_1.5.0         grid_4.5.2             Rtsne_0.17
    ##  [61] cluster_2.1.8.1        reshape2_1.4.5         generics_0.1.4
    ##  [64] gtable_0.3.6           spatstat.data_3.1-9    tzdb_0.5.0
    ##  [67] hms_1.1.4              spatstat.geom_3.7-0    RcppAnnoy_0.0.23
    ##  [70] RANN_2.6.2             pillar_1.11.1          spam_2.11-3
    ##  [73] RcppHNSW_0.6.0         later_1.4.5            splines_4.5.2
    ##  [76] lattice_0.22-7         survival_3.8-6         deldir_2.0-4
    ##  [79] tidyselect_1.2.1       miniUI_0.1.2           pbapply_1.7-4
    ##  [82] knitr_1.51             gridExtra_2.3          scattermore_1.2
    ##  [85] RhpcBLASctl_0.23-42    xfun_0.56              matrixStats_1.5.0
    ##  [88] stringi_1.8.7          lazyeval_0.2.2         yaml_2.3.12
    ##  [91] evaluate_1.0.5         codetools_0.2-20       cli_3.6.5
    ##  [94] uwot_0.2.4             xtable_1.8-4           reticulate_1.44.1
    ##  [97] jquerylib_0.1.4        globals_0.18.0         spatstat.random_3.4-4
    ## [100] png_0.1-8              ggrastr_1.0.2          spatstat.univar_3.1-6
    ## [103] parallel_4.5.2         dotCall64_1.2          listenv_0.10.0
    ## [106] viridisLite_0.4.2      scales_1.4.0           ggridges_0.5.7
    ## [109] rlang_1.1.7