Chapter 1 Introduction

1.1 Motivation

The Bioconductor package SingleR implements an automatic annotation method for single-cell RNA sequencing (scRNA-seq) data (Aran et al. 2019). Given a reference dataset of samples (single-cell or bulk) with known labels, it assigns those labels to new cells from a test dataset based on similarities in their expression profiles. This provides a convenient way of transferring biological knowledge across datasets, allowing users to leverage the domain expertise implicit in the creation of each reference. The most common application of SingleR involves predicting cell type (or “state”, or “kind”) in a new dataset, a process that is facilitated by the availability of curated references and compatibility with user-supplied datasets. In this manner, the burden of manually interpreting clusters and defining marker genes only has to be done once, for the reference dataset, and this knowledge can be propagated to new datasets in an automated manner.

1.2 Method description

SingleR can be considered a robust variant of nearest-neighbors classification, with some tweaks to improve resolution for closely related labels. For each test cell:

  1. We compute the Spearman correlation between its expression profile and that of each reference sample. The use of Spearman’s correlation provides a measure of robustness to batch effects across datasets. The calculation only uses the union of marker genes identified by pairwise comparisons between labels in the reference data, so as to improve resolution of separation between labels.
  2. We define the per-label score as a fixed quantile (by default, 0.8) of the correlations across all samples with that label. This accounts for differences in the number of reference samples for each label, which interferes with simpler flavors of nearest neighbor classification; it also avoids penalizing classifications to heterogeneous labels by only requiring a good match to a minority of samples.
  3. We repeat the score calculation for all labels in the reference dataset. The label with the highest score is used as SingleR’s prediction for this cell.
  4. We optionally perform a fine-tuning step to improve resolution between closely related labels. The reference dataset is subsetted to only include labels with scores close to the maximum; scores are recomputed using only marker genes for the subset of labels, thus focusing on the most relevant features; and this process is iterated until only one label remains.

1.3 Quick start

We will demonstrate the use of SingleR() on a well-known 10X Genomics dataset (Zheng et al. 2017) with the Human Primary Cell Atlas dataset (Mabbott et al. 2013) as the reference.

# Loading test data.
library(TENxPBMCData) <- TENxPBMCData("pbmc4k")

# Loading reference data with Ensembl annotations.
library(celldex) <- HumanPrimaryCellAtlasData(ensembl=TRUE)

# Performing predictions.
predictions <- SingleR(, assay.type.test=1,,$label.main)

##           B_cell              CMP               DC              GMP 
##              606                8                1                2 
##         Monocyte          NK_cell        Platelets Pre-B_cell_CD34- 
##             1164              217                3               46 
##          T_cells 
##             2293

And that’s it, really.

1.4 Where to get help

Questions on the general use of SingleR should be posted to the Bioconductor support site. Please send requests for general assistance and advice to the support site rather than to the individual authors. Bug reports or feature requests should be made to the GitHub repository; well-considered suggestions for improvements are always welcome.

Session information

R Under development (unstable) (2022-12-10 r83428)
Platform: x86_64-pc-linux-gnu (64-bit)
Running under: Ubuntu 22.04.1 LTS

Matrix products: default
BLAS:   /home/biocbuild/bbs-3.17-bioc/R/lib/ 
LAPACK: /usr/lib/x86_64-linux-gnu/lapack/

 [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
 [3] LC_TIME=en_GB              LC_COLLATE=C              
 [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
 [9] LC_ADDRESS=C               LC_TELEPHONE=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] SingleR_2.1.0               ensembldb_2.23.1           
 [3] AnnotationFilter_1.23.0     GenomicFeatures_1.51.4     
 [5] AnnotationDbi_1.61.0        celldex_1.9.0              
 [7] TENxPBMCData_1.17.0         HDF5Array_1.27.0           
 [9] rhdf5_2.43.0                DelayedArray_0.25.0        
[11] Matrix_1.5-3                SingleCellExperiment_1.21.0
[13] SummarizedExperiment_1.29.1 Biobase_2.59.0             
[15] GenomicRanges_1.51.4        GenomeInfoDb_1.35.10       
[17] IRanges_2.33.0              S4Vectors_0.37.3           
[19] BiocGenerics_0.45.0         MatrixGenerics_1.11.0      
[21] matrixStats_0.63.0          BiocStyle_2.27.0           
[23] rebook_1.9.0               

loaded via a namespace (and not attached):
  [1] DBI_1.1.3                     bitops_1.0-7                 
  [3] biomaRt_2.55.0                CodeDepends_0.6.5            
  [5] rlang_1.0.6                   magrittr_2.0.3               
  [7] compiler_4.3.0                RSQLite_2.2.20               
  [9] dir.expiry_1.7.0              DelayedMatrixStats_1.21.0    
 [11] png_0.1-8                     vctrs_0.5.1                  
 [13] ProtGenerics_1.31.0           stringr_1.5.0                
 [15] pkgconfig_2.0.3               crayon_1.5.2                 
 [17] fastmap_1.1.0                 dbplyr_2.2.1                 
 [19] XVector_0.39.0                ellipsis_0.3.2               
 [21] utf8_1.2.2                    Rsamtools_2.15.1             
 [23] promises_1.2.0.1              rmarkdown_2.19               
 [25] graph_1.77.1                  purrr_1.0.0                  
 [27] bit_4.0.5                     xfun_0.36                    
 [29] beachmat_2.15.0               zlibbioc_1.45.0              
 [31] cachem_1.0.6                  jsonlite_1.8.4               
 [33] progress_1.2.2                blob_1.2.3                   
 [35] later_1.3.0                   rhdf5filters_1.11.0          
 [37] BiocParallel_1.33.9           Rhdf5lib_1.21.0              
 [39] interactiveDisplayBase_1.37.0 irlba_2.3.5.1                
 [41] parallel_4.3.0                prettyunits_1.1.1            
 [43] R6_2.5.1                      bslib_0.4.2                  
 [45] stringi_1.7.8                 rtracklayer_1.59.1           
 [47] jquerylib_0.1.4               Rcpp_1.0.9                   
 [49] bookdown_0.31                 assertthat_0.2.1             
 [51] knitr_1.41                    httpuv_1.6.7                 
 [53] tidyselect_1.2.0              yaml_2.3.6                   
 [55] codetools_0.2-18              curl_4.3.3                   
 [57] lattice_0.20-45               tibble_3.1.8                 
 [59] shiny_1.7.4                   withr_2.5.0                  
 [61] KEGGREST_1.39.0               evaluate_0.19                
 [63] BiocFileCache_2.7.1           xml2_1.3.3                   
 [65] ExperimentHub_2.7.0           Biostrings_2.67.0            
 [67] pillar_1.8.1                  BiocManager_1.30.19          
 [69] filelock_1.0.2                generics_0.1.3               
 [71] RCurl_1.98-1.9                BiocVersion_3.17.1           
 [73] hms_1.1.2                     sparseMatrixStats_1.11.1     
 [75] xtable_1.8-4                  glue_1.6.2                   
 [77] lazyeval_0.2.2                tools_4.3.0                  
 [79] BiocIO_1.9.1                  AnnotationHub_3.7.0          
 [81] ScaledMatrix_1.7.0            GenomicAlignments_1.35.0     
 [83] XML_3.99-0.13                 grid_4.3.0                   
 [85] GenomeInfoDbData_1.2.9        BiocSingular_1.15.0          
 [87] restfulr_0.0.15               rsvd_1.0.5                   
 [89] cli_3.5.0                     rappdirs_0.3.3               
 [91] fansi_1.0.3                   dplyr_1.0.10                 
 [93] sass_0.4.4                    digest_0.6.31                
 [95] rjson_0.2.21                  memoise_2.0.1                
 [97] htmltools_0.5.4               lifecycle_1.0.3              
 [99] httr_1.4.4                    mime_0.12                    
[101] bit64_4.0.5                  


Aran, D., A. P. Looney, L. Liu, E. Wu, V. Fong, A. Hsu, S. Chak, et al. 2019. “Reference-based analysis of lung single-cell sequencing reveals a transitional profibrotic macrophage.” Nat. Immunol. 20 (2): 163–72.

Mabbott, Neil A., J. K. Baillie, Helen Brown, Tom C. Freeman, and David A. Hume. 2013. “An expression atlas of human primary cells: Inference of gene function from coexpression networks.” BMC Genomics 14.

Zheng, G. X., J. M. Terry, P. Belgrader, P. Ryvkin, Z. W. Bent, R. Wilson, S. B. Ziraldo, et al. 2017. “Massively parallel digital transcriptional profiling of single cells.” Nat Commun 8 (January): 14049.