Table of Contents

• Overview
• Key Features
• Architecture
• Installation
• Quick Start
• CLI Reference
• Input Formats
• Output Structure
• Configuration
• Variant Scoring
• Pathway Enrichment
• Dashboard
• Cohort and Family Analysis
• Reproducibility
• Citation
• License

Overview

VariantFlow is a modular, extensible Python platform designed for downstream analysis of ANNOVAR-annotated genomic variant files. It is built for clinical genomics research and is intended for publication in journals such as BMC Genomics, Bioinformatics, and Briefings in Bioinformatics.

The platform takes a standard ANNOVAR multianno file as input and executes a complete, auditable analysis pipeline — from raw variant filtering through to HTML, Excel, and PDF reports — without requiring any manual column mapping or configuration.

Key Features

Architecture

variantflow/
├── core/               # Data models (Pydantic), exceptions, logging, pipeline orchestrator
├── io/                 # ColumnMapper, MultiannoReader — auto-detect all ANNOVAR fields
├── filters/            # Quality, population frequency, functional, exonic, ACMG filters
├── annotations/        # ClinVar engine, InterVar ACMG evidence parser
├── scoring/            # Transparent multi-factor variant scorer
├── prioritization/     # Gene ranker with score explanation
├── enrichment/         # GO BP/MF/CC, KEGG, Reactome via gseapy
├── statistics/         # Summary statistics engine → statistics.json
├── visualization/      # Plotly 2D figures + 3D landscapes + enrichment plots
├── dashboard/          # Multi-page Dash app with live callbacks
├── reports/            # HTML (Jinja2), Excel (openpyxl), PDF (ReportLab)
├── cohort/             # Multi-sample shared/unique/burden analysis
├── family/             # Pedigree-based inheritance detection
├── config/             # Pydantic v2 settings — fully configurable, env-var overridable
└── cli/                # Typer CLI — analyze / dashboard / cohort / family

Installation

From source (recommended)

git clone https://github.com/imrobintomar/VariantFlow.git
cd VariantFlow
pip install -e . --no-build-isolation

Dependencies

pip install pandas numpy scipy plotly dash dash-bootstrap-components \
            gseapy openpyxl reportlab jinja2 pydantic pydantic-settings \
            typer rich loguru tqdm

Docker

docker build -t variantflow:1.0.0 .
docker run --rm -v $(pwd)/data:/data -v $(pwd)/results:/results \
  variantflow:1.0.0 analyze /data/sample.hg38_multianno.txt --output /results

Quick Start

# Single-sample analysis
python variantflow_run.py analyze sample.hg38_multianno.txt \
  --output results/ --sample-id SAMPLE01

# Launch interactive dashboard
python variantflow_run.py dashboard results/ --port 8050

# Cohort analysis (directory of multianno files)
python variantflow_run.py cohort cohort_dir/ --output cohort_results/

# Family / trio analysis
python variantflow_run.py family family_dir/ \
  --proband PROBAND01 --father DAD01 --mother MOM01

CLI Reference

analyze

python variantflow_run.py analyze <input_file> [OPTIONS]

Arguments:
  input_file          ANNOVAR multianno file (.txt or .txt.gz)

Options:
  -o, --output        Output directory           [default: variantflow_results]
  -s, --sample-id     Sample identifier          [default: sample]
  -g, --genome        Genome build: hg38 / hg19  [default: hg38]
  --af                AF threshold (rare variant) [default: 0.01]
  --min-dp            Minimum read depth          [default: 10]
  --nonframeshift     Include nonframeshift indels
  --no-enrichment     Skip pathway enrichment
  --no-pdf            Skip PDF report
  -c, --config        JSON configuration file
  -v, --verbose       Verbose logging

dashboard

python variantflow_run.py dashboard <results_dir> [OPTIONS]

Options:
  --host    Dashboard host  [default: 127.0.0.1]
  --port    Dashboard port  [default: 8050]
  --debug   Enable debug mode

cohort

python variantflow_run.py cohort <cohort_dir> [OPTIONS]

Options:
  -o, --output   Output directory  [default: cohort_results]
  --pattern      File glob pattern [default: *.txt]

family

python variantflow_run.py family <family_dir> [OPTIONS]

Options:
  -p, --proband  Proband sample ID  [required]
  -f, --father   Father sample ID
  -m, --mother   Mother sample ID
  -o, --output   Output directory  [default: family_results]

Input Formats

VariantFlow accepts standard ANNOVAR multianno files:

Automatically detected fields include:

• Genomic coordinates: Chr, Start, End, Ref, Alt
• Gene annotations: Gene.refGene, Func.refGene, ExonicFunc.refGene, AAChange.refGene
• Population frequencies: gnomad411_exome_AF, gnomAD_exome_ALL, ExAC_ALL, 1000g2015aug_all
• ClinVar: CLNSIG, clinvar_20260503 (date-stamped), CLNDN
• InterVar: InterVar_automated, InterVar_ACMG
• Predictors: REVEL_score, CADD_phred, SIFT_score, SIFT4G_score, Polyphen2_HDIV_score
• Other: GERP++_RS, phyloP100way_vertebrate, MutationTaster_pred, SpliceAI_DS_max

Output Structure

results/
├── report.html                  # Self-contained interactive HTML report
├── VariantFlow_Report.xlsx       # Multi-sheet Excel workbook
│   ├── Summary                  # Key statistics and metadata
│   ├── CandidateVariants        # Top 500 variants ranked by score
│   ├── CandidateGenes           # Ranked candidate genes
│   ├── ClinVar_Pathogenic        # Pathogenic / Likely Pathogenic variants
│   ├── InterVar_Pathogenic       # ACMG Pathogenic / LP variants
│   └── go_* / kegg / reactome   # Enrichment results per database
├── report.pdf                   # PDF report with tables and methods
├── CandidateVariants.tsv        # Tab-separated candidate variants
├── CandidateGenes.tsv           # Tab-separated ranked genes
├── statistics.json              # Full summary statistics
├── project.json                 # Reproducibility manifest
├── methods.txt                  # Auto-generated methods section
└── figures/
    ├── filtering_funnel.html
    ├── clinvar_distribution.html
    ├── intervar_distribution.html
    ├── gene_ranking.html
    ├── chromosome_distribution.html
    ├── variant_score_histogram.html
    ├── af_distribution.html
    ├── acmg_evidence.html
    ├── variant_landscape_3d.html
    ├── enrichment_go_biological_process_dot.html
    ├── enrichment_go_biological_process_bar.html
    ├── enrichment_go_cellular_component_dot.html
    ├── enrichment_kegg_dot.html
    ├── enrichment_reactome_dot.html
    └── pathway_landscape_3d.html

Configuration

VariantFlow uses a Pydantic v2 settings system. All parameters can be overridden via:

1. JSON config file (--config my_config.json)
2. Environment variables (prefix VF_)

Example config.json

{
  "project_name": "Rare Disease Study",
  "sample_id": "PATIENT_001",
  "genome_build": "hg38",
  "output_dir": "results/",
  "filters": {
    "active_af_threshold": 0.001,
    "min_dp": 20,
    "include_nonframeshift": true
  },
  "scoring": {
    "clinvar_pathogenic": 10.0,
    "revel_high": 3.0,
    "cadd_very_high": 3.0
  },
  "enrichment": {
    "organism": "human",
    "qvalue_cutoff": 0.05,
    "top_n_terms": 20
  }
}

Environment variable override

export VF_FILTERS__ACTIVE_AF_THRESHOLD=0.001
export VF_FILTERS__MIN_DP=20
export VF_LOG_LEVEL=DEBUG
python variantflow_run.py analyze sample.txt

Variant Scoring

VariantFlow uses a transparent, configurable multi-factor scoring system. Every score contribution is stored in a score_breakdown column for full auditability.

All weights are configurable in config.json under the scoring key.

Note: Variants classified as Benign or Likely Benign by InterVar are automatically removed from the candidate set after annotation.

Pathway Enrichment

Enrichment analysis is performed using gseapy against:

Each database produces:

• Bubble plot — x = -log₁₀(adj. p-value), size = gene count, color = odds ratio
• Bar chart — ranked terms colored by gene count
• Full results table with export

Significance threshold: adjusted p-value ≤ 0.2 (Benjamini-Hochberg). Requires ≥ 5 candidate genes.

Dashboard

The interactive Dash dashboard (http://127.0.0.1:8050) provides eight analysis pages:

All tables support column filtering, sorting, and Excel export.

Cohort and Family Analysis

Cohort

python variantflow_run.py cohort cohort_dir/ --output cohort_results/

Outputs:

• cohort_shared_variants.tsv — variants present in ≥ 2 samples
• cohort_unique_variants.tsv — sample-private variants
• cohort_gene_burden.tsv — per-gene variant counts per sample
• cohort_recurrent_genes.tsv — genes affected in ≥ 2 samples

Family (Trio/Quad)

python variantflow_run.py family family_dir/ \
  --proband PROBAND --father FATHER --mother MOTHER

Detects and outputs:

• family_de_novo.tsv
• family_autosomal_recessive.tsv
• family_compound_heterozygous.tsv
• family_x_linked.tsv

Reproducibility

Every analysis generates a project.json manifest containing:

{
  "run_id": "16e51f54",
  "variantflow_version": "1.0.0",
  "created_at": "2026-06-03T10:36:51",
  "python_version": "3.13.11",
  "genome_build": "hg38",
  "input_files": ["sample.hg38_multianno.txt"],
  "filters_applied": ["quality", "population_frequency", "functional_consequence",
                       "exonic_consequence", "acmg_benign_removal"],
  "total_input_variants": 86299,
  "total_output_variants": 917,
  "total_candidate_genes": 100,
  "config": { "..." }
}

A methods.txt file is also generated, ready to paste into a manuscript Methods section.

Citation

If you use VariantFlow in your research, please cite:

Tomar R. (2024). VariantFlow: A production-quality platform for genomic variant interpretation and prioritization. Dr Prabudh Goel Lab, AIIMS New Delhi. GitHub. https://github.com/imrobintomar/VariantFlow

Contributing

Contributions are welcome. Please open an issue before submitting a pull request. All contributors must follow the existing code style (black, ruff) and include unit tests.

# Run tests
pytest tests/unit/ -v --cov=variantflow

# Lint
ruff check variantflow/
black variantflow/

License

MIT License © 2024 Robin Tomar — Dr Prabudh Goel Lab, AIIMS New Delhi

See LICENSE for full terms.