Introduction to scAnnotatR

Vy Nguyen

2021-10-27

Introduction

scAnnotatR is an R package for cell type prediction on single cell RNA-sequencing data. Currently, this package supports data in the forms of a Seurat object or a SingleCellExperiment object.

More information about Seurat object can be found here: https://satijalab.org/seurat/ More information about SingleCellExperiment object can be found here: https://osca.bioconductor.org/

scAnnotatR provides 2 main features:

Installation

The scAnnotatR package can be directly installed from Bioconductor:

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

if (!require(scAnnotatR))
  BiocManager::install("scAnnotatR")

For more information, see https://bioconductor.org/install/.

Included models

The scAnnotatR package comes with several pre-trained models to classify cell types.

# load scAnnotatR into working space
library(scAnnotatR)
#> Loading required package: Seurat
#> Attaching SeuratObject
#> Loading required package: SingleCellExperiment
#> Loading required package: SummarizedExperiment
#> Loading required package: MatrixGenerics
#> Loading required package: matrixStats
#> 
#> Attaching package: 'MatrixGenerics'
#> The following objects are masked from 'package:matrixStats':
#> 
#>     colAlls, colAnyNAs, colAnys, colAvgsPerRowSet, colCollapse,
#>     colCounts, colCummaxs, colCummins, colCumprods, colCumsums,
#>     colDiffs, colIQRDiffs, colIQRs, colLogSumExps, colMadDiffs,
#>     colMads, colMaxs, colMeans2, colMedians, colMins, colOrderStats,
#>     colProds, colQuantiles, colRanges, colRanks, colSdDiffs, colSds,
#>     colSums2, colTabulates, colVarDiffs, colVars, colWeightedMads,
#>     colWeightedMeans, colWeightedMedians, colWeightedSds,
#>     colWeightedVars, rowAlls, rowAnyNAs, rowAnys, rowAvgsPerColSet,
#>     rowCollapse, rowCounts, rowCummaxs, rowCummins, rowCumprods,
#>     rowCumsums, rowDiffs, rowIQRDiffs, rowIQRs, rowLogSumExps,
#>     rowMadDiffs, rowMads, rowMaxs, rowMeans2, rowMedians, rowMins,
#>     rowOrderStats, rowProds, rowQuantiles, rowRanges, rowRanks,
#>     rowSdDiffs, rowSds, rowSums2, rowTabulates, rowVarDiffs, rowVars,
#>     rowWeightedMads, rowWeightedMeans, rowWeightedMedians,
#>     rowWeightedSds, rowWeightedVars
#> Loading required package: GenomicRanges
#> Loading required package: stats4
#> Loading required package: BiocGenerics
#> 
#> Attaching package: 'BiocGenerics'
#> The following objects are masked from 'package:stats':
#> 
#>     IQR, mad, sd, var, xtabs
#> The following objects are masked from 'package:base':
#> 
#>     Filter, Find, Map, Position, Reduce, anyDuplicated, append,
#>     as.data.frame, basename, cbind, colnames, dirname, do.call,
#>     duplicated, eval, evalq, get, grep, grepl, intersect, is.unsorted,
#>     lapply, mapply, match, mget, order, paste, pmax, pmax.int, pmin,
#>     pmin.int, rank, rbind, rownames, sapply, setdiff, sort, table,
#>     tapply, union, unique, unsplit, which.max, which.min
#> Loading required package: S4Vectors
#> 
#> Attaching package: 'S4Vectors'
#> The following objects are masked from 'package:base':
#> 
#>     I, expand.grid, unname
#> Loading required package: IRanges
#> Loading required package: GenomeInfoDb
#> Loading required package: Biobase
#> Welcome to Bioconductor
#> 
#>     Vignettes contain introductory material; view with
#>     'browseVignettes()'. To cite Bioconductor, see
#>     'citation("Biobase")', and for packages 'citation("pkgname")'.
#> 
#> Attaching package: 'Biobase'
#> The following object is masked from 'package:MatrixGenerics':
#> 
#>     rowMedians
#> The following objects are masked from 'package:matrixStats':
#> 
#>     anyMissing, rowMedians
#> 
#> Attaching package: 'SummarizedExperiment'
#> The following object is masked from 'package:SeuratObject':
#> 
#>     Assays
#> The following object is masked from 'package:Seurat':
#> 
#>     Assays

The models are stored in the default_models object:

default_models <- load_models("default")
#> snapshotDate(): 2021-10-20
#> downloading 1 resources
#> retrieving 1 resource
#> loading from cache
names(default_models)
#>  [1] "B cells"           "Plasma cells"      "NK"               
#>  [4] "CD16 NK"           "CD56 NK"           "T cells"          
#>  [7] "CD4 T cells"       "CD8 T cells"       "Treg"             
#> [10] "NKT"               "ILC"               "Monocytes"        
#> [13] "CD14 Mono"         "CD16 Mono"         "DC"               
#> [16] "pDC"               "Endothelial cells" "LEC"              
#> [19] "VEC"               "Platelets"         "RBC"              
#> [22] "Melanocyte"        "Schwann cells"     "Pericytes"        
#> [25] "Mast cells"        "Keratinocytes"     "alpha"            
#> [28] "beta"              "delta"             "gamma"            
#> [31] "acinar"            "ductal"            "Fibroblasts"

The default_models object is named a list of classifiers. Each classifier is an instance of the scAnnotatR S4 class. For example:

default_models[['B cells']]
#> An object of class scAnnotatR for B cells 
#> * 31 marker genes applied: CD38, CD79B, CD74, CD84, RASGRP2, TCF3, SP140, MEF2C, DERL3, CD37, CD79A, POU2AF1, MVK, CD83, BACH2, LY86, CD86, SDC1, CR2, LRMP, VPREB3, IL2RA, BLK, IRF8, FLI1, MS4A1, CD14, MZB1, PTEN, CD19, MME 
#> * Predicting probability threshold: 0.5 
#> * No parent model

Basic pipeline to identify cell types in a scRNA-seq dataset using scAnnotatR

Preparing the data

To identify cell types available in a dataset, we need to load the dataset as Seurat or SingleCellExperiment object.

For this vignette, we use a small sample datasets that is available as a Seurat object as part of the package.

The example dataset already contains the clustering results as part of the metadata. This is not necessary for the classification process.

Cell classification

To launch cell type identification, we simply call the classify_cells function. A detailed description of all parameters can be found through the function’s help page ?classify_cells.

Here we use only 3 classifiers for B cells, T cells and NK cells to reduce computational cost of this vignette. If users want to use all pretrained classifiers on their dataset, cell_types = 'all' can be used.

Parameters

  • The option cell_types = ‘all’ tells the function to use all available cell classification models. Alternatively, we can limit the identifiable cell types:
    • by specifying: cell_types = c('B cells', 'T cells')
    • or by indicating the applicable classifier using the classifiers option: classifiers = c(default_models[['B cells']], default_models[['T cells']])
  • The option path_to_models = ‘default’ is to automatically use the package-integrated pretrained models (without loading the models into the current working space). This option can be used to load a local database instead. For more details see the vignettes on training your own classifiers.

Result interpretation

The classify_cells function returns the input object but with additional columns in the metadata table.

# display the additional metadata fields
seurat.obj[[]][c(50:60), c(8:ncol(seurat.obj[[]]))]
#>                                            B_cells_p B_cells_class      NK_p
#> cy80.Cd45.pos.PD1.pos.B09.S45.comb       0.007754246            no 0.4881285
#> cy80.Cd45.pos.Pd1.neg.S366.H06.S366.comb 0.999385770           yes 0.4440553
#> cy80.Cd45.pos.Pd1.neg.S202.A10.S202.comb 0.998317662           yes 0.4416114
#> cy80.Cd45.pos.Pd1.neg.S201.A09.S201.comb 0.997774856           yes 0.4398997
#> cy80.Cd45.pos.Pd1.neg.S221.B05.S221.comb 0.998874031           yes 0.4541005
#> cy80.Cd45.pos.PD1.pos.A03.S15.comb       0.999944282           yes 0.4511450
#> cy80.Cd45.pos.PD1.pos.B11.S47.comb       0.015978230            no 0.4841041
#> cy80.Cd45.pos.PD1.pos.S189.H09.S189.comb 0.099311534            no 0.4858084
#> cy80.Cd45.pos.PD1.pos.A05.S17.comb       0.055754074            no 0.4924746
#> cy80.Cd45.pos.PD1.pos.C02.S62.comb       0.048558881            no 0.5002238
#> cy80.Cd45.pos.PD1.pos.D12.S96.comb       0.996979702           yes 0.4994867
#>                                          NK_class  T_cells_p T_cells_class
#> cy80.Cd45.pos.PD1.pos.B09.S45.comb             no 0.94205232           yes
#> cy80.Cd45.pos.Pd1.neg.S366.H06.S366.comb       no 0.11269306            no
#> cy80.Cd45.pos.Pd1.neg.S202.A10.S202.comb       no 0.09834696            no
#> cy80.Cd45.pos.Pd1.neg.S201.A09.S201.comb       no 0.22256938            no
#> cy80.Cd45.pos.Pd1.neg.S221.B05.S221.comb       no 0.12903487            no
#> cy80.Cd45.pos.PD1.pos.A03.S15.comb             no 0.27242536            no
#> cy80.Cd45.pos.PD1.pos.B11.S47.comb             no 0.94929624           yes
#> cy80.Cd45.pos.PD1.pos.S189.H09.S189.comb       no 0.93390248           yes
#> cy80.Cd45.pos.PD1.pos.A05.S17.comb             no 0.98161289           yes
#> cy80.Cd45.pos.PD1.pos.C02.S62.comb            yes 0.96436674           yes
#> cy80.Cd45.pos.PD1.pos.D12.S96.comb             no 0.94848597           yes
#>                                          predicted_cell_type
#> cy80.Cd45.pos.PD1.pos.B09.S45.comb                   T cells
#> cy80.Cd45.pos.Pd1.neg.S366.H06.S366.comb             B cells
#> cy80.Cd45.pos.Pd1.neg.S202.A10.S202.comb             B cells
#> cy80.Cd45.pos.Pd1.neg.S201.A09.S201.comb             B cells
#> cy80.Cd45.pos.Pd1.neg.S221.B05.S221.comb             B cells
#> cy80.Cd45.pos.PD1.pos.A03.S15.comb                   B cells
#> cy80.Cd45.pos.PD1.pos.B11.S47.comb                   T cells
#> cy80.Cd45.pos.PD1.pos.S189.H09.S189.comb             T cells
#> cy80.Cd45.pos.PD1.pos.A05.S17.comb                   T cells
#> cy80.Cd45.pos.PD1.pos.C02.S62.comb                NK/T cells
#> cy80.Cd45.pos.PD1.pos.D12.S96.comb           B cells/T cells
#>                                          most_probable_cell_type
#> cy80.Cd45.pos.PD1.pos.B09.S45.comb                       T cells
#> cy80.Cd45.pos.Pd1.neg.S366.H06.S366.comb                 B cells
#> cy80.Cd45.pos.Pd1.neg.S202.A10.S202.comb                 B cells
#> cy80.Cd45.pos.Pd1.neg.S201.A09.S201.comb                 B cells
#> cy80.Cd45.pos.Pd1.neg.S221.B05.S221.comb                 B cells
#> cy80.Cd45.pos.PD1.pos.A03.S15.comb                       B cells
#> cy80.Cd45.pos.PD1.pos.B11.S47.comb                       T cells
#> cy80.Cd45.pos.PD1.pos.S189.H09.S189.comb                 T cells
#> cy80.Cd45.pos.PD1.pos.A05.S17.comb                       T cells
#> cy80.Cd45.pos.PD1.pos.C02.S62.comb                       T cells
#> cy80.Cd45.pos.PD1.pos.D12.S96.comb                       B cells

New columns are:

Result visualization

The predicted cell types can now simply be visualized using the matching plotting functions. In this example, we use Seurat’s DimPlot function:

With the current number of cell classifiers, we identify cells belonging to 2 cell types (B cells and T cells) and to 2 subtypes of T cells (CD4+ T cells and CD8+ T cells). The other cells (red points) are not among the cell types that can be classified by the predefined classifiers. Hence, they have an empty label.

For a certain cell type, users can also view the prediction probability. Here we show an example of B cell prediction probability:

Cells predicted to be B cells with higher probability have darker color, while the lighter color shows lower or even zero probability of a cell to be B cells. For B cell classifier, the threshold for prediction probability is currently at 0.5, which means cells having prediction probability at 0.5 or above will be predicted as B cells.

The automatic cell identification by scAnnotatR matches the traditional cell assignment, ie. the approach based on cell canonical marker expression. Taking a simple example, we use CD19 and CD20 (MS4A1) to identify B cells:

We see that the marker expression of B cells exactly overlaps the B cell prediction made by scAnnotatR.

Session Info

sessionInfo()
#> R Under development (unstable) (2021-10-19 r81077)
#> Platform: x86_64-pc-linux-gnu (64-bit)
#> Running under: Ubuntu 20.04.3 LTS
#> 
#> Matrix products: default
#> BLAS:   /home/biocbuild/bbs-3.15-bioc/R/lib/libRblas.so
#> LAPACK: /home/biocbuild/bbs-3.15-bioc/R/lib/libRlapack.so
#> 
#> 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       
#> 
#> attached base packages:
#> [1] stats4    stats     graphics  grDevices utils     datasets  methods  
#> [8] base     
#> 
#> other attached packages:
#>  [1] scAnnotatR_1.1.0            SingleCellExperiment_1.17.0
#>  [3] SummarizedExperiment_1.25.0 Biobase_2.55.0             
#>  [5] GenomicRanges_1.47.1        GenomeInfoDb_1.31.0        
#>  [7] IRanges_2.29.0              S4Vectors_0.33.0           
#>  [9] BiocGenerics_0.41.0         MatrixGenerics_1.7.0       
#> [11] matrixStats_0.61.0          SeuratObject_4.0.2         
#> [13] Seurat_4.0.5               
#> 
#> loaded via a namespace (and not attached):
#>   [1] utf8_1.2.2                    reticulate_1.22              
#>   [3] tidyselect_1.1.1              RSQLite_2.2.8                
#>   [5] AnnotationDbi_1.57.0          htmlwidgets_1.5.4            
#>   [7] grid_4.2.0                    Rtsne_0.15                   
#>   [9] pROC_1.18.0                   munsell_0.5.0                
#>  [11] codetools_0.2-18              ica_1.0-2                    
#>  [13] future_1.22.1                 miniUI_0.1.1.1               
#>  [15] withr_2.4.2                   colorspace_2.0-2             
#>  [17] filelock_1.0.2                highr_0.9                    
#>  [19] knitr_1.36                    ROCR_1.0-11                  
#>  [21] tensor_1.5                    listenv_0.8.0                
#>  [23] labeling_0.4.2                GenomeInfoDbData_1.2.7       
#>  [25] polyclip_1.10-0               bit64_4.0.5                  
#>  [27] farver_2.1.0                  parallelly_1.28.1            
#>  [29] vctrs_0.3.8                   generics_0.1.1               
#>  [31] ipred_0.9-12                  xfun_0.27                    
#>  [33] BiocFileCache_2.3.0           R6_2.5.1                     
#>  [35] bitops_1.0-7                  spatstat.utils_2.2-0         
#>  [37] cachem_1.0.6                  DelayedArray_0.21.0          
#>  [39] assertthat_0.2.1              promises_1.2.0.1             
#>  [41] scales_1.1.1                  nnet_7.3-16                  
#>  [43] gtable_0.3.0                  globals_0.14.0               
#>  [45] goftest_1.2-3                 timeDate_3043.102            
#>  [47] rlang_0.4.12                  splines_4.2.0                
#>  [49] lazyeval_0.2.2                ModelMetrics_1.2.2.2         
#>  [51] spatstat.geom_2.3-0           BiocManager_1.30.16          
#>  [53] yaml_2.2.1                    reshape2_1.4.4               
#>  [55] abind_1.4-5                   httpuv_1.6.3                 
#>  [57] caret_6.0-90                  tools_4.2.0                  
#>  [59] lava_1.6.10                   ggplot2_3.3.5                
#>  [61] ellipsis_0.3.2                spatstat.core_2.3-0          
#>  [63] jquerylib_0.1.4               RColorBrewer_1.1-2           
#>  [65] proxy_0.4-26                  ggridges_0.5.3               
#>  [67] Rcpp_1.0.7                    plyr_1.8.6                   
#>  [69] zlibbioc_1.41.0               purrr_0.3.4                  
#>  [71] RCurl_1.98-1.5                rpart_4.1-15                 
#>  [73] deldir_1.0-6                  pbapply_1.5-0                
#>  [75] cowplot_1.1.1                 zoo_1.8-9                    
#>  [77] ggrepel_0.9.1                 cluster_2.1.2                
#>  [79] magrittr_2.0.1                data.table_1.14.2            
#>  [81] scattermore_0.7               lmtest_0.9-38                
#>  [83] RANN_2.6.1                    fitdistrplus_1.1-6           
#>  [85] patchwork_1.1.1               mime_0.12                    
#>  [87] evaluate_0.14                 xtable_1.8-4                 
#>  [89] gridExtra_2.3                 compiler_4.2.0               
#>  [91] tibble_3.1.5                  KernSmooth_2.23-20           
#>  [93] crayon_1.4.1                  htmltools_0.5.2              
#>  [95] mgcv_1.8-38                   later_1.3.0                  
#>  [97] tidyr_1.1.4                   lubridate_1.8.0              
#>  [99] DBI_1.1.1                     dbplyr_2.1.1                 
#> [101] MASS_7.3-54                   rappdirs_0.3.3               
#> [103] data.tree_1.0.0               Matrix_1.3-4                 
#> [105] parallel_4.2.0                gower_0.2.2                  
#> [107] igraph_1.2.7                  pkgconfig_2.0.3              
#> [109] plotly_4.10.0                 spatstat.sparse_2.0-0        
#> [111] recipes_0.1.17                foreach_1.5.1                
#> [113] bslib_0.3.1                   XVector_0.35.0               
#> [115] prodlim_2019.11.13            stringr_1.4.0                
#> [117] digest_0.6.28                 sctransform_0.3.2            
#> [119] RcppAnnoy_0.0.19              spatstat.data_2.1-0          
#> [121] Biostrings_2.63.0             rmarkdown_2.11               
#> [123] leiden_0.3.9                  uwot_0.1.10                  
#> [125] curl_4.3.2                    kernlab_0.9-29               
#> [127] shiny_1.7.1                   lifecycle_1.0.1              
#> [129] nlme_3.1-153                  jsonlite_1.7.2               
#> [131] viridisLite_0.4.0             fansi_0.5.0                  
#> [133] pillar_1.6.4                  lattice_0.20-45              
#> [135] KEGGREST_1.35.0               fastmap_1.1.0                
#> [137] httr_1.4.2                    survival_3.2-13              
#> [139] interactiveDisplayBase_1.33.0 glue_1.4.2                   
#> [141] png_0.1-7                     iterators_1.0.13             
#> [143] BiocVersion_3.15.0            bit_4.0.4                    
#> [145] class_7.3-19                  stringi_1.7.5                
#> [147] sass_0.4.0                    blob_1.2.2                   
#> [149] AnnotationHub_3.3.0           memoise_2.0.0                
#> [151] dplyr_1.0.7                   irlba_2.3.3                  
#> [153] e1071_1.7-9                   future.apply_1.8.1           
#> [155] ape_5.5