Introduction to ClinicalVariantR
Introduction
ClinicalVariantR is a Shiny application
for evidence-based germline variant classification under the ACMG/AMP
2015 framework. This vignette walks through installing the package,
launching the app, and using the three prediction workflows —
Group A (clinical + curator), Group B
(rapid automated), and Group C (gene-panel automated) —
from annotated VCF files (VEP CSQ, SnpEff ANN,
or ANNOVAR-style INFO fields).
Vignette outline
| Section | Purpose |
|---|---|
| How the Shiny app is organised | Workflow overview figure |
| Installation | Bioconductor (submitted) vs GitHub (not yet) vs local |
| Run latest code for analysis | Avoid stale installs; reinstall / source launch |
| Launch the Shiny application | Start the app + app steps |
| Evaluated package checks | Constructors, samples, parser demos |
| Step-by-step Shiny walkthrough | Home and Group A / B / C actions |
| VCF annotation requirements | CSQ / ANN / ANNOVAR expectations |
| Sample inputs | Bundled example files |
| Troubleshooting | Common install and runtime issues |
The package builds on shiny and bslib for the interface, data.table for streaming tabular work, and VariantAnnotation for VCF handling.
How the Shiny app is organised
The top navbar lists Home, Group A, Group B, Group C, plus optional Explorer and Audit panels. Start on Home, pick a workflow card, upload inputs, wait for readiness checks, then click Run Analysis.
| Phase | Tabs | What you do |
|---|---|---|
| Orientation | Home | Choose Group A, B, or C |
| Rapid prediction | Group B | Upload VCF → validate → run → download |
| Panel prediction | Group C | Upload VCF + gene list → run filtered results |
| Clinical curation | Group A | Upload VCF + clinical + pedigree → curator toggles → run |
| Review | Explorer / Audit | Browse evidence and session metadata after a run |
ClinicalVariantR Shiny workflows. Each box corresponds to a navbar tab or analysis phase.
Installation
Follow the Bioconductor installation instructions and the official install guide so your R version matches a supported Bioconductor release (e.g. Bioconductor 3.22 for R 4.6). ClinicalVariantR requires R ≥ 4.6.0.
Always install with dependencies = TRUE
so Imports (shiny, bslib, DT, data.table, readr, jsonlite,
VariantAnnotation, …) are resolved once. The app does
not install packages at launch.
Pick the path that matches the package status:
| Status | Use this install |
|---|---|
| Accepted / available on Bioconductor | Section A — Bioconductor |
| Not yet on Bioconductor (current GitHub release) | Section B — GitHub |
| Local development clone | Section C — Local clone |
If Windows reports that the package is in use, use Session → Restart R before reinstalling or updating.
A — Bioconductor (when the package is submitted and available)
Use this after ClinicalVariantR is listed on Bioconductor (or when reinstalling / updating from the Bioconductor build):
# Session -> Restart R if ClinicalVariantR is already loaded
if (!requireNamespace("BiocManager", quietly = TRUE)) {
install.packages("BiocManager")
}
BiocManager::install("ClinicalVariantR", dependencies = TRUE)
library(ClinicalVariantR)
packageVersion("ClinicalVariantR") # expect 0.99.3To reinstall / recall the Bioconductor build after an update:
B — GitHub (when not yet on Bioconductor)
Until the package is on Bioconductor, install (or reinstall) from GitHub:
# Session -> Restart R if ClinicalVariantR is already loaded
options(timeout = 3600)
if (!requireNamespace("BiocManager", quietly = TRUE)) {
install.packages("BiocManager")
}
options(repos = BiocManager::repositories())
if (!requireNamespace("remotes", quietly = TRUE)) {
install.packages("remotes")
}
remotes::install_github(
"safarafique/ClinicalVariantR",
ref = "main",
dependencies = TRUE,
force = TRUE,
INSTALL_opts = "--no-staged-install"
)
library(ClinicalVariantR)
packageVersion("ClinicalVariantR") # expect 0.99.3C — Local clone (developers)
# Session -> Restart R first
if (!requireNamespace("remotes", quietly = TRUE)) {
install.packages("remotes")
}
remotes::install_local(
"E:/ACGM/ClinicalVariantR",
force = TRUE,
upgrade = "never",
dependencies = TRUE
)
library(ClinicalVariantR)Or launch the source tree without reinstalling (see Run latest code for analysis).
Run latest code for analysis
If you installed some time ago, reinstall with section A or B above
so inst/shinyapp/ is current, or launch from a local
clone:
Launch the Shiny application
Bioconductor Shiny apps return an app object from the package; users
start the server with shiny::runApp() (Bioconductor
Shiny guide).
After install (Bioconductor or GitHub):
ClinicalVariantR() returns a Shiny app
object; it does not open a browser by itself.
shiny::runApp(app, launch.browser = TRUE) starts the server
and opens your default browser. ClinicalVariantRApp() is an
alias of ClinicalVariantR().
App steps at a glance
After the browser opens:
- Home — read the three workflow cards and pick a mode.
- Group B (recommended first run) — upload annotated VCF → wait for readiness → Run Analysis → download CSV.
- Group C — upload VCF → paste gene symbols → Run Analysis → confirm panel-restricted results.
- Group A — upload VCF + clinical CSV + pedigree CSV → optional curator toggles → Run Analysis → review 28-criteria evidence → export.
- Explorer / Audit — after any successful run, browse evidence and session metadata.
| Step | Tab | Inputs | Action |
|---|---|---|---|
| 1 | Home | — | Choose Group A, B, or C |
| 2 | Group B | Annotated VCF | Validate → Run → download |
| 3 | Group C | VCF + gene list | Validate → Run → filtered table |
| 4 | Group A | VCF + clinical + pedigree | Validate → Run → curator / export |
| 5 | Explorer / Audit | Prior run results | Review evidence and logs |
Detailed click-by-click instructions are in Step-by-step Shiny walkthrough.
Evaluated package checks
The chunks below run during vignette builds. They do not open a browser.
stopifnot(is.function(ClinicalVariantR))
stopifnot(is.function(ClinicalVariantRApp))
app <- ClinicalVariantR()
stopifnot(inherits(app, "shiny.appobj"))
class(app)
#> [1] "shiny.appobj"length(ClinicalVariantR:::AUTOMATED_ACMG_CRITERIA)
#> [1] 18
ClinicalVariantR:::AUTOMATED_ACMG_CRITERIA
#> [1] "PVS1" "PS1" "PS4" "PM1" "PM2" "PM4" "PM5" "PP2" "PP3" "PP5"
#> [11] "BA1" "BS1" "BS2" "BP1" "BP3" "BP4" "BP6" "BP7"
ClinicalVariantR:::ACMG_CLASSIFICATIONS
#> [1] "Pathogenic" "Likely Pathogenic" "VUS"
#> [4] "Likely Benign" "Benign"ClinicalVariantR:::parse_gene_filter("TCF4, MECP2; EGR2\nBCR-ABL")
#> [1] "TCF4" "MECP2" "EGR2" "ABL1" "BCR"ClinicalVariantR:::combine_acmg_evidence(list(
PVS = 1L, PS = 0L, PM = 1L, PP = 1L,
BA = FALSE, BS = 0L, BP = 0L
))
#> [1] "Pathogenic"
ClinicalVariantR:::normalize_acmg_class("Likely_pathogenic")
#> Likely_pathogenic
#> "Likely Pathogenic"ClinicalVariantR:::vcf_app_requirements("rapid")
#> $required_columns
#> [1] "CHROM" "POS" "REF" "ALT"
#>
#> $standard_columns
#> [1] "CHROM" "POS" "ID" "REF" "ALT" "QUAL" "FILTER" "INFO"
#>
#> $info_fields
#> field tier
#> 1 CSQ required
#> 2 ANN required
#> 3 GENE recommended
#> 4 AF recommended
#> 5 REVEL recommended
#> used_for
#> 1 VEP consequence (PVS1, PM4, BP1, BP7, PP3)
#> 2 SnpEff consequence (PVS1, PM4, BP1, BP7, PP3)
#> 3 Gene symbol annotation
#> 4 Population allele frequency (BA1, BS1, PM2); gnomAD join if missing
#> 5 Computational pathogenicity (PP3, BP4); reference join if missing
#>
#> $mode
#> [1] "rapid"
#>
#> $notes
#> [1] "Group B uses automated rules only; clinical phenotype is not evaluated."
#> [2] "PS4 is applied automatically when a variant matches the case-control reference DB."
#> [3] "ClinVar and gnomAD are joined from reference files when absent in VCF."
ClinicalVariantR:::vcf_app_requirements("full")
#> $required_columns
#> [1] "CHROM" "POS" "REF" "ALT"
#>
#> $standard_columns
#> [1] "CHROM" "POS" "ID" "REF" "ALT" "QUAL" "FILTER" "INFO"
#>
#> $info_fields
#> field tier
#> 1 CSQ required
#> 2 ANN required
#> 3 GENE recommended
#> 4 AF recommended
#> 5 REVEL recommended
#> used_for
#> 1 VEP consequence (PVS1, PM4, BP1, BP7, PP3)
#> 2 SnpEff consequence (PVS1, PM4, BP1, BP7, PP3)
#> 3 Gene symbol annotation
#> 4 Population allele frequency (BA1, BS1, PM2); gnomAD join if missing
#> 5 Computational pathogenicity (PP3, BP4); reference join if missing
#>
#> $mode
#> [1] "full"
#>
#> $notes
#> [1] "Group A also requires Clinical Logs CSV and Pedigree CSV before analysis."
#> [2] "Manual ACMG criteria (PS2-PS4, PP1-PP2, PP4, PM6) need curator input regardless of VCF content."Step-by-step Shiny walkthrough
The sections below mirror the navbar tabs. For each workflow, read the goal, apply the settings under What to do, click Run Analysis, and confirm the success check before exporting results.
Home — choose a workflow
Navbar: Home
Goal: Orient yourself and open the right prediction mode.
What to do:
- Confirm the app title ClinicalVariantR — Variant Prediction Platform.
- Read the three landing cards:
- Group A — Clinical Prediction (VCF + clinical + pedigree; 28 criteria)
- Group B — Automated Prediction (VCF only; 18 automated criteria)
- Group C — Gene Panel Prediction (VCF + gene list; same engine as B)
- Click a card (or the matching navbar tab) to continue.
Success check: The selected Group tab opens with upload controls on the left and validation / results panels on the right.
Group B — Automated Prediction (start here)
Navbar:
Group B — Automated Prediction
Goal: Fastest smoke test — classify an annotated VCF with automated ACMG/AMP rules only.
What to do:
- Under Required Inputs, upload a VCF
(
.vcf/.vcf.gz), for exampledata/samples/example_variants.vcfor a Group B benchmark VCF. - Optionally set disease profile, Analyze entire VCF, PASS-only filter, minimum QUAL, chunk size, and bcftools (Ubuntu/WSL).
- Wait for VCF Requirement Check to report ready (CSQ / ANN / required fields present).
- Review the VCF Preview table.
- Click Run Analysis.
- Open Classification Results: summary counts, variant table, criteria / confidence.
- Download CSV (full report and/or expert worklist) when offered.
Success check: Readiness is green; results populate with Pathogenic / Likely Pathogenic / VUS / Likely Benign / Benign categories; CSV download works.
Group C — Gene Panel Prediction
Navbar:
Group C — Gene Panel Prediction
Goal: Same automated engine as Group B, restricted to nominated genes.
What to do:
- Upload the patient VCF.
- Paste HGNC gene symbols into Gene symbol(s), for example:
- Confirm readiness, then click Run Analysis.
- Verify that results are limited to the nominated gene set.
Success check: Only nominated genes appear in the filtered result table.
Group A — Clinical Prediction
Navbar:
Group A — Clinical Prediction
Goal: Full clinical mode with clinical logs, pedigree, and per-variant curator evidence (28-criteria reporting).
What to do:
- Upload VCF, Clinical Logs (CSV),
and Pedigree Data (CSV). Bundled examples:
data/samples/example_variants.vcfdata/samples/example_clinical_logs.csvdata/samples/example_pedigree.csv
- Wait until Group A readiness reports all three inputs validated.
- Optionally enable per-variant curator evidence after a first pass (e.g. PS2, PS3, PS4, PM6, PP1, PP4) in the evidence accordion.
- Click Run Analysis.
- Select a variant row to inspect 28-criteria detail; apply curator toggles and reclassify when appropriate.
- Export evidence / CSV downloads.
Success check: All three inputs validate; classification and evidence panels populate; curator overrides update the selected variant.
Explorer and Audit (after a run)
Navbar: Explorer /
Audit
Goal: Browse structured evidence and session metadata for completed analyses.
What to do:
- Complete at least one Group A, B, or C run.
- Open Explorer for report-style summaries and variant evidence.
- Open Audit for reproducibility / session logging (unless skip-audit was enabled).
Success check: Explorer is not empty after a successful run.
VCF annotation requirements
ClinicalVariantR expects a pre-annotated VCF. At least one of the following should be present:
| Annotation style | Typical INFO / field | Notes |
|---|---|---|
| VEP | CSQ |
Preferred for transcript consequences |
| SnpEff | ANN |
Accepted alternative |
| ANNOVAR-style | INFO key/value fields | Supported when required columns resolve |
Optional but helpful fields (when available) improve automated criteria: population frequencies, computational predictions, ClinVar assertions, and gene / consequence annotations used by PVS1 and related rules.
Group A additionally requires:
- Clinical logs CSV — phenotype / clinical context for curator-assisted criteria
- Pedigree CSV — family structure for segregation-related evidence
Sample inputs
Installed packages ship samples under
inst/extdata/samples/ and
inst/shinyapp/data/samples/. Development clones may still
have a package-root data/samples/ tree (ignored by the
package build).
extdata_samples <- system.file("extdata", "samples", package = "ClinicalVariantR")
sample_files <- c(
"example_variants.vcf",
"example_clinical_logs.csv",
"example_pedigree.csv"
)
sample_paths <- file.path(extdata_samples, sample_files)
data.frame(
resource = sample_files,
path = sample_paths,
exists = file.exists(sample_paths)
)
#> resource
#> 1 example_variants.vcf
#> 2 example_clinical_logs.csv
#> 3 example_pedigree.csv
#> path
#> 1 /tmp/RtmpmulrXJ/Rinst193e4b07c3d/ClinicalVariantR/extdata/samples/example_variants.vcf
#> 2 /tmp/RtmpmulrXJ/Rinst193e4b07c3d/ClinicalVariantR/extdata/samples/example_clinical_logs.csv
#> 3 /tmp/RtmpmulrXJ/Rinst193e4b07c3d/ClinicalVariantR/extdata/samples/example_pedigree.csv
#> exists
#> 1 TRUE
#> 2 TRUE
#> 3 TRUEvcf_path <- system.file(
"extdata", "samples", "example_variants.vcf",
package = "ClinicalVariantR"
)
stopifnot(nzchar(vcf_path), file.exists(vcf_path))
writeLines(readLines(vcf_path, n = 8L))
#> ##fileformat=VCFv4.2
#> ##source=CML_Variant_Interpreter_Example
#> #CHROM POS ID REF ALT QUAL FILTER INFO
#> chr22 23631806 . A G . PASS GENE=BCR;CSQ=missense_variant;AF=0.00012;REVEL=0.82
#> chr22 23632600 . C T . PASS GENE=ABL1;CSQ=missense_variant;AF=0.0;REVEL=0.22
#> chr9 133738352 . G A . PASS GENE=ABL1;CSQ=stop_gained;AF=0.00045;REVEL=0.91
preview <- ClinicalVariantR:::preview_vcf(vcf_path, max_rows = 5L)
preview$total_variants
#> [1] 3
preview$preview
#> chrom pos ref alt gene all_genes consequence annotation_source
#> 1 chr22 23631806 A G <NA> BCR <NA> CSQ
#> 2 chr22 23632600 C T <NA> ABL1 <NA> CSQ
#> 3 chr9 133738352 G A <NA> ABL1 <NA> CSQ
#> population_af qual filter
#> 1 NA . PASS
#> 2 NA . PASS
#> 3 NA . PASShdr <- c("CHROM", "POS", "ID", "REF", "ALT", "QUAL", "FILTER", "INFO")
line <- "chr9\t133738352\t.\tG\tA\t.\tPASS\tGENE=ABL1;CSQ=stop_gained;AF=0.00045;REVEL=0.91"
ClinicalVariantR:::parse_vcf_line(line, hdr)
#> variant_id variant_key chrom pos ref alt gene all_genes
#> 1 chr9:133738352:G:A chr9:133738352:G:A chr9 133738352 G A <NA> ABL1
#> consequence impact hgvs_c hgvs_p protein_position amino_acids exon biotype
#> 1 <NA> <NA> <NA> <NA> <NA> <NA> <NA> <NA>
#> is_canonical_transcript is_protein_coding rsids annotation_source
#> 1 FALSE FALSE <NA> CSQ
#> genome_build_hint af_1000g af_esp6500 population_af gnomad_af popmax_af sift
#> 1 GRCh38 NA NA NA NA NA <NA>
#> sift_score polyphen polyphen_score revel_score REVEL cadd spliceai_max
#> 1 NA <NA> NA 0.91 0.91 NA NA
#> alphamissense_score clinvar_classification ClinVar info_csq qual filter
#> 1 NA <NA> <NA> stop_gained NA PASS
#> sample_genotypes
#> 1 {}| File | Use for |
|---|---|
example_variants.vcf |
Quick smoke test (few variants) |
example_clinical_logs.csv |
Group A clinical companion |
example_pedigree.csv |
Group A pedigree companion |
Troubleshooting
| Problem | Solution |
|---|---|
package is in use and will not be installed |
Session → Restart R, then reinstall from the clone or GitHub. |
Unable to locate global.R / ui.R /
server.R |
Reinstall after restart so inst/shinyapp/ is installed;
or shiny::runApp("E:/ACGM/ClinicalVariantR"). |
| Browser does not open | Copy the http://127.0.0.1:xxxx URL from the R
console. |
| VCF not ready / missing CSQ or ANN | Re-annotate with VEP or SnpEff before upload. |
| Group A blocked | Provide clinical logs and pedigree CSV in addition to the VCF. |
| Group C empty results | Gene symbols must intersect annotated gene names in the VCF. |
| Locked DLL files (Windows) | Restart R (Ctrl+Shift+F10) before installing or
launching. |
| Large VCF slow on Windows | Prefer Ubuntu/WSL with bcftools enabled in the analysis options. |
| Missing Imports (shiny, DT, …) | Reinstall ClinicalVariantR with
dependencies = TRUE. |
| Corrupt lazy-load database | Restart R, then reinstall with no-staged-install options. |
Interactive launch (copy into an R console; not evaluated here):
Session Information
sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.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.32.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=en_US.UTF-8
#> [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] ClinicalVariantR_0.99.3 BiocStyle_2.41.0
#>
#> loaded via a namespace (and not attached):
#> [1] tidyselect_1.2.1 dplyr_1.2.1
#> [3] farver_2.1.2 blob_1.3.0
#> [5] Biostrings_2.81.9 S7_0.2.2
#> [7] bitops_1.1-0 fastmap_1.2.0
#> [9] RCurl_1.98-1.20 VariantAnnotation_1.59.4
#> [11] promises_1.5.0 GenomicAlignments_1.49.2
#> [13] XML_3.99-0.25 digest_0.6.39
#> [15] mime_0.13 lifecycle_1.0.5
#> [17] KEGGREST_1.53.6 RSQLite_3.53.3
#> [19] magrittr_2.0.5 compiler_4.6.1
#> [21] rlang_1.3.0 sass_0.4.10
#> [23] tools_4.6.1 yaml_2.3.12
#> [25] data.table_1.18.6.1 rtracklayer_1.73.0
#> [27] knitr_1.52 askpass_1.2.1
#> [29] S4Arrays_1.13.2 labeling_0.4.3
#> [31] htmlwidgets_1.6.4 bit_4.6.0
#> [33] curl_8.0.0 DelayedArray_0.39.7
#> [35] RColorBrewer_1.1-3 abind_1.4-8
#> [37] BiocParallel_1.47.0 withr_3.0.3
#> [39] BiocGenerics_0.59.12 sys_3.4.3
#> [41] grid_4.6.1 stats4_4.6.1
#> [43] xtable_1.8-8 ggplot2_4.0.3
#> [45] scales_1.4.0 SummarizedExperiment_1.43.0
#> [47] cli_3.6.6 rmarkdown_2.32
#> [49] crayon_1.5.3 generics_0.1.4
#> [51] otel_0.2.0 tzdb_0.5.0
#> [53] httr_1.4.9 rjson_0.2.23
#> [55] BiocBaseUtils_1.15.1 DBI_1.3.0
#> [57] cachem_1.1.0 parallel_4.6.1
#> [59] AnnotationDbi_1.75.2 BiocManager_1.30.27
#> [61] XVector_0.53.0 restfulr_0.0.17
#> [63] matrixStats_1.5.0 vctrs_0.7.3
#> [65] Matrix_1.7-6 jsonlite_2.0.0
#> [67] hms_1.1.4 IRanges_2.47.5
#> [69] S4Vectors_0.51.10 bit64_4.8.6
#> [71] GenomicFeatures_1.65.0 maketools_1.3.2
#> [73] jquerylib_0.1.4 glue_1.8.1
#> [75] codetools_0.2-20 DT_0.34.0
#> [77] gtable_0.3.6 later_1.4.8
#> [79] GenomicRanges_1.65.4 BiocIO_1.23.3
#> [81] tibble_3.3.1 pillar_1.11.1
#> [83] htmltools_0.5.9 Seqinfo_1.3.2
#> [85] openssl_2.4.2 BSgenome_1.81.1
#> [87] R6_2.6.1 shiny_1.14.0
#> [89] evaluate_1.0.5 lattice_0.23-1
#> [91] Biobase_2.73.2 readr_2.2.0
#> [93] png_0.1-9 Rsamtools_2.29.0
#> [95] cigarillo_1.3.1 memoise_2.0.1
#> [97] httpuv_1.6.17 bslib_0.12.0
#> [99] Rcpp_1.1.2 SparseArray_1.13.3
#> [101] xfun_0.61 MatrixGenerics_1.25.0
#> [103] buildtools_1.0.0 pkgconfig_2.0.3