🧬 IGV De Novo Variant Review

✨ Features

Everything you need to review, curate, and export de novo variant calls from trio sequencing data.

🚀 Quick Start

Get up and running in under 5 minutes.

Prerequisites

Node.js 18+ is required. On HPC clusters, you can use Docker/Singularity instead (see Deployment).

Installation & Launch

# 1. Clone the repository
git clone https://github.com/jlanej/igv.js.git
cd igv.js

# 2. Build igv.js (from the repo root – only needed once)
npm install
npm run build

# 3. Install server dependencies
cd server
npm install

# 4. Start the server with your data
node server.js \
  --variants /path/to/your/variants.tsv \
  --data-dir /path/to/bam_cram_files \
  --sample-qc /path/to/sample_qc.tsv \
  --genome hg38 \
  --port 3000

# 5. Open in your browser
#    http://127.0.0.1:3000

Try with Example Data

The server includes example data for a quick demo (no alignment files needed – the table and filtering still work):

cd server
node server.js
# Open http://127.0.0.1:3000

CLI Options

📋 Variant Table

The main view for browsing and reviewing variants. All annotation columns from your TSV are displayed and sortable.

Key Capabilities

• Sortable columns – Click any column header to sort ascending (▲) or descending (▼). The current sort is indicated by an arrow icon.
• Search – Type in the search bar to perform case-insensitive substring search across all columns. Results update with a 300ms debounce.
• Pagination – Navigate through large variant sets with Previous/Next buttons. Page size defaults to 50 variants.
• Row selection – Check individual rows or use "Select all on page" for batch curation operations.
• Curation status – Each row displays a colored badge: Pass Fail Uncertain Pending. The entire row background is tinted to match.
• Click to view – Click any variant row to load its trio alignment tracks in the IGV viewer below the table.

Stats Bar

The header bar displays real-time statistics: total variant count, number currently shown (after filtering), and per-status curation tallies. These counts reflect all variants, not just the current page.

🔍 Dynamic Filtering

Filter variants using any combination of annotation columns. Filters are applied server-side for fast response on large datasets.

Filter Types

• Checkbox groups – For categorical columns with ≤10 unique values (e.g., gene, impact, inheritance, curation status). Check one or more values to include.
• Dropdown selectors – For categorical columns with >10 unique values. Select one or more from a dropdown menu.
• Range inputs – For numeric columns (e.g., frequency, quality). Set minimum and/or maximum values.

Filter Actions

• Apply Filters – Submit all current filter selections to the server and refresh the variant table.
• Clear All – Reset all filters to show all variants.
• 💾 Save Filters – Save the current filter configuration for later reuse.
• 📂 Load Filters – Restore a previously saved filter configuration.

Collapsible Groups

Each filter group can be collapsed or expanded individually by clicking the header. Use the ▼ Collapse All / ▲ Expand All button to toggle all groups at once.

Collapsible Sidebar

The entire filter sidebar can be collapsed using the ◀ toggle button or the keyboard shortcut Ctrl+B to maximize table and IGV viewer space.

✅ Curation Workflow

A streamlined workflow for reviewing and curating variants, designed for high-throughput sessions.

Step-by-Step Workflow

1. Filter variants

   Use the sidebar controls to narrow down to variants of interest (e.g., HIGH impact, de novo inheritance, low frequency).

2. Click a variant row

   The row highlights in blue and the IGV viewer loads the trio alignment tracks (child, mother, father) at the variant position.

3. Review trio alignments

   Examine read support in the child versus parents. Toggle display mode (Squished / Expanded / Collapsed) for different views.

4. Curate the variant

   Click ✓ Pass, ✗ Fail, or ? Uncertain. The table row updates its color immediately.

5. Add a note (optional)

   Type a free-text note in the curation note field. Use the "Previous notes…" dropdown to reuse common notes from prior curations.

6. Advance to the next variant

   Press j to jump to the next uncurated variant, or use P / F / U to curate and advance in one keystroke.

7. Export results

   When done, export your curated variant set as TSV or publication-quality XLSX.

Batch Curation

Select multiple variant rows using the checkboxes, then use the Quick Curation buttons in the sidebar to apply a curation status to all selected variants at once. This is useful for quickly failing a group of known artifacts.

Sample-Level Curation

The Sample Summary tab includes Flag Sample buttons (✓ ✗ ?) that let you curate all variants for an entire sample in one click.

Gene-Level Curation

Similarly, the Gene Summary tab includes Flag Gene buttons to curate all variants within a specific gene at once.

Curation Persistence

🧬 IGV Alignment Viewer

An embedded igv.js genome browser for reviewing trio alignment data directly in the web interface.

Viewer Components

• Variant metadata header – Shows gene symbol, genomic coordinates (e.g., chr1:12,345), allele change (A→G), and trio-specific metadata badges (AD, GQ, DKA/DKT values for each family member).
• Curation controls – Pass / Fail / Uncertain buttons, note suggestions dropdown, free-text note textarea, and Save Note button — all inline in the IGV header for efficient review.
• Genome browser – Full igv.js browser displaying child, mother, and father alignment tracks centered on the variant position. Supports BAM and CRAM formats.
• Display mode selector – Toggle between Squished, Expanded, and Collapsed read display modes for all alignment tracks simultaneously.
• Track load status – Color-coded badges showing whether each trio member's tracks loaded successfully, have no reads, or encountered errors.

VCF Track Support

Optionally load VCF tracks alongside alignments. VCF files can be specified:

• Per-trio – Via child_vcf, mother_vcf, father_vcf columns in the variant TSV, with corresponding *_vcf_index and *_vcf_id columns.
• Globally – Via the --vcf CLI flag, applying to all variants.

Shared multi-sample VCF files are de-duplicated automatically and loaded as a single track annotated with all sample roles.

Resizable Layout

A drag handle between the variant table and the IGV viewer allows you to resize the table height to allocate more or less screen space to the genome browser.

🧪 Gene Summary

Aggregate view of variants by gene, reflecting current filters. Useful for identifying genes with multiple candidate variants.

Columns

📈 Sample Summary

Per-sample variant counts and cohort-level statistics, broken down by impact and frequency thresholds.

Cohort Summary

Displays mean, median, and standard deviation of variant counts across all samples, stratified by impact level and frequency threshold. This helps identify samples with unusually high or low variant burdens.

Per-Sample Counts

Each row shows one sample/trio with:

• Total unfiltered variant count
• Variants passing current filters
• Curation breakdown: Pass Fail Uncertain Pending
• Variant counts per impact group × frequency threshold combination
• Flag Sample buttons for sample-level curation

🔬 Sample QC

Quality control metrics integration for flagging problematic samples before curation.

Load a per-sample QC file with --sample-qc <path> to enable QC integration. The QC file is a tab-separated file with columns for trio_id, role (proband/mother/father), sample_id, and any number of numeric QC metrics.

Freemix Thresholds

The freemix column (from VerifyBamID) is automatically classified:

UI Integration

• Sample QC tab – One row per trio showing each member's QC metrics with color-coded cells.
• Variant table QC badges – When a trio's trio_id matches the variant TSV, a colored dot + badge appears in the variant table's QC column.
• XLSX export – QC data is included as a styled "Sample QC" sheet.

Example QC File

trio_id	role	sample_id	freemix	mean_coverage
TRIO_A	proband	SAMPLE_001	0.005	35.2
TRIO_A	mother	SAMPLE_002	0.012	30.1
TRIO_A	father	SAMPLE_003	0.002	32.5
TRIO_B	proband	SAMPLE_004	0.045	28.3
TRIO_B	mother	SAMPLE_005	0.008	31.7
TRIO_B	father	SAMPLE_006	0.003	29.8

📊 Export

Download your curated variant data in multiple formats for downstream analysis and publication.

⌨️ Keyboard Shortcuts

Navigate and curate entirely from the keyboard for efficient high-throughput review sessions.

Action	Key
Next uncurated variant	j or ↓
Previous uncurated variant	k or ↑
Mark as Pass	p
Mark as Fail	f
Mark as Uncertain	u
Pass & advance to next	P (Shift+p)
Fail & advance to next	F (Shift+f)
Uncertain & advance to next	U (Shift+u)
Toggle keyboard shortcuts help	?
Toggle filter sidebar	Ctrl+B

Press ? at any time to display the shortcuts overlay in the bottom-right corner of the screen.

📄 Input File Format

The server reads a tab-separated variant file with a header row. Four columns are required; all others are auto-detected and made filterable.

Required Columns

Recommended Columns

Per-Trio VCF Columns

Additional columns (e.g., cadd_score, clinvar, gnomad_af) are automatically displayed in the variant table and made available as filter options.

Alignment File Paths

• Relative paths – Resolved relative to the --data-dir directory.
• Absolute URLs – https://… paths are served directly (useful for cloud-hosted BAMs).
• If index files follow standard naming (.bam.bai, .cram.crai) and are co-located, the index columns can be omitted.

🐳 HPC Deployment

Deploy on HPC clusters using Docker, Singularity/Apptainer, or native Node.js.

Docker / Singularity (Recommended)

Most HPC clusters don't have Node.js. Build a Docker image and convert to a Singularity SIF:

# Pull pre-built image from GitHub Container Registry
docker pull ghcr.io/jlanej/igv-variant-review:latest

# Or build locally from the repo root
docker build -t igv-variant-review .

# Convert to Singularity SIF
singularity build igv-variant-review.sif \
  docker://ghcr.io/jlanej/igv-variant-review:latest

Run with Singularity

singularity run \
  --bind /scratch/project/alignments:/data \
  --bind /scratch/project/denovo_variants.tsv:/variants.tsv \
  --bind /scratch/project/curation.json:/curation.json \
  igv-variant-review.sif \
  --variants /variants.tsv \
  --data-dir /data \
  --curation-file /curation.json \
  --port 8080

# Open browser: http://127.0.0.1:8080

SLURM Job Script

#!/bin/bash
#SBATCH --job-name=igv-review
#SBATCH --time=8:00:00
#SBATCH --mem=4G

singularity run \
  --bind /scratch/project/alignments:/data \
  --bind /scratch/project/denovo_variants.tsv:/variants.tsv \
  igv-variant-review.sif \
  --variants /variants.tsv \
  --data-dir /data \
  --port 3000

# Forward the port from a login node:
# ssh -L 3000:$SLURMD_NODENAME:3000 login-node

Native Node.js

If Node.js is available on your cluster (via module load or otherwise):

module load nodejs

cd /path/to/igv.js/server
npm install

node server.js \
  --variants /scratch/project/denovo_variants.tsv \
  --data-dir /scratch/project/alignments/ \
  --port 8080

# Open Firefox/Chrome: http://127.0.0.1:8080

Port Forwarding

When running on a remote compute node, forward the port to your local machine:

# From your local terminal:
ssh -L 3000:compute-node:3000 login-node

# Then open http://localhost:3000 in your local browser

🔌 REST API

The server exposes a RESTful API for programmatic access. All endpoints return JSON.

Variant Query Parameters

The /api/variants endpoint supports the following query parameters:

🏗️ Architecture

A lightweight Express server with an in-memory variant store and a single-page web UI.

igv.js/
├── server/
│   ├── server.js              # Express server & REST API
│   ├── logger.js              # Leveled logger with timestamps
│   ├── package.json           # Server dependencies
│   ├── public/
│   │   ├── index.html         # Web UI (single page)
│   │   ├── app.js             # Client-side application (~1000 lines)
│   │   └── styles.css         # Responsive styling
│   ├── example_data/
│   │   ├── variants.tsv       # Example variant file (10 variants)
│   │   └── sample_qc.tsv     # Example QC file
│   └── test/
│       └── server.test.js     # Integration tests (Mocha/Chai/Supertest)
├── js/                        # Core igv.js source
├── dist/                      # Built igv.js library
├── Dockerfile                 # Multi-stage Docker build
└── docs/
    └── index.html             # This documentation page

The server loads the variant TSV into memory at startup, serves a REST API for filtering, sorting, and curation, and provides a static file server for the web UI. The client-side application fetches data from the API and renders the UI dynamically. Curation state is persisted to a JSON file on disk.