The explosion of the usage of Next Generation Sequencing techniques during the past few years due to the seemingly endless portfolio of applications has created the need for new NGS data analytics tools which are able to offer comprehensive and at the same time flexible visualizations under several experimental settings and factors. An established visualization tool in NGS experiments is the visualization of the signal created by short reads after the application of every NGS protocol. Genome Browsers (e.g. the UCSC Genome Browser) serve very well this purpose considering single genomic areas. They are very good when it comes to the visualization of the abundance of a single or a few genes or the strength of a few protein-DNA interaction sites. However, when it comes to the visualization of average signal profiles over multiple genomic locations (gene regions or others like DNA methylation sites or transcription factor binding sites), Genome Browsers fail to depict such information in a comprehensive way. Furthermore, they cannot visualize average signal profiles of factored data, for example a set of genes categorized in high, medium and low expression or even by strand and they cannot visualize all signals of interest mapped on all the genomic regions of interest in a compact way, something that can be done using for example a heatmap.
In such cases, bioinformaticians use several toolkits like BEDTools and
facilities from R/Bioconductor to read/import short reads and overlap them with
genomic regions of interest, summarize them by binning/averaging overlaps to
control the resolution of final graphics etc. This procedure often requires the
usage of multiple tools and custom scripts with multiple steps. One of the most
comprehensive and easy-to-use tools up to date is
ngs.plot. It is sufficiently fast
for most applications and has a low memory footprint which allows users to run
it in low end machines too. It is command line based and users can run it by
using a simple configuration file most of the times, has a rich database of
genome annotation and genomic features and uses R/Bioconductor for underlying
calculations and plotting of profiles. However, ngs.plot is not up to date with
modern R graphics systems like ggplot2 and ComplexHeatmap. As a result,
among others, it is impossible to create faceted genomic profiles using a
statistical design and in such cases, a lot of additional manual work and
computational time is required in order to reach the desired outcomes. The same
applies to heatmap profiles. Furthermore, the resolution of genomic profiles
(e.g. per base coverage or per bin of base-pairs coverage) cannot be controlled
and this can cause problems in cases where extreme levels of resolution (e.g.
DNAse-Seq experiments) is required to reach meaningful biological conclusions.
Last but not least, ngs.plot requires a not so straightforward setup in order
to run, does not run in a unified working environment (e.g. R environment with
its graphics displaying mechanisms) and in some cases produces oversized and
complex output.
The recoup package comes to fill such gaps by stepping on the shoulders of giants. It uses the now standardized and stable Bioconductor facilities to read and import short reads from BAM/BED files or processed genomic signals from BIGWig files and also modern R graphics systems, namely ggplot2 and ComplexHeatmap in order to create comprehensive averaged genomic profiles and genomic profile heatmaps. In addition it offers a lot of (easy to use) customization options and automation at various levels. Inexperienced users can gather their data in a simple text file and just choose one of the supported organisms and recoup does the rest for them. More experienced users can play with several options and provide more flexible input so as to produce optimal results. This vignette, although it covers basic usage of the package, it offers the basis for more sophisticated usage. recoup is not as fast as ngs.plot but we are working on this! Also, recoup is not here to replace other more mature packages. It is here to offer more options to users that need more sophisticated genomic profile visualizations. Finally, it offers a very flexible way to reuse genomic profiles whose calculations may be computationally and time expensive by offering a smart way to recognize which parameters have changed and acting based on these.
Specifically, recoup creates three types of plots:
All plots can be faceted using a design file with the categories into which the plots should be separated. All the above are illustrated in the examples in the vignettes of this package.
Detailed instructions on how to run the recoup genomic profile creation pipeline can be found under the main documentation of the package:
library(recoup)## Warning: replacing previous import 'utils::findMatches' by
## 'S4Vectors::findMatches' when loading 'AnnotationDbi'help(recoup)Briefly, to run recoup you need:
recoup man page). They can also be provided
as an organism version keyword, e.g. hg19 or mm9 and the respective regions
will be either retrieved from a local recoup annotation database setup, or
downloaded on the fly (takes significantly more time as some extra operations
are required).The package contains a small dataset which serves only for package building and testing purposes as well as complying with Bioconductor guidelines. These data are useful for the user to check how the input data to recoup should look like. For a more complete test dataset (a small one) have a look and download from here
The following commands should provide some information on the embedded test data, which are subsets of the complete test data in the above link.
help(test.input)
help(test.genome)
help(test.design)
help(test.exons)In order to run smoothly some usage examples and produce some realistic results, you need to download a set of example BAM files, genomic regions and design files from here. Following, a description of each file in the archive (the tissue is always liver):
recoup annotation
databaseIn order to run the vignette examples, you should download and extract the
archive to a path of your preference, e.g. /home/me/recoup_tutorial.
Apart from a user specified file, the reference genomic regions used by recoup
to construct average profiles over, can be predefined gene set from a few common
organisms supported by recoup. See the recoup man page for a list of these
organisms. In order to use this “database” of predefined genomic areas, you
should run the function buildAnnotationStore with a list of organisms, a list
of annotation sources (Ensembl, RefSeq and UCSC supported) and a desired path to
store the annotations (defaults to /home/me/.recoup). For example:
buildAnnotationDatabase(c("hg19","mm9","rn4"),c("ensembl","refseq"))See the man page of buildAnnotationStore for more details. This step is not
necessary for recoup to run as these annotations can be also downloaded on the
fly. However, if subsets of the supported organisms are to be used often, it is
much more preferrable to spend some time building the local store as it can save
a lot of running time later by investing some time in the beginning to build
this store.
The recoup function can be used to create coverage profiles from ChIP-Seq
like experiments (signals over continuous genomic regions) or from RNA-Seq
experiments (signals over non-continuous genomic regions). Due to restrictions
(logical ones) imposed by the Bioconductor development core team, the data that
are required for a realistic tutorial of the recoup package cannot be
included. Thus, this page along with the rest of the tutorial on how to create
genomic profiles from ChIP-Seq or RNA-Seq data can be found either
here or in the wiki
recoup pages in
github
When working with gene bodies, it happens very often that
gene lengths are a little to a lot smaller than the number of bins into which
they should be split and averaged in order to be able to create the average
curve and heatmap profiles. While other packages line ngs.plot deal with this by
always plotting in a pre-specifed axis system (e.g. 1-100 in the x-axis for
ngs.plot) and using splines to sample coverages at equal spaces, recoup supports
a more dynamic resolution by allowing the user to set the number of bins into
which genomic areas will be binned or by allowing a per-base resolution where
possible. Thus, when genes are smaller than the desired number of bins, there
might be a problem. recoup deals with that in four possible ways:
spline function with the default method)approx function with the default method)NA values are distributed randomly across the small area
coverage vector (e.g. gene with length smaller than the desired number of
bins), excluding the first and the last two positions, in order to reach
the desired number of bins. Then, each NA position is filled with the
mean value of the two values before and the two values after the NA
position. This method should be avoided when >20% of the values of the
extended vector are NA’s as it may cause a crash. However, it should be
the most accurate one in the opposite case (few NA’s). See the
recoup man page for further information.In the two vignettes explaining the useage of the recoup package and its
functions and in the examples, you will notice the direct use of plot function
instead of direct plotting (plotParams$plot=FALSE instead of the default
TRUE) or the recoupPlot function. This has been done on purpose as at this
point, it is not straighforward how to tell the knitr vignette builder how to
plot objects created within called functions.
Due to strict Bioconductor guidelines regarding package size, these vignettes can also be found in the github package page with a few more examples.
## 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] grid stats4 stats graphics grDevices utils datasets
## [8] methods base
##
## other attached packages:
## [1] recoup_1.28.0 ComplexHeatmap_2.16.0
## [3] ggplot2_3.4.2 GenomicAlignments_1.36.0
## [5] Rsamtools_2.16.0 Biostrings_2.68.0
## [7] XVector_0.40.0 SummarizedExperiment_1.30.0
## [9] Biobase_2.60.0 MatrixGenerics_1.12.0
## [11] matrixStats_0.63.0 GenomicRanges_1.52.0
## [13] GenomeInfoDb_1.36.0 IRanges_2.34.0
## [15] S4Vectors_0.38.0 BiocGenerics_0.46.0
## [17] BiocStyle_2.28.0
##
## loaded via a namespace (and not attached):
## [1] DBI_1.1.3 bitops_1.0-7 biomaRt_2.56.0
## [4] rlang_1.1.0 magrittr_2.0.3 clue_0.3-64
## [7] GetoptLong_1.0.5 compiler_4.3.0 RSQLite_2.3.1
## [10] GenomicFeatures_1.52.0 png_0.1-8 vctrs_0.6.2
## [13] stringr_1.5.0 pkgconfig_2.0.3 shape_1.4.6
## [16] crayon_1.5.2 fastmap_1.1.1 dbplyr_2.3.2
## [19] utf8_1.2.3 rmarkdown_2.21 bit_4.0.5
## [22] xfun_0.39 zlibbioc_1.46.0 cachem_1.0.7
## [25] jsonlite_1.8.4 progress_1.2.2 blob_1.2.4
## [28] DelayedArray_0.26.0 BiocParallel_1.34.0 parallel_4.3.0
## [31] prettyunits_1.1.1 cluster_2.1.4 R6_2.5.1
## [34] bslib_0.4.2 stringi_1.7.12 RColorBrewer_1.1-3
## [37] rtracklayer_1.60.0 jquerylib_0.1.4 bookdown_0.33
## [40] iterators_1.0.14 knitr_1.42 Matrix_1.5-4
## [43] tidyselect_1.2.0 yaml_2.3.7 doParallel_1.0.17
## [46] codetools_0.2-19 curl_5.0.0 lattice_0.21-8
## [49] tibble_3.2.1 withr_2.5.0 KEGGREST_1.40.0
## [52] evaluate_0.20 BiocFileCache_2.8.0 xml2_1.3.3
## [55] circlize_0.4.15 pillar_1.9.0 BiocManager_1.30.20
## [58] filelock_1.0.2 foreach_1.5.2 generics_0.1.3
## [61] RCurl_1.98-1.12 hms_1.1.3 munsell_0.5.0
## [64] scales_1.2.1 glue_1.6.2 tools_4.3.0
## [67] BiocIO_1.10.0 XML_3.99-0.14 AnnotationDbi_1.62.0
## [70] colorspace_2.1-0 GenomeInfoDbData_1.2.10 restfulr_0.0.15
## [73] cli_3.6.1 rappdirs_0.3.3 fansi_1.0.4
## [76] dplyr_1.1.2 gtable_0.3.3 sass_0.4.5
## [79] digest_0.6.31 rjson_0.2.21 memoise_2.0.1
## [82] htmltools_0.5.5 lifecycle_1.0.3 httr_1.4.5
## [85] GlobalOptions_0.1.2 bit64_4.0.5