User Guide

Running IMPACT-VIS
Authors
Affiliation

Nicholas Boehler

University of Toronto Mississauga

Hai-Ying Mary Cheng

University of Toronto Mississauga

Published

December 18, 2025

1 Quick Start

# 1. Clone the repository
git clone https://github.com/boehlernick/IMPACT-VIS.git
cd IMPACT-VIS

# 2. Install system prerequisites (Debian/Ubuntu/WSL)
sudo apt update
sudo apt install -y build-essential pkg-config cmake libnlopt-dev libcurl4-openssl-dev libssl-dev

# 3. Install R dependencies
R -e "install.packages('renv'); renv::restore(prompt = FALSE)"

# 4. Launch the app
R -e "shiny::runApp()"

# 5. Open the URL printed in the console (e.g., http://127.0.0.1:xxxx)

Done! You should see the IMPACT-VIS interface with demo sample data already loaded.

2 System Overview

NoteIMPACT Pipeline Integration

IMPACT-VIS is the visualization and curation layer of the broader IMPACT genomic interpretation pipeline.

Upstream Modules (Preprocessing):

  • IMPACT-SNV: Converts raw SNV VCF → annotated GDS files with IMPACT scoring

  • IMPACT-SV: Converts raw SV VCF → AnnotSV-annotated TSV files with phenotype filtering

  • IMPACT-CNV: Converts raw CNV VCF → SCIP-annotated TXT files with read-depth validation

This Guide: Setting up IMPACT-VIS to visualize outputs from upstream modules.

This quick-start uses demo data that has already been preprocessed by IMPACT modules.

3 Prerequisites

  • R ≥ 4.0 (download from https://www.r-project.org/)
  • Git (for cloning the repository)
  • System libraries (Debian/Ubuntu/WSL): build-essential, pkg-config, cmake, libnlopt-dev, libcurl4-openssl-dev, libssl-dev
  • 4 GB RAM minimum
  • Modern web browser (Chrome, Firefox, Safari, Edge)

Optional: Docker (for containerized deployment)

4 Installation Methods

4.2 Method 2: Docker

Encapsulates all dependencies; consistent across all systems.

Step 1: Build Image

git clone https://github.com/boehlernick/IMPACT-VIS.git
cd IMPACT-VIS
docker build -t impact-vis:latest .

Takes ~3-5 minutes first time (layer caching speeds up subsequent builds).

Step 2: Run Container

docker run -p 3838:3838 impact-vis:latest

Step 3: Open in Browser

http://localhost:3838

To use your own data:

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

4.3 Method 3: RStudio

If you prefer RStudio, you can launch from the IDE:

  1. Clone & open: File -> Open Project... and select the IMPACT-VIS folder (or File -> New Project -> Existing Directory).
  2. Install system prerequisites (Debian/Ubuntu/WSL terminal):
sudo apt update
sudo apt install -y build-essential pkg-config cmake libnlopt-dev libcurl4-openssl-dev libssl-dev
  1. Restore R packages (one-time): In the RStudio Console, run:
install.packages("renv")
renv::restore(prompt = FALSE)
  1. Run the app: Click the Run App button in the RStudio toolbar, or run in the Console:
shiny::runApp()
  1. Open the app: Use the URL printed in the RStudio Console (e.g., http://127.0.0.1:xxxx).
Note

On Windows without WSL, install Rtools and the libcurl/openssl build deps, or use the Docker method if native system libraries are unavailable.

5 First Analysis

5.1 Step 1: Initiate the app and select a sample

When IMPACT-VIS loads, you’ll see:

IMPACT-VIS sample selector

The app comes with a test_sample pre-loaded. However, you may simply add your input files to the /app/data directory and then select any valid sample from the dropdown.

5.2 Step 2: Plot Display Settings

In the Plot Settings panel (left sidebar), choose:

  • Chromosome to display
  • Maximum number of variants to be plotted on the GDS subplot
  • Override settings for maximum variants (caution: memory intensive)
  • Dynamic Y-axis scaling setting will automatically configure the GDS subplot Y-axis in accordance with IMPACT score values of variants currently displayed. Turning this setting off will restrict axis to 0-100.

5.3 Step 3: Apply Filters

Adjust filters to focus on variants of interest:

  • ClinVar Status: Pathogenic, VUS, Benign
  • Allele Frequency: Set threshold (default 1%)
  • Genotype: Heterozygous, Homozygous, Both

Click “Apply Filters” to update plot.

Tip

Start with default IMPACT quick filters, then progressively add custom filters as needed.

5.4 Step 4: Explore the Plot

Interact with the visualization:

  • Hover: See variant details (name, position, annotations)
  • Click: Open detailed variant modal with additional information
  • Zoom: Click + drag to zoom into region
  • Pan: Hold shift + drag to move around
  • Reset: Double-click to zoom out

5.5 Step 5: Export Results

In the Export panel:

  • CSV: Tabular variant data (for downstream analysis)
  • PNG: High-resolution plot (for presentations/publications)

6 Sample Data

The repository includes a demonstration sample in app/data/:

app/data/
├── test_sample_SNV_IMPACT.gds
├── test_sample_SV_IMPACT.tsv
└── test_sample_CNV_IMPACT.txt

6.1 About Demo Data

  • A small subset of randomly selected variants from UK Biobank whole-genome sequencing samples. All identifying features have been stripped from the variants and genotypes were programatically assigned. Therefore, while these variants have been identified in real samples, the configurations may not be real and should not be interpreted as such. The purpose of the test_sample is to allow users to quickly interact with IMPACT-VIS.

7 Using Your Own Data

This section assumes you have preprocessed variant files from the IMPACT pipeline modules. If you only have raw VCF files, you must first run IMPACT-SNV, IMPACT-SV, and/or IMPACT-CNV preprocessing.

7.1 Prerequisites

You must have completed upstream preprocessing to generate:

Data Type Expected File Required? Source
SNV/Indel {sample}_SNV_IMPACT.gds Yes IMPACT-SNV
Structural Variants {sample}_SV_IMPACT.tsv No IMPACT-SV
Copy Number Variants {sample}_CNV_IMPACT.txt No IMPACT-CNV

If you only have raw VCF files, see IMPACT-SNV Documentation to preprocess them first.

7.2 Step 1: Organize Your Files

Place all sample files directly in app/data/:

cd /path/to/IMPACT-VIS

# Copy preprocessed files
cp /path/to/sample001_SNV_IMPACT.gds app/data/
cp /path/to/sample001_SV_IMPACT.tsv app/data/
cp /path/to/sample001_CNV_IMPACT.txt app/data/

# Repeat for additional samples
Important

Files must be in app/data/ root directory, NOT in subdirectories. IMPACT-VIS auto-discovers samples by scanning for *_SNV_IMPACT.gds files.

7.3 Step 2: Launch IMPACT-VIS

R -e "shiny::runApp('app')"

Your samples will appear in the Sample Selector dropdown automatically.

7.4 Step 3: Verify Data Loaded

  1. Expand Sample Selector dropdown
  2. Check that your sample IDs appear
  3. Click “Refresh Data” if samples don’t immediately appear
  4. Select a sample and verify plot loads

For detailed troubleshooting, see Data Preparation.

8 Next Steps

9 Troubleshooting

9.1 “Error: GDS file not found”

Demo data not properly loaded.

Solution:

# Verify files exist
ls -la app/data/

# If missing, reinstall from GitHub
git clone https://github.com/boehlernick/IMPACT-VIS.git
cd IMPACT-VIS

9.2 “Slow performance / App hangs”

Too many variants to display.

Solution: Reduce the number of variants displayed using the “Top IMPACT Score SNV/Indels” slider in the Plot Settings panel.

9.3 Docker image won’t build

Dependency installation failed.

Solution:

# Rebuild without cache
docker build --no-cache -t impact-vis:latest .

# View full build log
docker build --progress=plain -t impact-vis:latest .

10 Support

  • Documentation: https://boehlernick.github.io/IMPACT-VIS
  • GitHub Issues: https://github.com/boehlernick/IMPACT-VIS/issues
  • Email: nick.boehler@mail.utoronto.ca (contact maintainer)

Next: Ready to load your own data? → Data Preparation

Document Version: 1.0.0
Last Updated: 2025-12-10