Contents

1 Introduction

DecontX is a Bayesian hierarchical model to estimate and remove cross-contamination from ambient RNA in single-cell RNA-seq count data generated from droplet-based sequencing devices. DecontX will take the count matrix with/without the cell labels and estimate the contamination level and deliver a decontaminted count matrix for downstream analysis.

In this vignette we will demonstrate how to use DecontX to estimate and remove contamination.

2 Installation

celda can be installed from Bioconductor:

if (!requireNamespace("BiocManager", quietly=TRUE)){
    install.packages("BiocManager")}
BiocManager::install("celda")

The package can be loaded using the library command.

library(celda)

To see the latest updates and releases or to post a bug, see our GitHub page at https://github.com/campbio/celda. To ask questions about running celda, post a thread on Bioconductor support site at https://support.bioconductor.org/.

3 Reproducibility note

Many functions in celda make use of stochastic algorithms or procedures which require the use of random number generator (RNG) for simulation or sampling. To maintain reproducibility, all these functions use a default seed of 12345 to make sure same results are generated each time one of these functions is called. Explicitly setting the seed arguments is needed for greater control and randomness.

4 Generation of a cross-contaminated dataset

DecontX will take a matrix of counts (referred as observed counts) where each row is a feature, each column is a cell, and each entry in the matrix is the number of counts of each feature in each cell. To illustrate the utility of DecontX, we will apply it to a simulated dataset.

In the function simulateContaminatedMatrix, the K parameter designates the number of cell clusters, the C parameter determines the number of cells, the G parameter determines the number of genes in the simulated dataset.

simCounts <- simulateContaminatedMatrix(G = 300, C = 100, K = 3)

The nativeCounts is the natively expressed counts matrix, and observedCounts is the observed counts matrix that contains both contaminated and natively expressed transctripts. The NByC is the total number of observed transcripts per cell. The counts matrix which only contains contamianted transcripts can be obtained by subtracting the observed counts matrix from the observed counts matrix.

contamination <- simCounts$observedCounts - simCounts$nativeCounts

The z variable contains the population label for each cell.

table(simCounts$z)
## 
##  1  2  3 
## 26 36 38

The phi and eta variables contain the expression distributions and contamination distributions for each population, respectively. Each column corresponds to a population, each row represents a gene. The sum of the rows equal to 1.

colSums(simCounts$phi)
## [1] 1 1 1
colSums(simCounts$eta)
## [1] 1 1 1

5 Decontamination using DecontX

DecontX uses bayesian method to estimate and remove contamination via varitaional inference.

decontxModel <- decontX(counts = simCounts$observedCounts, z = simCounts$z)

5.1 Check convergence

Use log-likelihood to check convergence

plot(decontxModel$resList$logLikelihood)

5.2 Evaluate model performance

decontX estimates a contamination proportion for each cell. We compare the estimated contamination proportion with the real contamination proportion.

plot(decontxModel$resList$estConp,
    colSums(contamination) / simCounts$NByC, col = simCounts$z)
abline(0, 1)

6 Session Information

sessionInfo()
## R version 3.6.2 (2019-12-12)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 18.04.3 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.10-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.10-bioc/R/lib/libRlapack.so
## 
## 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       
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] celda_1.2.4      BiocStyle_2.14.4
## 
## loaded via a namespace (and not attached):
##  [1] Biobase_2.46.0              ggdendro_0.1-20            
##  [3] viridis_0.5.1               httr_1.4.1                 
##  [5] viridisLite_0.3.0           foreach_1.4.7              
##  [7] RcppParallel_4.4.4          assertthat_0.2.1           
##  [9] BiocManager_1.30.10         stats4_3.6.2               
## [11] GenomeInfoDbData_1.2.2      ggrepel_0.8.1              
## [13] yaml_2.2.0                  pillar_1.4.3               
## [15] lattice_0.20-38             glue_1.3.1                 
## [17] pROC_1.16.1                 RcppEigen_0.3.3.7.0        
## [19] digest_0.6.23               GenomicRanges_1.38.0       
## [21] RColorBrewer_1.1-2          XVector_0.26.0             
## [23] colorspace_1.4-1            enrichR_2.1                
## [25] htmltools_0.4.0             Matrix_1.2-18              
## [27] plyr_1.8.5                  pkgconfig_2.0.3            
## [29] magick_2.2                  bookdown_0.17              
## [31] zlibbioc_1.32.0             purrr_0.3.3                
## [33] scales_1.1.0                Rtsne_0.15                 
## [35] BiocParallel_1.20.1         tibble_2.1.3               
## [37] combinat_0.0-8              IRanges_2.20.2             
## [39] ggplot2_3.2.1               withr_2.1.2                
## [41] SummarizedExperiment_1.16.1 BiocGenerics_0.32.0        
## [43] lazyeval_0.2.2              magrittr_1.5               
## [45] crayon_1.3.4                evaluate_0.14              
## [47] doParallel_1.0.15           MASS_7.3-51.5              
## [49] MAST_1.12.0                 tools_3.6.2                
## [51] data.table_1.12.8           lifecycle_0.1.0            
## [53] matrixStats_0.55.0          stringr_1.4.0              
## [55] S4Vectors_0.24.3            munsell_0.5.0              
## [57] DelayedArray_0.12.2         compiler_3.6.2             
## [59] GenomeInfoDb_1.22.0         rlang_0.4.2                
## [61] grid_3.6.2                  RCurl_1.98-1.1             
## [63] iterators_1.0.12            rjson_0.2.20               
## [65] SingleCellExperiment_1.8.0  bitops_1.0-6               
## [67] rmarkdown_2.1               gtable_0.3.0               
## [69] codetools_0.2-16            abind_1.4-5                
## [71] reshape2_1.4.3              R6_2.4.1                   
## [73] gridExtra_2.3               knitr_1.27.2               
## [75] dplyr_0.8.3                 uwot_0.1.5                 
## [77] dendextend_1.13.2           stringi_1.4.5              
## [79] parallel_3.6.2              Rcpp_1.0.3                 
## [81] MCMCprecision_0.4.0         tidyselect_0.2.5           
## [83] xfun_0.12