Genetics-Viz 🧬

A web-based visualization tool for genetics cohort data, providing interactive analysis and validation of genetic variants.

Features

Core Features

• 📊 Multi-Cohort Management - Browse and analyze multiple cohorts from a single data directory
• 👨‍👩‍👧‍👦 Family Structure Visualization - View pedigree information and family relationships
• 🧬 Variant Analysis - Interactive TanStack-powered tables for DNM (de novo mutations) and WOMBAT analysis
• 🔍 Cohort-Wide Search - Search variants across all samples with filters on locus, genesets, impact, individuals (sex, phenotype, parental status), and validation status
• 📈 Variant Statistics - Interactive charts (chromosome distribution, consequence/validation pie charts) and ideogram visualization with cytoband rendering
• ✅ Variant Validation - Track and validate genetic variants with inheritance patterns
• 🔬 IGV Integration - Built-in IGV.js browser for sequence visualization (CRAM files)
• 🌊 WAVES Validation - Specialized validation workflow for bedGraph/coverage analysis
• 🔐 Authentication & Authorization - YAML-configured user accounts with role-based access (reader, curator, administrator)
• 📂 Multi-Data-Directory - Switch between multiple data directories per user session via YAML config
• 🛠️ Admin Pages - Manage users and data directories from the web interface
• 🎨 Modern UI - Clean, responsive interface built with NiceGUI

Validation Features

• Save validation status (present/absent/uncertain/different/in phase MNV)
• Track inheritance patterns (de novo/paternal/maternal/not paternal/not maternal/either/homozygous)
• Add optional comments to validations
• Mark validations as ignored (excluded from statistics and conflict detection)
• View validation history with timestamps and ignore status
• Interactive validation guide accessible via info button
• Filter variants by validation status
• Automatic conflict detection (ignoring validations marked as ignored)
• Export validation data

Installation

Quick Start with uvx (Recommended)

The easiest way to run genetics-viz without installation:

uvx genetics-viz /path/to/config.yaml

From PyPI

pip install genetics-viz

From Source

# Clone the repository
git clone https://github.com/bourgeron-lab/genetics-viz.git
cd genetics-viz

# Install with uv (recommended)
uv sync
uv run genetics-viz /path/to/config.yaml

# Or install with pip
pip install -e .
genetics-viz /path/to/config.yaml

Alternative: Local Python/Virtualenv

# Create a virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install genetics-viz
pip install genetics-viz

# Run the application
genetics-viz /path/to/config.yaml

Configuration

YAML Config File

The application requires a YAML configuration file listing data directories and users:

data_directories:
  - path: /path/to/data/directory1
    description: "Primary WGS data"
    default: true
  - path: /path/to/data/directory2
    description: "Secondary dataset"

user_list:
  - username: admin
    password: "<sha512-hex-digest>"
    role: administrator
  - username: curator1
    password: "<sha512-hex-digest>"
    role: curator
  - username: viewer
    password: "<sha512-hex-digest>"
    role: reader

# Optional. Root of the ancestry/PGS references tree, holding one
# v<bundle_version>/ subdirectory per reference bundle. The version to use is
# derived from the per-family data filenames, so it is not configured here.
# Without this key, the Ancestry tab still plots each family's own samples but
# cannot draw the reference panel behind them.
ancestry_reference_dir: /path/to/references/ancestry-pgs

# Auto-generated on first run — do not edit manually
storage_secret: "<hex-string>"

Generating Password Hashes

echo -n "your_password" | sha512sum | cut -d' ' -f1

User Roles

Initial Setup

1. Create a YAML config file with at least one data directory and one administrator user
2. Generate the admin password hash (see above)
3. Run: genetics-viz /path/to/config.yaml
4. Log in with admin credentials at http://localhost:8080/login
5. Use the admin pages to add more users and data directories

Usage

Command Line Options

# Basic usage
genetics-viz /path/to/config.yaml

# With custom host and port
genetics-viz /path/to/config.yaml --host 0.0.0.0 --port 8080

# Full help
genetics-viz --help

Web Interface

Once started, open your browser to http://localhost:8080 (or the specified port). You will be redirected to the login page.

The interface provides:

• Home Page - List of available cohorts
• Cohort View - Family list and overview
• Family View - DNM, WOMBAT, and SV analysis tabs with TanStack tables
• Search Page - Cohort-wide variant search with tabbed filters (Variants and Individuals)
• Variant Statistics - Charts and ideogram views for search results
• Validation Pages - Track variant validations (file-specific and all validations)
• Diagnostic Pages - Track variant diagnostic conclusions
• WAVES Validation - Specialized coverage/bedGraph validation workflow
• Profile Page - View role and change password
• Admin Pages - Manage data directories and users (administrators only)

Data Directory Structure

The tool expects the following directory structure:

data_directory/
├── cohorts/
│   ├── cohort1/
│   │   ├── cohort1.pedigree.tsv
│   │   ├── cohort1.params.yml (optional: ghfc-ngs workflow parameters)
│   │   ├── .ghfc-ngs.state.json (optional: written by the workflow, run record)
│   │   ├── wombat/
│   │   │   └── cohort1.rare.*.*.results.tsv (cohort-wide search files)
│   │   └── families/
│   │       ├── FAM001/
│   │       │   ├── FAM001.wombat.*.tsv (WOMBAT analysis files)
│   │       │   └── FAM001.dnm.*.tsv (DNM analysis files)
│   │       └── FAM002/
│   │           └── ...
│   └── cohort2/
│       └── ...
├── params/
│   └── genesets/
│       └── *.tsv (gene set files for search filtering)
├── samples/
│   ├── SAMPLE001/
│   │   └── sequences/
│   │       ├── SAMPLE001.GRCh38_GIABv3.cram
│   │       ├── SAMPLE001.GRCh38_GIABv3.cram.crai
│   │       └── SAMPLE001.GRCh38.bedGraph.gz (for WAVES)
│   └── SAMPLE002/
│       └── ...
└── validations/
    ├── snvs.tsv (variant validations)
    └── waves.tsv (WAVES validations)

Required Files

A cohort is any directory under cohorts/, and the directory name is the cohort name. A directory whose <name>.pedigree.tsv is missing or unreadable is listed on the home page as an incomplete cohort rather than being skipped, and is not explorable until the pedigree is in place.

Optional Workflow Files

cohort1.params.yml is the parameter file the ghfc-ngs workflow was launched with. When it is present, the cohort page gains two tabs: Parameters, which shows the file verbatim, and Status, which shows per-step pipeline progress. The home page card gains a foldable Status item with the same per-step breakdown.

.ghfc-ngs.state.json is the workflow's own run record (see COHORT_STATE.md in the ghfc-ngs repository) and is written only by the pipeline. It supplies the run status, timings and the per-step completion counts; genetics-viz reads it and never measures completion itself. Its absence is reported as "no run recorded", which is not the same as the cohort never having been processed.

Pedigree File Format

Pedigree files (cohort_name.pedigree.tsv) should be tab-separated. The header is optional - if present, it must start with "FID" (a leading # is stripped automatically):

With header:

#FID	IID	PAT	MAT	SEX	PHENOTYPE
FAM001	SAMPLE001	SAMPLE003	SAMPLE004	1	2
FAM001	SAMPLE002	0	0	2	1

Without header (positional columns):

FAM001	SAMPLE001	SAMPLE003	SAMPLE004	1	2
FAM001	SAMPLE002	0	0	2	1

Missing/unknown values for parent IDs are 0, -9, or empty. These values are also treated as unknown for sex and phenotype when building filter options.

Column Mapping (case-insensitive, # prefix stripped):

CRAM Files (for IGV visualization)

• Format: SAMPLE_ID.GRCh38_GIABv3.cram
• Index: SAMPLE_ID.GRCh38_GIABv3.cram.crai
• Location: samples/SAMPLE_ID/sequences/

BedGraph Files (for WAVES validation)

• Format: SAMPLE_ID.GRCh38.bedGraph.gz
• Location: samples/SAMPLE_ID/sequences/

Analysis Files

• DNM files: FAMILY_ID.dnm.*.tsv (must contain chr:pos:ref:alt column)
• WOMBAT files: FAMILY_ID.wombat.*.tsv (must contain #CHROM, POS, REF, ALT columns)

GHFC Lab Usage

Prerequisites

You need to either:

• Be on the Institut Pasteur network, OR
• Be connected via VPN

Mounting ghfc_wgs from Helix

On macOS

# Mount the network drive
# In Finder: Go > Connect to Server (⌘K)
# Enter: smb://helix.pasteur.fr/ghfc_wgs
# Or via command line:
open 'smb://helix.pasteur.fr/projects/ghfc_wgs'

The drive will be mounted at /Volumes/ghfc_wgs

On Linux

# Create mount point
sudo mkdir -p /mnt/ghfc_wgs

# Mount via CIFS
sudo mount -t cifs //helix.pasteur.fr/projects/ghfc_wgs /mnt/ghfc_wgs -o username=YOUR_USERNAME,domain=PASTEUR

# Or add to /etc/fstab for automatic mounting:
# //helix.pasteur.fr/projects/ghfc_wgs /mnt/ghfc_wgs cifs username=YOUR_USERNAME,password=YOUR_PASSWORD,domain=PASTEUR,uid=1000,gid=1000 0 0

Running genetics-viz for GHFC Data

Method 1: Using uvx (Recommended - No Installation)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run directly with uvx
uvx genetics-viz /path/to/genetics_viz.yaml

# On Linux (adjust path):
uvx genetics-viz /path/to/genetics_viz.yaml

Method 2: Using uv with Local Installation

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install genetics-viz
uv pip install genetics-viz

# Run the application
genetics-viz /path/to/genetics_viz.yaml

Access the Application

Once started, open your browser to:

http://localhost:8080

To access from other machines on the network:

genetics-viz /path/to/genetics_viz.yaml --host 0.0.0.0 --port 8080

Then access via: http://YOUR_MACHINE_IP:8080

Validation Workflow

SNV Validation

1. Navigate to a variant table (DNM or WOMBAT tabs, or Validation pages)
2. Click "View in IGV" button for a variant
3. In the dialog:
   • Review variant details with collapsible sections
   • Add additional samples (parents, siblings, or by barcode)
   • Examine CRAM tracks in IGV viewer
   • Click the info button (ℹ️) to view validation guidelines
   • Set validation status (default: present) and inheritance pattern
   • Add an optional comment
   • Click "Save Validation"
4. The validation is saved to validations/snvs.tsv
5. View validation history below the form
   • Toggle the "Ignore" switch to exclude validations from statistics
   • Ignored validations appear with reduced opacity
6. Validation/all page aggregates multiple validations per variant/sample
   • Shows unique list of users who validated each variant
   • Computes final status from non-ignored validations

WAVES Validation

1. Go to "Validation" > "Waves" in the menu
2. Select a cohort and pedigree
3. Select a sample from the pedigree
4. Click "View on IGV" for the sample
5. In the dialog:
   • Review bedGraph coverage tracks for the sample
   • Add additional samples for comparison
   • Set validation status
   • Click "Save Validation"
6. The validation is saved to validations/waves.tsv

Development

# Clone repository
git clone https://github.com/bourgeron-lab/genetics-viz.git
cd genetics-viz

# Install with development dependencies
uv sync --dev

# Run tests
uv run pytest

# Run linter
uv run ruff check .

# Format code
uv run ruff format .

# Run with auto-reload for development
uv run genetics-viz --reload /path/to/config.yaml

Validation File Formats

SNV Validations (validations/snvs.tsv)

Version 0.2.0+ format:

FID Variant Sample User Inheritance Validation Comment Ignore Timestamp
FAM001 chr1:12345:A:T SAMPLE001 username de novo present Initial validation 0 2026-01-18T10:30:00
FAM001 chr1:12345:A:T SAMPLE001 reviewer homozygous present Confirmed 0 2026-01-19T14:20:00
FAM002 chr2:67890:G:C SAMPLE002 username unknown uncertain Low coverage 1 2026-01-18T11:00:00

Columns:

• FID: Family ID
• Variant: chr:pos:ref:alt format
• Sample: Sample ID
• User: Username who performed validation
• Inheritance: de novo, paternal, maternal, not paternal, not maternal, either, homozygous, or unknown
• Validation: present, absent, uncertain, different, or "in phase MNV"
• Comment: Optional free-text comment
• Ignore: 0 (included) or 1 (excluded from statistics and conflict detection)
• Timestamp: ISO format timestamp

Migration from v0.1.1:

If upgrading from v0.1.1, use the provided migration script:

./utils/snvs_validations_migration_0.1.1_to_0.2.0.sh /path/to/data/validations/snvs.tsv

This adds the Comment and Ignore columns with default values.

WAVES Validations (validations/waves.tsv)

Cohort Pedigree Sample User Validation Timestamp
cohort1 FAM001 SAMPLE001 username present 2026-01-18T10:30:00

Troubleshooting

Cannot access GHFC data

• Verify VPN connection or Pasteur network access
• Check that ghfc_wgs is properly mounted
• Verify mount path (/Volumes/ghfc_wgs on macOS, /mnt/ghfc_wgs on Linux)

IGV not displaying

• Ensure CRAM files and indices (.crai) exist
• Check that files follow naming convention: SAMPLE_ID.GRCh38_GIABv3.cram
• Verify IGV.js is loading (check browser console)

Pedigree file not recognized

• Ensure tab-separated format
• Verify required columns are present
• Check file naming: cohort_name.pedigree.tsv

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

For detailed changes between versions, see CHANGELOG.md.

License

MIT License - See LICENSE file for details

Citation

If you use this tool in your research, please cite:

Genetics-Viz: A web-based visualization tool for genetics cohort data
GitHub: https://github.com/bourgeron-lab/genetics-viz

Support

For issues, questions, or feature requests, please open an issue on GitHub: https://github.com/bourgeron-lab/genetics-viz/issues