options(SeuratData.repo.use = "http://satijalab04.nygenome.org")

In this vignette, we will combine two 10X PBMC datasets: one containing 4K cells and one containing 8K cells. The datasets can be found here.

To start, we read in the data and create two Seurat objects.

library(Seurat)
pbmc4k.data <- Read10X(data.dir = "../data/pbmc4k/filtered_gene_bc_matrices/GRCh38/")
pbmc4k <- CreateSeuratObject(counts = pbmc4k.data, project = "PBMC4K")
pbmc4k
## An object of class Seurat 
## 33694 features across 4340 samples within 1 assay 
## Active assay: RNA (33694 features, 0 variable features)
##  1 layer present: counts
pbmc8k.data <- Read10X(data.dir = "../data/pbmc8k/filtered_gene_bc_matrices/GRCh38/")
pbmc8k <- CreateSeuratObject(counts = pbmc8k.data, project = "PBMC8K")
pbmc8k
## An object of class Seurat 
## 33694 features across 8381 samples within 1 assay 
## Active assay: RNA (33694 features, 0 variable features)
##  1 layer present: counts

Merging Two Seurat Objects

merge() merges the raw count matrices of two Seurat objects and creates a new Seurat object with the resulting combined raw count matrix. To easily tell which original object any particular cell came from, you can set the add.cell.ids parameter with an c(x, y) vector, which will prepend the given identifier to the beginning of each cell name. The original project ID will remain stored in object meta data under orig.ident

pbmc.combined <- merge(pbmc4k, y = pbmc8k, add.cell.ids = c("4K", "8K"), project = "PBMC12K")
pbmc.combined
## An object of class Seurat 
## 33694 features across 12721 samples within 1 assay 
## Active assay: RNA (33694 features, 0 variable features)
##  2 layers present: counts.PBMC4K, counts.PBMC8K
# notice the cell names now have an added identifier
head(colnames(pbmc.combined))
## [1] "4K_AAACCTGAGAAGGCCT-1" "4K_AAACCTGAGACAGACC-1" "4K_AAACCTGAGATAGTCA-1"
## [4] "4K_AAACCTGAGCGCCTCA-1" "4K_AAACCTGAGGCATGGT-1" "4K_AAACCTGCAAGGTTCT-1"
table(pbmc.combined$orig.ident)
## 
## PBMC4K PBMC8K 
##   4340   8381

Merging More Than Two Seurat Objects

To merge more than two Seurat objects, simply pass a vector of multiple Seurat objects to the y parameter for merge; we’ll demonstrate this using the 4K and 8K PBMC datasets as well as our previously computed Seurat object from the 2,700 PBMC tutorial (loaded via the SeuratData package).

library(SeuratData)
InstallData("pbmc3k")
pbmc3k <- LoadData("pbmc3k", type = "pbmc3k.final")
pbmc3k
## An object of class Seurat 
## 13714 features across 2638 samples within 1 assay 
## Active assay: RNA (13714 features, 2000 variable features)
##  3 layers present: data, counts, scale.data
##  2 dimensional reductions calculated: pca, umap
pbmc.big <- merge(pbmc3k, y = c(pbmc4k, pbmc8k), add.cell.ids = c("3K", "4K", "8K"), project = "PBMC15K")
pbmc.big
## An object of class Seurat 
## 34230 features across 15359 samples within 1 assay 
## Active assay: RNA (34230 features, 2000 variable features)
##  5 layers present: data.pbmc3k, counts.pbmc3k, scale.data.pbmc3k, counts.PBMC4K, counts.PBMC8K
head(colnames(pbmc.big))
## [1] "3K_AAACATACAACCAC" "3K_AAACATTGAGCTAC" "3K_AAACATTGATCAGC"
## [4] "3K_AAACCGTGCTTCCG" "3K_AAACCGTGTATGCG" "3K_AAACGCACTGGTAC"
tail(colnames(pbmc.big))
## [1] "8K_TTTGTCAGTTACCGAT-1" "8K_TTTGTCATCATGTCCC-1" "8K_TTTGTCATCCGATATG-1"
## [4] "8K_TTTGTCATCGTCTGAA-1" "8K_TTTGTCATCTCGAGTA-1" "8K_TTTGTCATCTGCTTGC-1"
unique(sapply(X = strsplit(colnames(pbmc.big), split = "_"), FUN = "[", 1))
## [1] "3K" "4K" "8K"
table(pbmc.big$orig.ident)
## 
## pbmc3k PBMC4K PBMC8K 
##   2638   4340   8381

Merge Based on Normalized Data

By default, merge() will combine the Seurat objects based on the raw count matrices, erasing any previously normalized and scaled data matrices. If you want to merge the normalized data matrices as well as the raw count matrices, simply pass merge.data = TRUE. This should be done if the same normalization approach was applied to all objects.

pbmc4k <- NormalizeData(pbmc4k)
pbmc8k <- NormalizeData(pbmc8k)
pbmc.normalized <- merge(pbmc4k, y = pbmc8k, add.cell.ids = c("4K", "8K"), project = "PBMC12K",
    merge.data = TRUE)
LayerData(pbmc.combined)[1:10, 1:15]
## 10 x 15 sparse Matrix of class "dgCMatrix"
##                                            
## RP11-34P13.3  . . . . . . . . . . . . . . .
## FAM138A       . . . . . . . . . . . . . . .
## OR4F5         . . . . . . . . . . . . . . .
## RP11-34P13.7  . . . . . . . . . . . . . . .
## RP11-34P13.8  . . . . . . . . . . . . . . .
## RP11-34P13.14 . . . . . . . . . . . . . . .
## RP11-34P13.9  . . . . . . . . . . . . . . .
## FO538757.3    . . . . . . . . . . . . . . .
## FO538757.2    . . . . . . . . . 1 . . . . .
## AP006222.2    . . . . . . . . . . . 1 . . .
LayerData(pbmc.normalized)[1:10, 1:15]
## 10 x 15 sparse Matrix of class "dgCMatrix"
##                                                           
## RP11-34P13.3  . . . . . . . . . .         . .        . . .
## FAM138A       . . . . . . . . . .         . .        . . .
## OR4F5         . . . . . . . . . .         . .        . . .
## RP11-34P13.7  . . . . . . . . . .         . .        . . .
## RP11-34P13.8  . . . . . . . . . .         . .        . . .
## RP11-34P13.14 . . . . . . . . . .         . .        . . .
## RP11-34P13.9  . . . . . . . . . .         . .        . . .
## FO538757.3    . . . . . . . . . .         . .        . . .
## FO538757.2    . . . . . . . . . 0.7721503 . .        . . .
## AP006222.2    . . . . . . . . . .         . 1.087928 . . .
write.csv(x = t(as.data.frame(all_times)), file = "../output/timings/merge_vignette_times.csv")

Session Info

## R version 4.2.2 Patched (2022-11-10 r83330)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 20.04.6 LTS
## 
## Matrix products: default
## BLAS:   /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.9.0
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.9.0
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
##  [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       
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
##  [1] thp1.eccite.SeuratData_3.1.5  stxBrain.SeuratData_0.1.1    
##  [3] ssHippo.SeuratData_3.1.4      pbmcsca.SeuratData_3.0.0     
##  [5] pbmcMultiome.SeuratData_0.1.4 pbmc3k.SeuratData_3.1.4      
##  [7] panc8.SeuratData_3.0.2        ifnb.SeuratData_3.0.0        
##  [9] hcabm40k.SeuratData_3.0.0     cbmc.SeuratData_3.1.4        
## [11] bmcite.SeuratData_0.3.0       SeuratData_0.2.2.9001        
## [13] Seurat_5.0.0                  SeuratObject_5.0.0           
## [15] sp_2.1-1                     
## 
## loaded via a namespace (and not attached):
##   [1] spam_2.10-0            systemfonts_1.0.4      plyr_1.8.9            
##   [4] igraph_1.5.1           lazyeval_0.2.2         splines_4.2.2         
##   [7] RcppHNSW_0.5.0         listenv_0.9.0          scattermore_1.2       
##  [10] ggplot2_3.4.4          digest_0.6.33          htmltools_0.5.6.1     
##  [13] fansi_1.0.5            magrittr_2.0.3         memoise_2.0.1         
##  [16] tensor_1.5             cluster_2.1.4          ROCR_1.0-11           
##  [19] globals_0.16.2         matrixStats_1.0.0      R.utils_2.12.2        
##  [22] pkgdown_2.0.7          spatstat.sparse_3.0-3  colorspace_2.1-0      
##  [25] rappdirs_0.3.3         ggrepel_0.9.4          textshaping_0.3.6     
##  [28] xfun_0.40              dplyr_1.1.3            crayon_1.5.2          
##  [31] jsonlite_1.8.7         progressr_0.14.0       spatstat.data_3.0-3   
##  [34] survival_3.5-7         zoo_1.8-12             glue_1.6.2            
##  [37] polyclip_1.10-6        gtable_0.3.4           leiden_0.4.3          
##  [40] future.apply_1.11.0    abind_1.4-5            scales_1.2.1          
##  [43] spatstat.random_3.2-1  miniUI_0.1.1.1         Rcpp_1.0.11           
##  [46] viridisLite_0.4.2      xtable_1.8-4           reticulate_1.34.0     
##  [49] dotCall64_1.1-0        htmlwidgets_1.6.2      httr_1.4.7            
##  [52] RColorBrewer_1.1-3     ellipsis_0.3.2         ica_1.0-3             
##  [55] pkgconfig_2.0.3        R.methodsS3_1.8.2      sass_0.4.7            
##  [58] uwot_0.1.16            deldir_1.0-9           utf8_1.2.4            
##  [61] tidyselect_1.2.0       rlang_1.1.1            reshape2_1.4.4        
##  [64] later_1.3.1            munsell_0.5.0          tools_4.2.2           
##  [67] cachem_1.0.8           cli_3.6.1              generics_0.1.3        
##  [70] ggridges_0.5.4         evaluate_0.22          stringr_1.5.0         
##  [73] fastmap_1.1.1          yaml_2.3.7             ragg_1.2.5            
##  [76] goftest_1.2-3          knitr_1.45             fs_1.6.3              
##  [79] fitdistrplus_1.1-11    purrr_1.0.2            RANN_2.6.1            
##  [82] pbapply_1.7-2          future_1.33.0          nlme_3.1-162          
##  [85] mime_0.12              formatR_1.14           R.oo_1.25.0           
##  [88] compiler_4.2.2         plotly_4.10.3          png_0.1-8             
##  [91] spatstat.utils_3.0-4   tibble_3.2.1           bslib_0.5.1           
##  [94] stringi_1.7.12         desc_1.4.2             RSpectra_0.16-1       
##  [97] lattice_0.21-9         Matrix_1.6-1.1         vctrs_0.6.4           
## [100] pillar_1.9.0           lifecycle_1.0.4        spatstat.geom_3.2-7   
## [103] lmtest_0.9-40          jquerylib_0.1.4        RcppAnnoy_0.0.21      
## [106] data.table_1.14.8      cowplot_1.1.1          irlba_2.3.5.1         
## [109] httpuv_1.6.12          patchwork_1.1.3        R6_2.5.1              
## [112] promises_1.2.1         KernSmooth_2.23-22     gridExtra_2.3         
## [115] parallelly_1.36.0      codetools_0.2-19       fastDummies_1.7.3     
## [118] MASS_7.3-58.2          rprojroot_2.0.4        sctransform_0.4.1     
## [121] parallel_4.2.2         grid_4.2.2             tidyr_1.3.0           
## [124] rmarkdown_2.25         Rtsne_0.16             spatstat.explore_3.2-5
## [127] shiny_1.7.5.1