1 Introduction

The TENxPBMCData package provides a R / Bioconductor resource for representing and manipulating nine different single-cell RNA-seq (scRNA-seq) and CITE-seq data sets on peripheral blood mononuclear cells (PBMC) generated by 10X Genomics:

  1. pbmc68k
  2. frozen_pbmc_donor_a
  3. frozen_pbmc_donor_b
  4. frozen_pbmc_donor_c
  5. pbmc33k
  6. pbmc3k
  7. pbmc6k
  8. pbmc4k
  9. pbmc8k
  10. pbmc5k-CITEseq

The number in the dataset title is roughly the number of cells in the experiment.

This package makes extensive use of the HDF5Array package to avoid loading the entire data set in memory, instead storing the counts on disk as a HDF5 file and loading subsets of the data into memory upon request.

Note: The purpose of this package is to provide testing and example data for Bioconductor packages. We have done no processing of the “filtered” 10X scRNA-RNA or CITE-seq data; it is delivered as is.

2 Work flow

2.1 Loading the data

We use the TENxPBMCData function to download the relevant files from Bioconductor’s ExperimentHub web resource. This includes the HDF5 file containing the counts, as well as the metadata on the rows (genes) and columns (cells). The output is a single SingleCellExperiment object from the SingleCellExperiment package. This is equivalent to a SummarizedExperiment class but with a number of features specific to single-cell data.

library(TENxPBMCData)
tenx_pbmc4k <- TENxPBMCData(dataset = "pbmc4k")
tenx_pbmc4k
## class: SingleCellExperiment 
## dim: 33694 4340 
## metadata(0):
## assays(1): counts
## rownames(33694): ENSG00000243485 ENSG00000237613 ... ENSG00000277475
##   ENSG00000268674
## rowData names(3): ENSEMBL_ID Symbol_TENx Symbol
## colnames: NULL
## colData names(11): Sample Barcode ... Individual Date_published
## reducedDimNames(0):
## mainExpName: NULL
## altExpNames(0):

Note: of particular interest to some users might be the pbmc68k dataset for its size.

The first call to TENxPBMCData() may take some time due to the need to download some moderately large files. The files are then stored locally such that ensuing calls in the same or new sessions are fast. Use the dataset argument to select which dataset to download; values are visible through the function definition:

args(TENxPBMCData)
## function (dataset = c("pbmc4k", "pbmc68k", "frozen_pbmc_donor_a", 
##     "frozen_pbmc_donor_b", "frozen_pbmc_donor_c", "pbmc33k", 
##     "pbmc3k", "pbmc6k", "pbmc8k", "pbmc5k-CITEseq"), as.sparse = TRUE) 
## NULL

The count matrix itself is represented as a DelayedMatrix from the DelayedArray package. This wraps the underlying HDF5 file in a container that can be manipulated in R. Each count represents the number of unique molecular identifiers (UMIs) assigned to a particular gene in a particular cell.

counts(tenx_pbmc4k)
## <33694 x 4340> sparse DelayedMatrix object of type "integer":
##                    [,1]    [,2]    [,3]    [,4] ... [,4337] [,4338] [,4339]
## ENSG00000243485       0       0       0       0   .       0       0       0
## ENSG00000237613       0       0       0       0   .       0       0       0
## ENSG00000186092       0       0       0       0   .       0       0       0
## ENSG00000238009       0       0       0       0   .       0       0       0
## ENSG00000239945       0       0       0       0   .       0       0       0
##             ...       .       .       .       .   .       .       .       .
## ENSG00000277856       0       0       0       0   .       0       0       0
## ENSG00000275063       0       0       0       0   .       0       0       0
## ENSG00000271254       0       0       0       0   .       0       0       0
## ENSG00000277475       0       0       0       0   .       0       0       0
## ENSG00000268674       0       0       0       0   .       0       0       0
##                 [,4340]
## ENSG00000243485       0
## ENSG00000237613       0
## ENSG00000186092       0
## ENSG00000238009       0
## ENSG00000239945       0
##             ...       .
## ENSG00000277856       0
## ENSG00000275063       0
## ENSG00000271254       0
## ENSG00000277475       0
## ENSG00000268674       0

2.2 Exploring the data

To quickly explore the data set, we compute some summary statistics on the count matrix. We tell the DelayedArray block size to indicate that we can use up to 1 GB of memory for loading the data into memory from disk.

options(DelayedArray.block.size=1e9)

We are interested in library sizes colSums(counts(tenx_pbmc4k)), number of genes expressed per cell colSums(counts(tenx_pbmc4k) != 0), and average expression across cells rowMeans(counts(tenx_pbmc4k)). A naive implement might be

lib.sizes <- colSums(counts(tenx_pbmc4k))
n.exprs <- colSums(counts(tenx_pbmc4k) != 0L)
ave.exprs <- rowMeans(counts(tenx_pbmc4k))

More advanced analysis procedures are implemented in various Bioconductor packages - see the SingleCell biocViews for more details.

2.3 Saving computations

Saving the tenx_pbmc4k object in a standard manner, e.g.,

destination <- tempfile()
saveRDS(tenx_pbmc4k, file = destination)

saves the row-, column-, and meta-data as an R object, and remembers the location and subset of the HDF5 file from which the object is derived. The object can be read into a new R session with readRDS(destination), provided the HDF5 file remains in it’s original location.

2.4 CITE-seq datasets

For CITE-seq datasets, both the transcriptomics data and the antibody capture data are available from a single SingleCellExperiment object. While the transcriptomics data can be accessed directly as described above, the antibody capture data should be accessed with the altExp function. Again, the resulting count matrix is represented as a DelayedMatrix.

tenx_pbmc5k_CITEseq <- TENxPBMCData(dataset = "pbmc5k-CITEseq")

counts(altExp(tenx_pbmc5k_CITEseq))
## <32 x 5247> sparse DelayedMatrix object of type "integer":
##           [,1]    [,2]    [,3]    [,4] ... [,5244] [,5245] [,5246] [,5247]
##    CD3      25     959     942     802   .     402     401       6    1773
##    CD4     164     720    1647    1666   .    1417       1      46    1903
##   CD8a      16       8      21       5   .       8     222       3       9
##  CD11b    3011      12      11      11   .      15       7    1027       9
##   CD14     696      12      13       9   .       9      17     382       8
##    ...       .       .       .       .   .       .       .       .       .
## HLA-DR     573      15      11      19   .       6      40     184      32
##  TIGIT      10       3       3       3   .       2      15       1      12
##   IgG1       4       4       2       4   .       1       0       2       4
##  IgG2a       1       3       0       6   .       4       0       4       2
##  IgG2b       6       2       4       8   .       0       0       2       5

3 Session information

sessionInfo()
## R version 4.3.1 (2023-06-16)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 22.04.3 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.18-bioc/R/lib/libRblas.so 
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_GB              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] stats4    stats     graphics  grDevices utils     datasets  methods  
## [8] base     
## 
## other attached packages:
##  [1] TENxPBMCData_1.20.0         HDF5Array_1.30.0           
##  [3] rhdf5_2.46.0                DelayedArray_0.28.0        
##  [5] SparseArray_1.2.0           S4Arrays_1.2.0             
##  [7] abind_1.4-5                 Matrix_1.6-1.1             
##  [9] SingleCellExperiment_1.24.0 SummarizedExperiment_1.32.0
## [11] Biobase_2.62.0              GenomicRanges_1.54.0       
## [13] GenomeInfoDb_1.38.0         IRanges_2.36.0             
## [15] S4Vectors_0.40.0            BiocGenerics_0.48.0        
## [17] MatrixGenerics_1.14.0       matrixStats_1.0.0          
## [19] knitr_1.44                  BiocStyle_2.30.0           
## 
## loaded via a namespace (and not attached):
##  [1] tidyselect_1.2.0              dplyr_1.1.3                  
##  [3] blob_1.2.4                    Biostrings_2.70.1            
##  [5] filelock_1.0.2                bitops_1.0-7                 
##  [7] fastmap_1.1.1                 RCurl_1.98-1.12              
##  [9] BiocFileCache_2.10.0          promises_1.2.1               
## [11] digest_0.6.33                 mime_0.12                    
## [13] lifecycle_1.0.3               ellipsis_0.3.2               
## [15] KEGGREST_1.42.0               interactiveDisplayBase_1.40.0
## [17] RSQLite_2.3.1                 magrittr_2.0.3               
## [19] compiler_4.3.1                rlang_1.1.1                  
## [21] sass_0.4.7                    tools_4.3.1                  
## [23] utf8_1.2.4                    yaml_2.3.7                   
## [25] bit_4.0.5                     curl_5.1.0                   
## [27] withr_2.5.1                   purrr_1.0.2                  
## [29] grid_4.3.1                    fansi_1.0.5                  
## [31] ExperimentHub_2.10.0          xtable_1.8-4                 
## [33] Rhdf5lib_1.24.0               cli_3.6.1                    
## [35] rmarkdown_2.25                crayon_1.5.2                 
## [37] generics_0.1.3                httr_1.4.7                   
## [39] DBI_1.1.3                     cachem_1.0.8                 
## [41] zlibbioc_1.48.0               AnnotationDbi_1.64.0         
## [43] BiocManager_1.30.22           XVector_0.42.0               
## [45] vctrs_0.6.4                   jsonlite_1.8.7               
## [47] bookdown_0.36                 bit64_4.0.5                  
## [49] jquerylib_0.1.4               glue_1.6.2                   
## [51] BiocVersion_3.18.0            later_1.3.1                  
## [53] tibble_3.2.1                  pillar_1.9.0                 
## [55] rappdirs_0.3.3                htmltools_0.5.6.1            
## [57] rhdf5filters_1.14.0           GenomeInfoDbData_1.2.11      
## [59] R6_2.5.1                      dbplyr_2.3.4                 
## [61] evaluate_0.22                 shiny_1.7.5.1                
## [63] lattice_0.22-5                AnnotationHub_3.10.0         
## [65] png_0.1-8                     memoise_2.0.1                
## [67] httpuv_1.6.12                 bslib_0.5.1                  
## [69] Rcpp_1.0.11                   xfun_0.40                    
## [71] pkgconfig_2.0.3