The Shiny Variant Explorer (tSVE) was primarily developped to demonstrate features implemented in the TVTB, not as a production environment. As a result, a few important considerations should be made to clarify what should and should not be expected from the web-application:
...1).ggplot objects,
definition of custom genomic ranges).ggplot) are currently the only output that can
be exported from the web-application (using the web browser “Download
image”, or equivalent context menu item). In the future, action buttons
may be added to export tables (e.g. CSV format) and figures
(e.g. PDF format).The Shiny Variant Explorer suggests a few additional package dependencies compared to the package, to support certain forms of data input and display.
Input
EnsDb2 annotation packages
are required if that interface is used to query genomic ranges
(demonstrated in this section).Display
The TVTB::tSVE() method launches the
web-application.
Overall, the web-application is implemented as a web-page with a top level navigation bar organised from left to right to reflect progression through a typical analysis, with the exception of the last two menu items Settings and Session, which may be useful to check and update at any point.
Here is a brief overview of the menu items:
EnsDb annotation package may be selected to use the
associated database interface.The Input panel controls the major input parameters of the analysis, including phenotypes (and therefore samples), genomic ranges, and fields to import from VCF file(s). Those inputs are useful to import only data of interest, as well as to limit memory usage and duration of calculations.
Phenotypes are critical to define groups of samples that may be
compared in summary statistics, tables, and plots. Moreover, phenotypes
also implicitely define the set of samples required in the analysis
(unique sample identifiers usually set as rownames of the
phenotypes).
The web-application accepts phenotypes stored in a text file, with the following requirements:
read.table function).rownames.colnames.When provided, phenotypes will be used to import from VCF file(s) only genotypes for the corresponding samples identifiers. Moreover, an error message will be displayed if any of the sample identifiers present in the phenotypes is absent from the VCF file(s).
Note that the web-application does not absolutely require phenotype information. In the absence of phenotype information, all samples are imported from VCF file(s).
Action:
- Click on the Browse action button
- Navigate to the
extdatafolder of the TVTB installation directory- Select the file
integrated_samples.txtAlternatively: click the Sample file button
Notes
Genomic ranges are critical to import only variants in targeted genomic regions or features (e.g. genes, transcripts, exons), as well as to limit memory usage and duration of calculations.
The Shiny Variant Explorer currently supports three types of input to define genomic ranges:
EnsDb annotation packagesCurrently, the web-application uses genomic ranges solely to query the corresponding variants from VCF file(s). In the future, those genomic ranges may also be used to produce faceted summary statistics and plots.
Notes:
If a BED file is supplied, the web-application parses it using the
rtracklayer
import.bed method. Therefore the file must respect the BED file
format guidelines.
Action:
- Click on the Browse action button
- Navigate to the
extdatafolder of the TVTB installation directory- Select the file
SLC24A5.bedAlternatively: click the Sample file button
Notes:
Sequence names (i.e. chromosomes), start, and end positions
of one or more genomic ranges may be defined in the text field, with
individual regions separated by ";".
Action:
- Paste
15:48,413,169-48,434,869in the text fieldAlternatively: click the Sample input button
Notes:
"," characters
from the text input, before coercing the start and end positions to
numeric1:123-456;2:234-345;2:456-789)Currently, genomic ranges encoding only gene-coding regions may be retrieved from an Ensembl-based database. This feature was adapted from the web-application implemented in the ensembldb package.
Action:
- Paste
SLC24A5in the text fieldAlternatively: click the Sample input button
At the core of the TVTB package, variants must be imported from one or more VCF file(s) annotated by the Ensembl Variant Effect Predictor (VEP) script (McLaren et al. 2010).
Considering the large size of most VCF file(s), it is common practice to split genetic variants into multiple files, each file used to store variants located on a single chromosome (more generally; a single sequence). The Shiny Variant Explorer supports two situations:
seqnames slot of the genomic ranges described above (“Multi-VCF mode”).In addition, VCF files can store a plethora of information in their
various fields. It is often useful to select only a subset of fields
relevant for a particular analysis, to limit memory usage. The
web-application uses the VariantAnnotation
scanVcfHeader to parse the header of the VCF file
(Single-VCF mode) or the first VCF file (Multi-VCF
mode), to display the list of available fields that users may choose to
import. A few considerations must be made:
"GT" key be
present in the FORMAT field.This mode display an action button that must be used to select the VCF file from which to import variants.
Action:
- Click on the Browse action button
- Navigate to the
extdatafolder of the TVTB installation directory- Select the file
chr15.phase3_integrated.vcf.gzAlternatively: click the Sample file button
This mode requires two pieces of information:
"%s" to declare the
emplacement of the sequence (i.e. chromosome) name in the
pattern.Note that a summary of VCF file(s) detected using the given the folder and pattern is displayed on the right, to help users determine whether the parameters are correct. In addition, the content of the given folder is displayed at the bottom of the page, beside the same content filtered for the VCF file naming pattern.
Action:
None. The text fields should already be filled with default values, pointing to the single example VCF file (
chr15.phase3_integrated.vcf.gz).
This panel allows users to select the INFO and FORMAT fields to
import (in the info and geno slots of the
VCF object, respectively).
It is important to note that the FORMAT/GT and INFO/<vep> stands for the INFO key where
Ensembl VEP predictions are stored—are implicitely imported from the
VCF. Similarly, the mandatory FIXED fields CHROM,
POS, ID, REF, ALT,
QUAL, and FILTER are automatically imported to
populate the rowRanges slot of the VCF
object.
Action:
- Click the Deselect all action button under the INFO fields selection input to import only the INFO/CSQ and FORMAT/GT fields.
- Click the Import variants action button
A summary of variants, phenotypes, and samples imported will appear beside the action button.
This panel allows users to select a pre-installed annotation package.
Currently, only EnsDb annotation packages are supported,
and only gene-coding regions may be queried.
Action:
- If none of the
EnsDbpackages are installed, it will simply not be possible to use theensemblinterface of the Genomic ranges input tab.- If the
EnsDb.Hsapiens.v75package is the onlyEnsDbpackages installed, no action is required; the package should already be pre-selected.- If the
EnsDb.Hsapiens.v75package is not the onlyEnsDbpackages installed, users should select it in the list of choices.
This panel demonstrates the use of three methods implemented in the
TVTB
package, namely addFrequencies,
addOverallFrequencies, and
addPhenoLevelFrequencies.
This panel allows users to Add and Remove INFO fields that contain genotype counts (i.e. homozygote reference, heterozygote, homozygote alternate) and allele frequencies (i.e. alternate allele frequency, minor allele frequency) calculated across all the samples and variants imported. The web-application uses the homozygote reference, heterozygote, and homozygote alternate genotypes defined in the Advanced settings panel.
Importantly, the name of the INFO keys that are used to store the calculated values can be defined in the Advanced settings panel.
Action:
- Click the Add action button
- See the Latest changes message update at the top of the screen.
- Optionally, the Views panel can be used to examine the new fields
This panel allows users to Refresh the list of INFO fields that contain genotype counts and allele frequencies calculated within groups of samples associated with various levels of a given phenotype.
Action:
- Select
super_popin the list of phenotypes- Click the Select all action button
- Click the Refresh action button
- See the Latest changes message update at the top of the screen.
- Optionally, the Views panel can be used to examine the new fields
One of the flagship features of the TVTB package
are the VCF filter rules, extending the S4Vectors
FilterRules class to new classes of filter rules that can
be evaluated within environments defined by the various slots of
VCF objects.
Generally speaking, FilterRules greatly facilitate the
design and combination of powerful filter rules for table-like objects,
such as the fixed and info slots of VariantAnnotation
VCF objects, as well as Ensembl VEP predictions stored in
the meta-columns of GRanges returned by the ensemblVEP
parseCSQToGRanges method.
A separate vignette describes in greater detail the use of classes that contain VCF filter rules. A simple example is shown below.
Action:
- Select
VEPas the Type of filter- Paste
grepl("missense",Consequence)in the text field- Leave the Active? checkbox ticked
- Click the Add filter action button
- See the list of rules update at the bottom of the screen
- Click the Apply filters action button
- See the summary of filtered variants update beside the action button
- Optionally, the Views panel can be used to examine the new fields
Alternatively: click the Sample input button
This panel offers the chance to examine the main objects of the session, namely:
rowRanges and selected meta-columns of the filtered
variants.info slot (of the filtered
variants).ggplot).Action:
- In the various panels, select fields to examine each object
- In particular, note the INFO fields that contain genotype counts and allele frequencies calculated earlier
- Go to the Heatmap tab of the Genotypes panel
- Click the Go! action button to calculate and display the heatmap
This panel demonstrates the use of two methods implemented in the
TVTB
package, namely tabulateVepByPhenotype and
densityVepByPhenotype.
This panel stores more advanced settings that users may not need to edit as frequently, if at all. Those settings are divided in two sub-panels:
It is critical to accurately identify and define how the different
genotypes—homozygote reference, heterozygote, and homozygote
alternate—are encoded in the VCF file, to produce accurate genotypes counts and frequencies, for instance.
This generally requires examining the content of the FORMAT/GT field
outside of the web-application. For instance, the functions
unique and table may be used to identify (and
count) all the distinct genotype codes in the geno slot
("GT" key) of a VCF object.
The default selected values are immediately compatible with the demonstration data set. Users who wish to select genotypes codes not yet available among the current choices may either contact the package maintainer to add them in a future release, or edit the Global configuration file of the web-application locally.
Currently, the three calculated genotypes counts and two allele frequencies require five INFO fields to store their respective values.
Considering that TVTB offers the possibility to calculate counts and frequencies for the overall data set, and for each level of each phenotype, it is important to define a clear and consistent naming mechanism that does not conflict with INFO keys imported from the VCF file(s). In the TVTB package, a suffix is required for each type of genotype and frequency calculated, to generate INFO as follows:
<suffix><phenotype>_<level>_<suffix>Again, the default values are immediately compatible with the demonstration data set. For other data sets, it may be necessary to change those values, either by preference, or to avoid conflict with INFO keys imported from the VCF file(s).
Other rarely used settings in this panel include:
Several functionalities of the TVTB package are applied to independent subsets of data (e.g. counting genotypes in various levels of a given phenotype). Such processes can benefit from multi-threaded calculations. Multi-threading settings in the Shiny web-application are somewhat experimental, as they have been validated only on a small set of operating systems, while some issues have been reported for others.
| Report | Operating System | Cluster Class | Cluster type | # Cores |
|---|---|---|---|---|
| OK | Ubuntu 14.04 | Multicore | FORK | 2 |
| OK | Scientific Linux 6.7 | Multicore | FORK | 2 |
| Hang1 | OS X El Capitan | Snow | SOCK | 2 |
The last panel of the Shiny Variant Explorer offers detailed views of objects and settings in the current session, including:
sessionInfo() valueVCF objectGRanges that store the Ensembl
VEP predictionsgeno slot ("GT"
key) of the raw variantsMost default values are stored in the global.R file of
the web-application. All the files of the web-application are stored in
the extdata/shinyApp folder of the TVTB
installation directory (see an earlier
section to identify this directory).
Users who wish to change the default values of certain input widgets
(e.g. genotype codes) may edit the global.R file
accordingly. However, the file will be reset at each package update.
Here is the output of sessionInfo() on the system on
which this document was compiled:
## R version 4.4.2 (2024-10-31)
## 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] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] TVTB_1.33.0 knitr_1.49 BiocStyle_2.35.0
##
## loaded via a namespace (and not attached):
## [1] RColorBrewer_1.1-3 sys_3.4.3
## [3] rstudioapi_0.17.1 jsonlite_1.8.9
## [5] magrittr_2.0.3 GenomicFeatures_1.59.1
## [7] farver_2.1.2 rmarkdown_2.29
## [9] BiocIO_1.17.1 zlibbioc_1.52.0
## [11] vctrs_0.6.5 memoise_2.0.1
## [13] Rsamtools_2.23.1 RCurl_1.98-1.16
## [15] base64enc_0.1-3 htmltools_0.5.8.1
## [17] S4Arrays_1.7.1 progress_1.2.3
## [19] curl_6.0.1 SparseArray_1.7.2
## [21] Formula_1.2-5 sass_0.4.9
## [23] bslib_0.8.0 htmlwidgets_1.6.4
## [25] plyr_1.8.9 Gviz_1.51.0
## [27] httr2_1.0.7 cachem_1.1.0
## [29] buildtools_1.0.0 GenomicAlignments_1.43.0
## [31] lifecycle_1.0.4 pkgconfig_2.0.3
## [33] Matrix_1.7-1 R6_2.5.1
## [35] fastmap_1.2.0 GenomeInfoDbData_1.2.13
## [37] MatrixGenerics_1.19.0 digest_0.6.37
## [39] colorspace_2.1-1 GGally_2.2.1
## [41] AnnotationDbi_1.69.0 S4Vectors_0.45.2
## [43] Hmisc_5.2-1 GenomicRanges_1.59.1
## [45] RSQLite_2.3.9 labeling_0.4.3
## [47] filelock_1.0.3 httr_1.4.7
## [49] abind_1.4-8 compiler_4.4.2
## [51] withr_3.0.2 bit64_4.5.2
## [53] pander_0.6.5 htmlTable_2.4.3
## [55] backports_1.5.0 BiocParallel_1.41.0
## [57] DBI_1.2.3 ggstats_0.7.0
## [59] biomaRt_2.63.0 rappdirs_0.3.3
## [61] DelayedArray_0.33.3 rjson_0.2.23
## [63] tools_4.4.2 foreign_0.8-87
## [65] nnet_7.3-19 glue_1.8.0
## [67] restfulr_0.0.15 grid_4.4.2
## [69] checkmate_2.3.2 reshape2_1.4.4
## [71] cluster_2.1.8 generics_0.1.3
## [73] gtable_0.3.6 BSgenome_1.75.0
## [75] ensembldb_2.31.0 tidyr_1.3.1
## [77] data.table_1.16.4 hms_1.1.3
## [79] xml2_1.3.6 XVector_0.47.0
## [81] BiocGenerics_0.53.3 pillar_1.10.0
## [83] stringr_1.5.1 limma_3.63.2
## [85] dplyr_1.1.4 BiocFileCache_2.15.0
## [87] lattice_0.22-6 deldir_2.0-4
## [89] rtracklayer_1.67.0 bit_4.5.0.1
## [91] EnsDb.Hsapiens.v75_2.99.0 biovizBase_1.55.0
## [93] tidyselect_1.2.1 maketools_1.3.1
## [95] Biostrings_2.75.3 gridExtra_2.3
## [97] ProtGenerics_1.39.0 IRanges_2.41.2
## [99] SummarizedExperiment_1.37.0 stats4_4.4.2
## [101] xfun_0.49 Biobase_2.67.0
## [103] statmod_1.5.0 matrixStats_1.4.1
## [105] stringi_1.8.4 UCSC.utils_1.3.0
## [107] lazyeval_0.2.2 yaml_2.3.10
## [109] evaluate_1.0.1 codetools_0.2-20
## [111] interp_1.1-6 tibble_3.2.1
## [113] BiocManager_1.30.25 cli_3.6.3
## [115] rpart_4.1.23 munsell_0.5.1
## [117] jquerylib_0.1.4 dichromat_2.0-0.1
## [119] Rcpp_1.0.13-1 GenomeInfoDb_1.43.2
## [121] dbplyr_2.5.0 png_0.1-8
## [123] XML_3.99-0.17 parallel_4.4.2
## [125] ggplot2_3.5.1 blob_1.2.4
## [127] prettyunits_1.2.0 jpeg_0.1-10
## [129] latticeExtra_0.6-30 AnnotationFilter_1.31.0
## [131] bitops_1.0-9 VariantAnnotation_1.53.0
## [133] scales_1.3.0 purrr_1.0.2
## [135] crayon_1.5.3 rlang_1.1.4
## [137] KEGGREST_1.47.0