Allelix is an open-source Python CLI that annotates variants from consumer genotyping files and VCF/gVCF against seven public databases in a single local pass. Everything runs on-machine — no uploads, no API calls, no cloud.

Install and run

pip install allelix
allelix db update
allelix analyze input.vcf.gz -o report.html

Supported inputs

Consumer genotyping: 23andMe, AncestryDNA, FTDNA, LivingDNA, MyHeritage (auto-detected)
Sequencing: VCF, gVCF (single-sample and multi-sample with --sample)
Builds: GRCh37 and GRCh38 (auto-detected from data, not headers)

Databases

Each annotator queries a local SQLite cache, updated on-demand via allelix db update:

ClinVar — clinical significance + review status
gnomAD — population allele frequencies (807K individuals)
PharmGKB — drug-gene interactions, CPIC evidence levels
GWAS Catalog — genome-wide association findings
SNPedia — community annotations with magnitude scoring
AlphaMissense — missense pathogenicity predictions
CADD — variant deleteriousness scoring (pre-filtered cache against gnomAD/ClinVar/AlphaMissense positions, not the full 81 GB dataset)

Performance

1 GB whole-genome gVCF (~5.2M variants): ~90 seconds (MacBook M3)

Tested against GIAB HG002 benchmarks (GRCh37 + GRCh38) and 1000 Genomes multi-sample VCFs

Build detection

Allelix doesn't trust file headers for reference assembly. We use 11 sentinel SNPs across 7 chromosomes where positions differ between GRCh37 and GRCh38, tally votes from the actual data, and call the build empirically. Header/data mismatches are flagged in the report. We've encountered real-world files from consumer vendors where the header claims one build and the positions correspond to another.

Output formats:

HTML report (interactive, offline, self-contained)
JSON report (schema-versioned)
Terminal (Rich-formatted)
Annotated VCF (--vcf-out)
PLINK1 binary export (.bed/.bim/.fam)
Report diff (compare against previous JSON)

Modes:

Pharmacogenomics focused command
Methylation pathway focused command
Filter file for custom panels

Links

GitHub: https://github.com/allelix/allelix
PyPI: https://pypi.org/project/allelix/
Website: https://allelix.io
License: AGPL-3.0

Feedback, issues, and contributions welcome. Happy to answer questions about the annotation pipeline or database integration.