Training model classifying a cell subtype from scRNA-seq data
Introduction
Apart from a basic model for a basic independent cell type, our methods also supports cell types considered as the children of another cell type. In this case, the so-called parent cell type must already be represented by a classification model.
Here we consider the model classifying child cell type as child model and of course, parent model is used for classification of parent cell type.
Child model is used to distinguish a particular child cell type from other children cell types of the same parent. Therefore, our methods will examine all cells by parent model before training and testing for child model. Only cells that are considered as parent cell type will be used to train and test the new model.
The basis for this approach is that while markers that are very well suited to differentiate a CD4+ T cell from a CD8+ T cell, these markers may worsen the differentiation of a T cell vs. other cells.
Parent model
A first prerequisite of training for a child model is the parent model. A parent model is of class scAnnotatR and must be available in the working space, among default pretrained models of the package or among trained models in a user supplied database.
In this example, we load B cells classifier in the package default models to our working place.
# use BiocManager to install from Bioconductor
if (!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
# the scAnnotatR package
if (!require(scAnnotatR))
BiocManager::install("scAnnotatR")default_models <- load_models('default')
#> loading from cache
classifier_B <- default_models[['B cells']]
classifier_B
#> 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 modelPreparing train object and test object
Same as training for basic models, training for a child model also requires a train (Seurat/SCE) object and a test (Seurat/SCE) object. All objects must have a slot in meta data indicating the type of cells. Tag slot indicating parent cell type can also be provided. In this case, parent cell type tag will further be tested for coherence with the provided parent classifier.
Cell tagged as child cell type but incoherent to parent cell type will be removed from training and testing for the child cell type classifier.
In this vignette, we use the human lung dataset from Zilionis et al., 2019, which is available in the scRNAseq (2.4.0) library. The dataset is stored as a SCE object.
To start the training workflow, we first load the neccessary libraries.
# we use the scRNAseq package to load example data
if (!require(scRNAseq))
BiocManager::install("scRNAseq")First, we load the dataset. To reduce the computational complexity of this vignette, we only use the first 5000 cells of the dataset.
zilionis <- ZilionisLungData()
zilionis <- zilionis[, 1:5000]
# now we add simple colnames (= cell ids) to the dataset
# Note: This is normally not necessary
colnames(zilionis) <- paste0("Cell", 1:ncol(zilionis))We split this dataset into two parts, one for the training and the other for the testing.
pivot = ncol(zilionis)%/%2
train_set <- zilionis[, 1:pivot]
test_set <- zilionis[, (1+pivot):ncol(zilionis)]In this dataset, the cell type meta data is stored in the Most likely LM22 cell type slot of the SingleCellExperiment object (in both the train object and test object).
If the cell type is stored not stored as the default identification
(set through Idents for Seurat object) the slot must be set
as a parameter in the training and testing function (see below).
table(train_set$`Most likely LM22 cell type`)
#>
#> B cells memory B cells naive
#> 36 2
#> Dendritic cells activated Dendritic cells resting
#> 31 41
#> Eosinophils Macrophages M0
#> 14 155
#> Macrophages M1 Macrophages M2
#> 18 116
#> Mast cells activated Mast cells resting
#> 63 13
#> Monocytes NK cells activated
#> 130 5
#> NK cells resting Neutrophils
#> 20 86
#> Plasma cells T cells CD4 memory activated
#> 32 37
#> T cells CD4 memory resting T cells CD8
#> 215 28
#> T cells follicular helper T cells regulatory (Tregs)
#> 29 23table(test_set$`Most likely LM22 cell type`)
#>
#> B cells memory B cells naive
#> 36 3
#> Dendritic cells activated Dendritic cells resting
#> 35 35
#> Eosinophils Macrophages M0
#> 16 185
#> Macrophages M1 Macrophages M2
#> 7 92
#> Mast cells activated Mast cells resting
#> 79 14
#> Monocytes NK cells activated
#> 135 11
#> NK cells resting Neutrophils
#> 21 83
#> Plasma cells T cells CD4 memory activated
#> 51 39
#> T cells CD4 memory resting T cells CD8
#> 195 21
#> T cells follicular helper T cells regulatory (Tregs)
#> 31 25Unlike the example of the training basic model, we will remove all NAs cells in order to reduce the computational complexity for this example.
# remove NAs cells
train_set <- train_set[, !is.na(train_set$`Most likely LM22 cell type`)]
test_set <- test_set[, !is.na(test_set$`Most likely LM22 cell type`)]# convert cell label:
# 1 - positive to plasma cells,
# 0 - negative to plasma cells
train_set$plasma <- unlist(lapply(train_set$`Most likely LM22 cell type`,
function(x) if (x == 'Plasma cells') {1} else {0}))
test_set$plasma <- unlist(lapply(test_set$`Most likely LM22 cell type`,
function(x) if (x == 'Plasma cells') {1} else {0}))We may want to check the number of cells in each category:
Defining set of marker genes
Next, we define a set of marker genes, which will be used for the child classification model. Supposing we are training a model for classifying plasma cells, we define the set of marker genes as follows:
selected_marker_genes_plasma <- c('BACH2', 'BLK', 'CD14', 'CD19', 'CD27', 'CD37',
'CD38', 'CD40LG', 'CD74', 'CD79A', 'CD79B', 'CD83', 'CD84', 'CD86', 'CR2',
'DERL3', 'FLI1', 'IGHG1', 'IGHG2', 'IGHM', 'IL2RA', 'IRF8', 'LRMP', 'LY86',
'MCL1', 'MEF2C', 'MME', 'MS4A1', 'MVK', 'MZB1', 'POU2AF1', 'PTEN', 'RASGRP2',
'SDC1', 'SP140', 'TCF3', 'VPREB3')Train model
Training for a child model needs more parameters than training a basic one. Users must indicate the parent classifier. There are three ways to indicate the parent classifier to the train method:
Users can use an available model in current working place.
Users can give name of a model among default pretrained models, for example: parent_cell = ‘B cells’
Users can give name of a model among models available in users’ database AND the path to that database, for example:
parent_cell = 'B cells', path_to_models = '.'
Train the child classifier:
set.seed(123)
classifier_plasma <- train_classifier(train_obj = train_set,
marker_genes = selected_marker_genes_plasma, cell_type = "Plasma cells",
assay = 'counts', tag_slot = 'plasma', parent_classifier = classifier_B)
#> Apply pretrained model for parent cell type.
#> Warning: Some annotated Plasma cells are negative to B cells classifier. They are removed from training/testing for Plasma cells classifier.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.If the cells classifier has not been loaded to the current working space, an equivalent training process should be:
set.seed(123)
classifier_plasma <- train_classifier(train_obj = train_set,
marker_genes = selected_marker_genes_plasma, cell_type = "Plasma cells",
assay = 'counts', tag_slot = 'plasma', parent_cell = 'B cells')
#> Parent classifier not provided. Try finding available model.
#> loading from cache
#> Apply pretrained model for parent cell type.
#> Warning: Some annotated Plasma cells are negative to B cells classifier. They are removed from training/testing for Plasma cells classifier.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.
#> Warning in .local(x, ...): Variable(s) `' constant. Cannot scale data.classifier_plasma
#> An object of class scAnnotatR for Plasma cells
#> * 37 marker genes applied: BACH2, BLK, CD14, CD19, CD27, CD37, CD38, CD40LG, CD74, CD79A, CD79B, CD83, CD84, CD86, CR2, DERL3, FLI1, IGHG1, IGHG2, IGHM, IL2RA, IRF8, LRMP, LY86, MCL1, MEF2C, MME, MS4A1, MVK, MZB1, POU2AF1, PTEN, RASGRP2, SDC1, SP140, TCF3, VPREB3
#> * Predicting probability threshold: 0.5
#> * A child model of: B cellscaret_model(classifier_plasma)
#> Support Vector Machines with Linear Kernel
#>
#> No pre-processing
#> Resampling: Cross-Validated (10 fold)
#> Summary of sample sizes: 83, 83, 84, 84, 83, 85, ...
#> Addtional sampling using down-sampling
#>
#> Resampling results:
#>
#> Accuracy Kappa
#> 0.9205556 0.7647773
#>
#> Tuning parameter 'C' was held constant at a value of 1Test model
The parent classifier must be also set in test method.
classifier_plasma_test <- test_classifier(test_obj = test_set,
classifier = classifier_plasma, assay = 'counts', tag_slot = 'plasma',
parent_classifier = classifier_B)
#> Apply pretrained model for parent cell type.
#> Warning: Some annotated Plasma cells are negative to B cells classifier. They are removed from training/testing for Plasma cells classifier.
#> Current probability threshold: 0.5
#> Positive Negative Total
#> Actual 24 73 97
#> Predicted 21 76 97
#> Accuracy: 0.948453608247423
#> Sensivity (True Positive Rate) for Plasma cells: 0.833333333333333
#> Specificity (1 - False Positive Rate) for Plasma cells: 0.986301369863014
#> Area under the curve: 0.913812785388128Interpreting test model result
The test result obtained from a child model can be interpreted in the same way as we do with the model for basic cell types. We can change the prediction probability threshold according to the research project or personal preference and plot a roc curve.
print(classifier_plasma_test$auc)
#> Area under the curve: 0.9138
roc_curve <- plot_roc_curve(test_result = classifier_plasma_test)
plot(roc_curve)
Save child classification model for further use
In order to save child classifier, the parent classifier must already exist in the classifier database, either in the package default database or in the user-defined database.
# see list of available model in package
default_models <- load_models('default')
#> 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"In our package, the default models already include a model classifying plasma cells. Therefore, we will save this model to a new local database specified by the path_to_models parameter. If you start with a fresh new local database, there is no available parent classifier of plasma cells’ classifier. Therefore, we have to save the parent classifier first, e.g. the classifier for B cells.
# no copy of pretrained models is performed
save_new_model(new_model = classifier_B, path_to_models = tempdir(),
include.default = FALSE)
#> Saving new models to /tmp/RtmpfwdcsO/new_models.rda...
#> Finished saving new model
save_new_model(new_model = classifier_plasma, path_to_models = tempdir(),
include.default = FALSE)
#> Saving new models to /tmp/RtmpfwdcsO/new_models.rda...
#> Finished saving new modelApplying newly trained models for cell classification
When we save the B cells’ classifier and the plasma cells’ classifier, a local database is newly created. We can use this new database to classify cells in a Seurat or SingleCellExperiment object.
Let’s try to classify cells in the test set:
classified <- classify_cells(classify_obj = test_set, assay = 'counts',
cell_types = 'all', path_to_models = tempdir())
#> i = 1...Using the classify_cells() function, we have to indicate exactly the repository containing the database that the models has recently been saved to. In the previous section, we saved our new models to the current working directory.
In the classified object, the classification process added new columns to the cell meta data, including the predicted_cell_type and most_probable_cell_type columns.
If we use the full prediction to compare with actual plasma tag, we obtain this result:
# compare the prediction with actual cell tag
table(classified$predicted_cell_type, classified$plasma)
#>
#> 0 1
#> B cells 72 4
#> B cells/Plasma cells 1 20
#> unknown 990 27
# plasma cell is child cell type of B cell
# so of course, all predicted plasma cells are predicted B cells When comparing the actual tag with the most probable prediction, we obtain:
# compare the prediction with actual cell tag
table(classified$most_probable_cell_type, classified$plasma)
#>
#> 0 1
#> B cells 72 4
#> Plasma cells 1 20
#> unknown 990 27The number of identified plasma cells is different in the predicted_cell_type slot and in the most_probable_cell_type. This is because the predicted_cell_type takes all predictions having the probabilities satisfying the corresponding probability thresholds. Meanwhile, the most_probable_cell_type takes only the cell type which gives highest prediction probability.
To have all plasma cells specified as plasma cells, we can set the ignore_ambiguous_result to TRUE. This option will hide all ambiguous predictions where we have more than one possible cell type. In the parent-chid(ren) relationship of cell types, the more specified cell types/phenotypes will be reported.
Session Info
sessionInfo()
#> R version 4.4.1 (2024-06-14)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.1 LTS
#>
#> Matrix products: default
#> BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.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: Etc/UTC
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats4 stats graphics grDevices utils datasets methods
#> [8] base
#>
#> other attached packages:
#> [1] caret_6.0-94 lattice_0.22-6
#> [3] ggplot2_3.5.1 scRNAseq_2.19.1
#> [5] scAnnotatR_1.13.0 SingleCellExperiment_1.28.0
#> [7] SummarizedExperiment_1.36.0 Biobase_2.67.0
#> [9] GenomicRanges_1.59.0 GenomeInfoDb_1.43.0
#> [11] IRanges_2.41.0 S4Vectors_0.44.0
#> [13] BiocGenerics_0.53.0 MatrixGenerics_1.19.0
#> [15] matrixStats_1.4.1 Seurat_5.1.0
#> [17] SeuratObject_5.0.2 sp_2.1-4
#> [19] rmarkdown_2.28
#>
#> loaded via a namespace (and not attached):
#> [1] ProtGenerics_1.38.0 spatstat.sparse_3.1-0 bitops_1.0-9
#> [4] lubridate_1.9.3 httr_1.4.7 RColorBrewer_1.1-3
#> [7] alabaster.base_1.7.0 tools_4.4.1 sctransform_0.4.1
#> [10] utf8_1.2.4 R6_2.5.1 HDF5Array_1.35.0
#> [13] lazyeval_0.2.2 uwot_0.2.2 rhdf5filters_1.18.0
#> [16] withr_3.0.2 gridExtra_2.3 progressr_0.15.0
#> [19] cli_3.6.3 spatstat.explore_3.3-3 fastDummies_1.7.4
#> [22] alabaster.se_1.7.0 labeling_0.4.3 sass_0.4.9
#> [25] spatstat.data_3.1-2 proxy_0.4-27 ggridges_0.5.6
#> [28] pbapply_1.7-2 Rsamtools_2.22.0 parallelly_1.38.0
#> [31] RSQLite_2.3.7 generics_0.1.3 BiocIO_1.17.0
#> [34] ica_1.0-3 spatstat.random_3.3-2 dplyr_1.1.4
#> [37] Matrix_1.7-1 fansi_1.0.6 abind_1.4-8
#> [40] lifecycle_1.0.4 yaml_2.3.10 rhdf5_2.50.0
#> [43] recipes_1.1.0 SparseArray_1.6.0 BiocFileCache_2.15.0
#> [46] Rtsne_0.17 grid_4.4.1 blob_1.2.4
#> [49] promises_1.3.0 ExperimentHub_2.15.0 crayon_1.5.3
#> [52] miniUI_0.1.1.1 cowplot_1.1.3 GenomicFeatures_1.59.0
#> [55] KEGGREST_1.47.0 sys_3.4.3 maketools_1.3.1
#> [58] pillar_1.9.0 knitr_1.48 rjson_0.2.23
#> [61] future.apply_1.11.3 codetools_0.2-20 leiden_0.4.3.1
#> [64] glue_1.8.0 spatstat.univar_3.0-1 data.table_1.16.2
#> [67] gypsum_1.3.0 vctrs_0.6.5 png_0.1-8
#> [70] spam_2.11-0 gtable_0.3.6 kernlab_0.9-33
#> [73] cachem_1.1.0 gower_1.0.1 xfun_0.48
#> [76] S4Arrays_1.6.0 mime_0.12 prodlim_2024.06.25
#> [79] survival_3.7-0 timeDate_4041.110 iterators_1.0.14
#> [82] hardhat_1.4.0 lava_1.8.0 fitdistrplus_1.2-1
#> [85] ROCR_1.0-11 ipred_0.9-15 nlme_3.1-166
#> [88] bit64_4.5.2 alabaster.ranges_1.7.0 filelock_1.0.3
#> [91] RcppAnnoy_0.0.22 data.tree_1.1.0 bslib_0.8.0
#> [94] irlba_2.3.5.1 KernSmooth_2.23-24 rpart_4.1.23
#> [97] colorspace_2.1-1 DBI_1.2.3 nnet_7.3-19
#> [100] tidyselect_1.2.1 bit_4.5.0 compiler_4.4.1
#> [103] curl_5.2.3 httr2_1.0.5 DelayedArray_0.33.1
#> [106] plotly_4.10.4 rtracklayer_1.66.0 scales_1.3.0
#> [109] lmtest_0.9-40 rappdirs_0.3.3 stringr_1.5.1
#> [112] digest_0.6.37 goftest_1.2-3 spatstat.utils_3.1-0
#> [115] alabaster.matrix_1.7.0 XVector_0.46.0 htmltools_0.5.8.1
#> [118] pkgconfig_2.0.3 ensembldb_2.31.0 highr_0.11
#> [121] dbplyr_2.5.0 fastmap_1.2.0 rlang_1.1.4
#> [124] htmlwidgets_1.6.4 UCSC.utils_1.2.0 shiny_1.9.1
#> [127] farver_2.1.2 jquerylib_0.1.4 zoo_1.8-12
#> [130] jsonlite_1.8.9 BiocParallel_1.41.0 ModelMetrics_1.2.2.2
#> [133] RCurl_1.98-1.16 magrittr_2.0.3 GenomeInfoDbData_1.2.13
#> [136] dotCall64_1.2 patchwork_1.3.0 Rhdf5lib_1.28.0
#> [139] munsell_0.5.1 Rcpp_1.0.13 ape_5.8
#> [142] reticulate_1.39.0 alabaster.schemas_1.7.0 stringi_1.8.4
#> [145] pROC_1.18.5 zlibbioc_1.52.0 MASS_7.3-61
#> [148] AnnotationHub_3.15.0 plyr_1.8.9 parallel_4.4.1
#> [151] listenv_0.9.1 ggrepel_0.9.6 deldir_2.0-4
#> [154] Biostrings_2.75.0 splines_4.4.1 tensor_1.5
#> [157] igraph_2.1.1 spatstat.geom_3.3-3 RcppHNSW_0.6.0
#> [160] buildtools_1.0.0 reshape2_1.4.4 BiocVersion_3.21.1
#> [163] XML_3.99-0.17 evaluate_1.0.1 BiocManager_1.30.25
#> [166] foreach_1.5.2 httpuv_1.6.15 RANN_2.6.2
#> [169] tidyr_1.3.1 purrr_1.0.2 polyclip_1.10-7
#> [172] alabaster.sce_1.7.0 future_1.34.0 scattermore_1.2
#> [175] xtable_1.8-4 AnnotationFilter_1.31.0 restfulr_0.0.15
#> [178] e1071_1.7-16 RSpectra_0.16-2 later_1.3.2
#> [181] viridisLite_0.4.2 class_7.3-22 tibble_3.2.1
#> [184] GenomicAlignments_1.43.0 memoise_2.0.1 AnnotationDbi_1.69.0
#> [187] cluster_2.1.6 timechange_0.3.0 globals_0.16.3