IMPACT-VIS: Interactive Visualization for Genomic Variant Interpretation

A web-based interactive visualization platform for exploring genomic variants produced by the IMPACT preprocessing workflows. Part of IMPACT, an open-source framework for unified, phenotype-guided variant interpretation.

Overview

IMPACT-VIS is an R Shiny application for interactive exploration of genomic variants. It provides a unified visualization interface for variant interpretation workflows, supporting exploration of:

• SNV/Indels (via GDS files from IMPACT-SNV preprocessing)
• Structural Variants (via AnnotSV TSV files from IMPACT-SV preprocessing)
• Copy Number Variants (via TXT files from IMPACT-CNV preprocessing)

Key Features

• Interactive multi-panel visualization: Simultaneous view of SNVs, SVs, and CNVs in a stacked, linked layout
• High-resolution plot export: Download the current combined plot view as a PNG from the Plotly toolbar camera button
• Interactive tabular views: Compact DT-based SNV and SV tables with full-row context and click-to-modal workflow
• Curated table export: Download curated SNV/Indel, SV, and CNV annotations as a ZIP archive of CSV files
• Dynamic filtering: Filter variants by tier, gene, annotation fields, BRAVO frequency, and QC status
• Per-variant annotation: Add notes, classifications, and custom tags; persist annotations per sample
• Genome-wide and single-chromosome views: Toggle between aggregate genome-wide analysis and detailed region inspection
• Data-on-disk processing: SeqArray-based GDS handling for memory-efficient exploration of large variant sets
• Reproducible environment: Docker support for consistent deployment across platforms

Getting Started

Requirements

• R >= 4.0
• renv for dependency management (see renv.lock)
• Bioconductor packages: SeqArray, SeqVarTools (installed via renv)

Run Locally (Development)

Option 1: Direct R

# from repo root
Rscript install.R
R -e "shiny::runApp()"

Option 2: RStudio Open the project in RStudio, restore the environment if needed with renv::restore(prompt = FALSE), then run shiny::runApp() from the Console.

Option 3: Docker

docker build -t impact-vis:latest .
docker run -p 3838:3838 impact-vis:latest

Then visit http://localhost:3838 in your browser.

To run the container against your own data directory, mount it into app/data/ inside the image:

docker run -p 3838:3838 \
  -v /path/to/your/data:/app/app/data:ro \
  impact-vis:latest

Try with Sample Data

Test sample files are included in app/data/test_sample_*. The app will load these automatically on startup, so you can begin exploring immediately without providing your own data.

Data Format & Loading

Place sample files into app/data/ using these naming patterns (outputs from IMPACT preprocessing):

• GDS SNV/Indel data: <sample>_SNV_IMPACT.gds + <sample>_SNV_IMPACT.gds_variant_states.rds (annotation persistence)
• SV data: <sample>_SV_IMPACT.tsv (AnnotSV format with READ_SUPPORT_FILTERING)
• CNV data: <sample>_CNV_IMPACT.txt (headerless 6-column format with QC interpretation)

For format details and validation, see Input Specifications.

Demo Fixture: Run Rscript scripts/build_test_sample_fixture.R to rebuild the bundled test_sample_* files in app/data/.

Testing

Unit tests are in tests/testthat/. Run all tests with:

R -e "testthat::test_dir('tests/testthat')"

Or in Docker:

docker run --rm impact-vis:latest R -e "testthat::test_dir('tests/testthat')"

For end-to-end tests, see .github/workflows/.

Data Persistence & State Management

Per-sample annotation states (variant notes, classifications, tags) are persisted as RDS files under app/data/. This approach is suitable for single-user or small-team deployments. For production or multi-user scenarios, consider migrating to a database-backed adapter (SQLite, PostgreSQL).

For performance tuning and advanced configuration, see Quick Start Guide.

Documentation

📖 Full Documentation: Visit the IMPACT-VIS Documentation Site for comprehensive guides, schema references, and technical information.

Quick Links:

• Quick Start Guide: Installation, first steps, and workflow tutorial
• Methods Documentation: Architecture, workflows, and implementation notes
• Input Specifications: Supported file layouts and validation flow
• GDS Format: SNV/Indel GDS expectations
• SV Format: AnnotSV TSV expectations
• CNV Format: SCIP TXT expectations
• Contributing: Development setup and code style
• Changelog: Release history and updates

License

This project is released under the MIT License. See LICENSE.

Contributing

We welcome issues, bug reports, and pull requests. Please see CONTRIBUTING.md for guidelines on development setup and code style.