VariantCentrifuge

A command-line tool for filtering, extracting, and prioritizing genetic variants from VCF files. VariantCentrifuge combines gene-centric region extraction, multi-tier filtering (bcftools, SnpSift, pandas), inheritance analysis, and configurable scoring into a single reproducible pipeline.

Features

• Gene-centric variant extraction using gene names or BED regions
• Three-tier filtering: bcftools prefilter, SnpSift expressions, pandas final filter
• Inheritance pattern analysis (de novo, AD, AR, X-linked, compound het)
• Configurable variant scoring models
• Association analysis with Fisher's exact test (legacy --perform-gene-burden is deprecated)
• Modular association testing: SKAT-O, COAST allelic series, logistic/linear burden regression with covariates and PCA, ACAT-O omnibus combination — see the Association Testing Guide
• Interactive HTML reports with column-level filtering, semantic color badges, summary dashboard, accessible design (WCAG 2.1 AA), and PDF export
• ClinVar, gnomAD, and SpliceAI annotation links
• Cohort aggregation across multiple samples
• Field profiles for switching annotation database versions (e.g., dbNSFP v4/v5)
• Docker image with all bioinformatics dependencies included
• Stage-based pipeline architecture with parallel execution

Installation

Docker (recommended -- all tools included):

docker pull ghcr.io/scholl-lab/variantcentrifuge:latest

The production image contains an immutable runtime environment. pip is used only while building the image and is removed before distribution; package installation belongs in a development environment.

pip:

pip install variantcentrifuge

From source:

git clone https://github.com/scholl-lab/variantcentrifuge.git
cd variantcentrifuge && pip install .

External tools (bcftools, snpEff, SnpSift, bedtools) must be in PATH when not using Docker. Install via conda: mamba create -y -n vc bcftools snpsift snpeff bedtools

Quick Start

# Filter rare coding variants in a gene list
variantcentrifuge \
  --gene-file genes.txt \
  --vcf-file input.vcf.gz \
  --preset rare,coding \
  --html-report \
  --xlsx

# Score and filter with a custom model
variantcentrifuge \
  --gene-file genes.txt \
  --vcf-file input.vcf.gz \
  --preset rare,coding \
  --scoring-config-path scoring/nephro_variant_score \
  --final-filter 'score > 0.8 and IMPACT == "HIGH"' \
  --output-file results.tsv

Snakemake Workflow

A Snakemake 8+ workflow for batch-processing multiple VCFs on HPC clusters (SLURM, PBS) is included under workflow/, with cluster profiles in profiles/ and sample configuration in config/. See scripts/run_snakemake.sh for the auto-detecting launcher.

Documentation

Full documentation: scholl-lab.github.io/variantcentrifuge

• Installation Guide
• Usage Guide
• Configuration
• API Reference

Contributing

Contributions are welcome. Please see the Contributing Guide for details.

• Bug Reports and Feature Requests
• Discussions

How to cite

If you use VariantCentrifuge in your research, cite the software and record the exact release or commit used in your analysis. CITATION.cff provides machine-readable citation metadata for GitHub's Cite this repository menu. Until an archive DOI is available, cite the corresponding GitHub release or commit URL. For example, for the latest published release:

Popp, B. (2026). VariantCentrifuge (version 0.17.12) [Computer software]. https://github.com/scholl-lab/variantcentrifuge/releases/tag/v0.17.12

The current development version is 0.26.0, as recorded in variantcentrifuge/version.py, CITATION.cff, and .zenodo.json. It has no release date yet; the latest published release is v0.17.12 (2026-07-19). For a development checkout, include its full commit hash and URL instead of citing it as a published release.

Zenodo archive pending: metadata is prepared, but no DOI has been minted. See the release and archival guide for the maintainer steps to archive a release and add the resulting DOI badge.

License

This project is licensed under the MIT License.