countsimQC - Comparing characteristic features across count data sets

Charlotte Soneson

2023-04-25

Introduction

The countsimQC package provides a simple way to compare the characteristic features of a collection of (e.g., RNA-seq) count data sets. An important application is in situations where a synthetic count data set has been generated using a real count data set as an underlying source of parameters, in which case it is often important to verify that the final synthetic data captures the main features of the original data set. However, the package can be used to create a visual overview of any collection of one or more count data sets.

Data preparation

In this vignette we will show how to generate a comparative report from a collection of two simulated data sets and the original, underlying real data set. First, we load the object containing the three data sets. The object is a named list, where each element is a DESeqDataSet object, containing the count matrix, a sample information data frame and a model formula (necessary to calculate dispersions). For more information about the DESeqDataSet class, please see the DESeq2 Bioconductor package. For speed reasons, we use only a subset of the features in each data set for the following calculations.

suppressPackageStartupMessages({
  library(countsimQC)
  library(DESeq2)
})

data(countsimExample)
countsimExample
## $Original
## class: DESeqDataSet 
## dim: 10000 11 
## metadata(1): version
## assays(1): counts
## rownames(10000): ENSMUSG00000000001.4 ENSMUSG00000000028.14 ...
##   ENSMUSG00000048027.7 ENSMUSG00000048029.10
## rowData names(0):
## colnames(11): GSM1923445 GSM1923446 ... GSM1923578 GSM1923579
## colData names(2): group sample
## 
## $Sim1
## class: DESeqDataSet 
## dim: 10000 11 
## metadata(1): version
## assays(1): counts
## rownames(10000): Gene1 Gene2 ... Gene9999 Gene10000
## rowData names(0):
## colnames(11): Cell1 Cell2 ... Cell88 Cell89
## colData names(4): Cell Batch Group ExpLibSize
## 
## $Sim2
## class: DESeqDataSet 
## dim: 10000 11 
## metadata(1): version
## assays(1): counts
## rownames(10000): Gene1 Gene2 ... Gene9999 Gene10000
## rowData names(0):
## colnames(11): Cell1 Cell2 ... Cell88 Cell89
## colData names(3): Cell CellFac Group
countsimExample <- lapply(countsimExample, function(cse) {
  cse[seq_len(1500), ]
})

Report generation

Next, we generate the report using the countsimQCReport() function. Depending on the level of detail and the type of information that are required for the final report, this function can be run in different “modes”:

Here, for the sake of speed, we calculate statistics for a small subset of the observations (subsampleSize = 25) and refrain from calculating permutation p-values.

tempDir <- tempdir()
countsimQCReport(ddsList = countsimExample, outputFile = "countsim_report.html",
                 outputDir = tempDir, outputFormat = "html_document", 
                 showCode = FALSE, forceOverwrite = TRUE,
                 savePlots = TRUE, description = "This is my test report.", 
                 maxNForCorr = 25, maxNForDisp = Inf, 
                 calculateStatistics = TRUE, subsampleSize = 25,
                 kfrac = 0.01, kmin = 5, 
                 permutationPvalues = FALSE, nPermutations = NULL)

The countsimQCReport() function can generate either an HTML file (by setting outputFormat = "html_document" or outputFormat = NULL) or a pdf file (by setting outputFormat = "pdf_document"). The description argument can be used to provide a more extensive description of the data set(s) that are included in the report.

Generation of individual figures

If the argument savePlots is set to TRUE, an .rds file containing the individual ggplot objects will be generated. These objects can be used to perform fine-tuning of the visualizations if desired. Note, however, that the .rds file can become large if the number of data sets is large, or if the individual data sets have many samples or features. The convenience function generateIndividualPlots() can be used to quickly generate individual figures for all plots included in the report, using a variety of devices. For example, to generate each plot in pdf format:

ggplots <- readRDS(file.path(tempDir, "countsim_report_ggplots.rds"))
if (!dir.exists(file.path(tempDir, "figures"))) {
  dir.create(file.path(tempDir, "figures"))
}
generateIndividualPlots(ggplots, device = "pdf", nDatasets = 3, 
                        outputDir = file.path(tempDir, "figures"))
## `geom_smooth()` using formula = 'y ~ x'

Input data format

In the example above, all data sets were provided as DESeqDataSet objects. The advantage of this is that it allows the specification of the experimental design, which is used in the dispersion calculations. countsimQC also allows a data set to be provided as either a data.frame or a matrix. However, in these situations, it will be assumed that all samples are replicates (i.e., a design ~1). An example is provided in the countsimExample_dfmat data set, provided with the package.

data(countsimExample_dfmat)
names(countsimExample_dfmat)
## [1] "Original" "Sim1"     "Sim2"
lapply(countsimExample_dfmat, class)
## $Original
## [1] "DESeqDataSet"
## attr(,"package")
## [1] "DESeq2"
## 
## $Sim1
## [1] "matrix" "array" 
## 
## $Sim2
## [1] "data.frame"
tempDir <- tempdir()
countsimQCReport(ddsList = countsimExample_dfmat, 
                 outputFile = "countsim_report_dfmat.html",
                 outputDir = tempDir, outputFormat = "html_document", 
                 showCode = FALSE, forceOverwrite = TRUE,
                 savePlots = TRUE, description = "This is my test report.", 
                 maxNForCorr = 25, maxNForDisp = Inf, 
                 calculateStatistics = TRUE, subsampleSize = 25,
                 kfrac = 0.01, kmin = 5, 
                 permutationPvalues = FALSE, nPermutations = NULL)

Session info

sessionInfo()
## R version 4.3.0 RC (2023-04-13 r84269)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 22.04.2 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.17-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] DESeq2_1.40.0               SummarizedExperiment_1.30.0
##  [3] Biobase_2.60.0              MatrixGenerics_1.12.0      
##  [5] matrixStats_0.63.0          GenomicRanges_1.52.0       
##  [7] GenomeInfoDb_1.36.0         IRanges_2.34.0             
##  [9] S4Vectors_0.38.0            BiocGenerics_0.46.0        
## [11] countsimQC_1.18.0          
## 
## loaded via a namespace (and not attached):
##  [1] tidyselect_1.2.0        farver_2.1.1            dplyr_1.1.2            
##  [4] blob_1.2.4              Biostrings_2.68.0       bitops_1.0-7           
##  [7] fastmap_1.1.1           RCurl_1.98-1.12         XML_3.99-0.14          
## [10] digest_0.6.31           lifecycle_1.0.3         ellipsis_0.3.2         
## [13] survival_3.5-5          KEGGREST_1.40.0         RSQLite_2.3.1          
## [16] magrittr_2.0.3          genefilter_1.82.0       compiler_4.3.0         
## [19] rlang_1.1.0             sass_0.4.5              tools_4.3.0            
## [22] utf8_1.2.3              yaml_2.3.7              knitr_1.42             
## [25] labeling_0.4.2          htmlwidgets_1.6.2       bit_4.0.5              
## [28] DelayedArray_0.26.0     BiocParallel_1.34.0     withr_2.5.0            
## [31] purrr_1.0.1             grid_4.3.0              fansi_1.0.4            
## [34] caTools_1.18.2          xtable_1.8-4            colorspace_2.1-0       
## [37] edgeR_3.42.0            ggplot2_3.4.2           scales_1.2.1           
## [40] cli_3.6.1               rmarkdown_2.21          crayon_1.5.2           
## [43] ragg_1.2.5              generics_0.1.3          httr_1.4.5             
## [46] DBI_1.1.3               cachem_1.0.7            zlibbioc_1.46.0        
## [49] splines_4.3.0           parallel_4.3.0          AnnotationDbi_1.62.0   
## [52] XVector_0.40.0          vctrs_0.6.2             Matrix_1.5-4           
## [55] jsonlite_1.8.4          bit64_4.0.5             crosstalk_1.2.0        
## [58] systemfonts_1.0.4       locfit_1.5-9.7          limma_3.56.0           
## [61] jquerylib_0.1.4         tidyr_1.3.0             annotate_1.78.0        
## [64] glue_1.6.2              randtests_1.0.1         codetools_0.2-19       
## [67] DT_0.27                 gtable_0.3.3            munsell_0.5.0          
## [70] tibble_3.2.1            pillar_1.9.0            htmltools_0.5.5        
## [73] GenomeInfoDbData_1.2.10 R6_2.5.1                textshaping_0.3.6      
## [76] evaluate_0.20           lattice_0.21-8          highr_0.10             
## [79] png_0.1-8               memoise_2.0.1           bslib_0.4.2            
## [82] Rcpp_1.0.10             nlme_3.1-162            mgcv_1.8-42            
## [85] xfun_0.39               pkgconfig_2.0.3