Abstract
alevinQC reads output files from alevin and generates summary reports.
Introduction
The purpose of the alevinQC package is to generate a summary QC report based on the output of an alevin (Srivastava et al. 2019) run. The QC report can be generated as a html or pdf file, or launched as a shiny application.
Installation
alevinQC can be installed using the
BiocManager CRAN package.
if (!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("alevinQC")After installation, load the package into the R session.
library(alevinQC)
#> Error in get(paste0(generic, ".", class), envir = get_method_env()) :
#> object 'type_sum.accel' not foundNote that in order to process output from Salmon v0.14 or later, you need Alevin v1.1 or later.
Assumed output directory structure
For more information about running alevin, we refer to the documentation.
When invoked, alevin generates several output files in the specified
output directory. alevinQC
assumes that this structure is retained, and will return an error if it
isn’t - thus, it is not recommended to move or rename the output files
from alevin. alevinQC
assumes that the following files (in the indicated structure) are
available in the provided baseDir (note that currently, in
order to generate the full set of files, alevin must be invoked with the
--dumpFeatures flag).
For alevin versions before 0.14:
baseDir
|--alevin
| |--featureDump.txt
| |--filtered_cb_frequency.txt
| |--MappedUmi.txt
| |--quants_mat_cols.txt
| |--quants_mat_rows.txt
| |--quants_mat.gz
| |--raw_cb_frequency.txt
| |--whitelist.txt
|--aux_info
| |--meta_info.json
|--cmd_info.jsonFor alevin version 0.14 and later:
Check that all required alevin files are available
The report generation functions (see below) will check that all the
required files are available in the provided base directory. However,
you can also call the function checkAlevinInputFiles() to
run the check manually. If one or more files are missing, the function
will raise an error indicating the missing file(s).
baseDir <- system.file("extdata/alevin_example_v0.14", package = "alevinQC")
checkAlevinInputFiles(baseDir = baseDir)
#> [1] "v0.14"Generate QC report
The alevinQCReport() function generates the QC report
from the alevin output. Depending on the file extension of the
outputFile argument, and the value of
outputFormat, the function can generate either an html
report or a pdf report.
outputDir <- tempdir()
alevinQCReport(baseDir = baseDir, sampleId = "testSample",
outputFile = "alevinReport.html",
outputFormat = "html_document",
outputDir = outputDir, forceOverwrite = TRUE)Create shiny app
In addition to static reports, alevinQC can also generate a shiny application, containing the same summary figures as the pdf and html reports.
app <- alevinQCShiny(baseDir = baseDir, sampleId = "testSample")Once created, the app can be launched using the runApp()
function from the shiny
package.
shiny::runApp(app)It is possible to export the data used internally by the interactive
application (in effect, the output from the internal call to
readAlevinQC() or readAlevinFryQC()). To
enable such export, first generate the app object as in the
example above, and then assign the call to shiny::runApp()
to a variable to capture the output. For example:
if (interactive()) {
out <- shiny::runApp(app)
}To activate the export, make sure to click the button ‘Close app’ in
the top right corner in order to close the application (don’t just close
the window). This will take you back to your R session, where the
variable out will be populated with the data used in the
app.
Generate individual plots
The individual plots included in the QC reports can also be independently generated. To do so, we must first read the alevin output into an R object.
alevin <- readAlevinQC(baseDir = baseDir)The resulting list contains four entries:
-
cbTable: adata.framewith various inferred characteristics of the individual cell barcodes. -
summaryTables: a list ofdata.frames with summary information about the full data set, the initial set of whitelisted cells and the final set of whitelisted cells, respectively. -
versionTable: amatrixwith information about the invokation of alevin. -
type: acharacterscalar indicating how alevinQC interpreted the alevin output directory.
head(alevin$cbTable)
#> CB originalFreq ranking collapsedFreq nbrMappedUMI
#> 1 GACTGCGAGGGCATGT 121577 1 123419 104128
#> 2 GGTGCGTAGGCTACGA 110467 2 111987 93608
#> 3 ATGAGGGAGTAGTGCG 106446 3 108173 88481
#> 4 ACTGTCCTCATGCTCC 104794 4 106085 81879
#> 5 CGAACATTCTGATACG 104616 5 106072 84395
#> 6 ACTGTCCCATATGGTC 99208 6 100776 81066
#> totalUMICount mappingRate dedupRate MeanByMax nbrGenesAboveZero
#> 1 73312 0.843695 0.295943 0.00735194 7512
#> 2 66002 0.835883 0.294911 0.00783094 7522
#> 3 62196 0.817958 0.297069 0.00832595 7081
#> 4 57082 0.771824 0.302849 0.00619664 6956
#> 5 58547 0.795639 0.306274 0.00743685 7347
#> 6 56534 0.804418 0.302618 0.00947029 6841
#> nbrGenesAboveMean ArborescenceCount inFinalWhiteList inFirstWhiteList
#> 1 1237 1.42034 TRUE TRUE
#> 2 1238 1.41826 TRUE TRUE
#> 3 1151 1.42262 TRUE TRUE
#> 4 957 1.43441 TRUE TRUE
#> 5 1238 1.44149 TRUE TRUE
#> 6 1068 1.43393 TRUE TRUE
knitr::kable(alevin$summaryTables$fullDataset)| Total number of processed reads | 7197662 |
| Number of reads with Ns | 35362 |
| Number of reads with valid cell barcode (no Ns) | 7162300 |
| Number of mapped reads | 4869156 |
| Percent mapped (of all reads) | 67.65% |
| Number of noisy CB reads | 1003624 |
| Number of noisy UMI reads | 266 |
| Total number of observed cell barcodes | 188613 |
knitr::kable(alevin$summaryTables$initialWhitelist)| Number of barcodes (initial whitelist) | 100 |
| Number of barcodes with quantification (initial whitelist) | 100 |
| Fraction reads in barcodes (initial whitelist) | 84.64% |
| Mean number of reads per cell (initial whitelist) | 60620 |
| Median number of reads per cell (initial whitelist) | 58132 |
| Mean number of detected genes per cell (initial whitelist) | 5163 |
| Median number of detected genes per cell (initial whitelist) | 5268 |
| Mean UMI count per cell (initial whitelist) | 33274 |
| Median UMI count per cell (initial whitelist) | 31353 |
knitr::kable(alevin$summaryTables$finalWhitelist)| Number of barcodes (final whitelist) | 95 |
| Number of barcodes with quantification (final whitelist) | 95 |
| Fraction reads in barcodes (final whitelist) | 82.39% |
| Mean number of reads per cell (final whitelist) | 62118 |
| Median number of reads per cell (final whitelist) | 58725 |
| Mean number of detected genes per cell (final whitelist) | 5260 |
| Median number of detected genes per cell (final whitelist) | 5343 |
| Mean UMI count per cell (final whitelist) | 34091 |
| Median UMI count per cell (final whitelist) | 32028 |
knitr::kable(alevin$versionTable)| Start time | Thu May 30 13:06:55 2019 |
| Salmon version | 0.14.0 |
| Index | /mnt/scratch5/avi/alevin/data/mohu/salmon_index |
| R1file | /mnt/scratch5/avi/alevin/data/10x/v2/mohu/100/all_bcs.fq |
| R2file | /mnt/scratch5/avi/alevin/data/10x/v2/mohu/100/all_reads.fq |
| tgMap | /mnt/scratch5/avi/alevin/data/mohu/gtf/txp2gene.tsv |
| Library type | ISR |
The plots can now be generated using the dedicated plotting functions provided with alevinQC (see the help file for the respective function for more information).
plotAlevinKneeRaw(alevin$cbTable)
plotAlevinBarcodeCollapse(alevin$cbTable)
plotAlevinQuant(alevin$cbTable)
plotAlevinKneeNbrGenes(alevin$cbTable)
Session info
sessionInfo()
#> R Under development (unstable) (2024-12-20 r87452)
#> Platform: aarch64-apple-darwin20
#> Running under: macOS Sonoma 14.7.2
#>
#> Matrix products: default
#> BLAS: /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRblas.0.dylib
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRlapack.dylib; LAPACK version 3.12.0
#>
#> locale:
#> [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
#>
#> time zone: UTC
#> tzcode source: internal
#>
#> attached base packages:
#> [1] stats graphics grDevices utils datasets methods base
#>
#> other attached packages:
#> [1] alevinQC_1.23.1 BiocStyle_2.35.0
#>
#> loaded via a namespace (and not attached):
#> [1] tximport_1.35.0 sass_0.4.9 generics_0.1.3
#> [4] tidyr_1.3.1 digest_0.6.37 magrittr_2.0.3
#> [7] evaluate_1.0.1 grid_4.5.0 RColorBrewer_1.1-3
#> [10] bookdown_0.41 fastmap_1.2.0 plyr_1.8.9
#> [13] jsonlite_1.8.9 promises_1.3.2 BiocManager_1.30.25
#> [16] GGally_2.2.1 purrr_1.0.2 crosstalk_1.2.1
#> [19] scales_1.3.0 shinydashboard_0.7.2 textshaping_0.4.1
#> [22] jquerylib_0.1.4 cli_3.6.3 shiny_1.10.0
#> [25] rlang_1.1.4 cowplot_1.1.3 munsell_0.5.1
#> [28] withr_3.0.2 cachem_1.1.0 yaml_2.3.10
#> [31] tools_4.5.0 dplyr_1.1.4 colorspace_2.1-1
#> [34] ggplot2_3.5.1 httpuv_1.6.15 DT_0.33
#> [37] ggstats_0.7.0 mime_0.12 vctrs_0.6.5
#> [40] R6_2.5.1 lifecycle_1.0.4 fs_1.6.5
#> [43] htmlwidgets_1.6.4 fontawesome_0.5.3 ragg_1.3.3
#> [46] pkgconfig_2.0.3 desc_1.4.3 pkgdown_2.1.1.9000
#> [49] pillar_1.10.0 bslib_0.8.0 later_1.4.1
#> [52] gtable_0.3.6 glue_1.8.0 Rcpp_1.0.13-1
#> [55] systemfonts_1.1.0 xfun_0.49 tibble_3.2.1
#> [58] tidyselect_1.2.1 knitr_1.49 farver_2.1.2
#> [61] xtable_1.8-4 rjson_0.2.23 htmltools_0.5.8.1
#> [64] labeling_0.4.3 rmarkdown_2.29 compiler_4.5.0