Open-source genotype analysis. Format-agnostic. Offline-first.

Website · Demo · Quickstart · Changelog

Allelix

Status: Production. Nine parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three GRCh38 enrichment sources (gnomAD + AlphaMissense + CADD) reached from GRCh37 input through a cross-build rsID identity table, licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports and annotated VCF output for pipeline integration (v2.3.0+), methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. Modern-build position detection requires at least three concordant seed SNPs and an 80% winning ratio before it overrides a fallback or header signal; a tentative GRCh36 signal instead fails closed to GRCh36 because no modern position cache is safe for it (ADR-0025, ADR-0037). No regex on prose anywhere in production. The Changelog tracks every release.

Quickstart

Requires Python 3.11 or newer. On Python 3.10 or older, pip install allelix succeeds but the first command fails with ImportError: cannot import name 'UTC' from 'datetime' — that's the symptom; the fix is to install on 3.11+. Check with python --version.

pip install allelix

# Download reference databases (~18 GB default install; ~24 GB if you opt into CADD).
# Use --no-gnomad / --no-alphamissense to skip the large ones.
# CADD is opt-in: download with `allelix db update --cadd`, then pass
# `--cadd` to an analysis or set `sources.cadd = true` persistently.
allelix db update

# Analyze a genotype file
allelix analyze your_genotype_file.txt --output report.html

# VCF / gVCF input — same command, auto-detected
allelix analyze your_wgs.vcf.gz --output report.html

# Multi-sample VCF — pick which sample to analyze
allelix analyze trio.vcf.gz --sample HG002 --output report.html

# VCF quality gate: rows the variant caller filtered (FILTER not PASS) are
# skipped and counted; calls with GQ below 20 or no reads become no-calls.
allelix analyze your_wgs.vcf.gz --keep-filtered --min-gq 10 --output report.html

# Filter to a custom panel (rsIDs + gene names, one per line; '#' comments and blank lines ignored)
allelix analyze your_genotype_file.txt --filter-file my_panel.txt --output report.html

# Annotated VCF output — VCF-in / VCF-out for pipeline integration
# Writes a valid VCF with annotations as INFO fields + full provenance in the header.
# Missing ##contig declarations are synthesized; raw CHROM names are preserved.
# Refuses to overwrite; requires VCF or gVCF input.
allelix analyze your_wgs.vcf.gz --vcf-out annotated.vcf

See Development for source installs and running tests, Managing your data for cache locations and cleanup, and Troubleshooting for common failure states.

Supported Formats

Adding a new format means adding one file to allelix/parsers/ and registering an instance in the PARSERS list in allelix/parsers/__init__.py.

Roadmap

Issues and milestones are tracked at github.com/allelix/allelix/issues. Annotator-level strand-aware carrier matching shipped in v2.1.0's ADR-0035 cluster.

Supported Databases

CADD modes

CADD ranks how deleterious any single-nucleotide variant is using 100+ annotation tracks (coding, non-coding, regulatory). PHRED 10 = top 10% most deleterious, 20 = top 1%, 30 = top 0.1%.

Opt-in: download the cache with allelix db update --cadd. Then pass --cadd to an analysis for a one-run override, or enable it persistently with allelix config set sources.cadd true. Downloading the cache alone does not change persistent configuration. Use --no-cadd to skip enrichment for a single run when it is enabled in config.

Two modes:

• Cache mode (default): pre-built ~5.8 GB SQLite cache (~120M GRCh38 variant keys). Covers nearly every GRCh38 position allelix can annotate from its other databases (gnomAD, AlphaMissense, ClinVar). GRCh37 input is scored only after translation through the rsID identity table; GRCh36 input never is.
• Full mode (options.cadd_full = true): tabix queries against the complete CADD v1.7 file via pysam (GRCh38 only). Adds coverage for novel or private variants that appear only in WGS/WES data and are not in any pre-computed database. Requires pip install allelix[cadd] for the pysam dependency.

If your input is a genotyping chip file, cache mode is normally all you need. GRCh37 chip files are scored through the rsID identity table; GRCh36 files are not scored.

Build coverage asymmetry (GRCh37 vs GRCh38)

ClinVar dispatches per build and ships with both GRCh37 and GRCh38 caches. gnomAD v4.1 exomes, AlphaMissense, and CADD v1.7 are GRCh38 datasets. Every enrichment lookup is made at GRCh38 coordinates by chromosome, position, reference and alternate allele, never by rsID. For GRCh37 input, the cross-build rsID identity table (ADR-0040) translates the allele the user carries at its GRCh37 position into the matching GRCh38 allele, written explicitly on the GRCh38 forward strand where the reference strand was inverted between assemblies. Palindromic sites (A/T, C/G, or all four bases in dbSNP, whose strand cannot be told from sequence) and alleles that are the GRCh38 reference receive no values rather than a guess. Without the identity table installed, GRCh37 analyses receive no gnomAD, AlphaMissense or CADD values; GRCh36 analyses never do.

Position-based rsID recovery for rsID-less VCFs uses ClinVar (on the selected build), the identity table (on GRCh37 and GRCh38), and gnomAD (GRCh38 only). The same recovery step runs for analyze, stats, extract and export plink, so high-value warnings, extracted genotypes and PLINK allele coding all see the recovered rsIDs (ADR-0043). The identity table covers the rsIDs the annotators hold, so an rsID-less GRCh37 VCF now recovers ClinPGx, GWAS Catalog and SNPedia rsIDs as well as ClinVar ones. If you convert between assemblies, re-normalize REF/ALT as part of the conversion and pass --build explicitly when the file does not carry a trustworthy build signal.

Known ClinPGx limitation: reference-genotype rows where ClinVar and CPIC both lack data

ADR-0022 + ADR-0023: a tiny residual of ClinPGx rows may appear in reports even when the user is homozygous reference. ClinPGx publishes one annotation per genotype including the reference homozygote, and for the reference-homozygote row to be suppressed Allelix needs structured data on the variant from either:

• ClinVar's REF allele (the primary filter — see ADR-0023). Covers any rsID ClinVar catalogs.
• CPIC's per-allele function table (the secondary fallback — see ADR-0020). Covers rsIDs CPIC has classified.

For the rare rsID where ClinPGx has an annotation but neither ClinVar nor CPIC has data, the row emits. These are identifiable by a homozygous-reference genotype combined with "decreased risk," "may have a typical response," or similar comparative language. They are an upstream data gap, not an Allelix bug — we surface them honestly rather than hide them behind a curated exclusion list (which would recreate the maintenance trap the v0.5–v0.7 prose filters were trying to escape).

The CFTR × ivacaftor leak (~30+ rows on real data, pre-v0.7.3) is fixed by the ADR-0023 ClinVar REF check: CPIC's CFTR vocabulary ("ivacaftor responsive") doesn't match the four-class enum the secondary tier expects, but ClinVar publishes REF for every CFTR rsID, so the primary tier catches them universally.

Known ClinVar upstream data quality issues

Two ClinVar rows in real-world reports are known upstream artifacts, not Allelix bugs:

• PKD1 rs199476100 GG (Pathogenic/Likely pathogenic, magnitude 8.5). This is a stop-gained variant with a gnomAD frequency of 0.0005% (7 observations in 1.38 million chromosomes). Homozygosity for this variant is biologically implausible — PKD1 is autosomal dominant and the nonsense variant would be embryonic-lethal or devastating in homozygous state. The chip genotyping call is almost certainly a probe artifact. The code correctly reports what ClinVar says and what the chip reads; the error is upstream of Allelix. The row is now marked implausible (see Plausibility flag) but is still shown.

• IL10 rs1800896 CT (Pathogenic, magnitude 9.0). This is a common polymorphism (MAF ~20–40%) in the IL-10 promoter. ClinVar's Pathogenic classification comes from a single submitter for hepatitis C susceptibility; another submission classifies the allele as "Uncertain risk allele" for leprosy susceptibility. Allelix's per-SCV loader keeps each submitter's significance paired with its own condition, so it does not create cross-submission combinations. The remaining concern is the upstream strength of a single-submitter classification on a common variant. Future work: review-status weighting could down-weight that evidence.

Neither issue affects Allelix's filter logic. Both are inherent to ClinVar's aggregation model and the limitations of array-based genotyping chips.

Regulatory Posture

Allelix is an informational research tool. It reports classifications made by external databases. It does not independently classify variants, diagnose conditions, or make health recommendations. All variant significance is attributed to its source — Allelix says "ClinVar classifies this variant as pathogenic," never "this variant is pathogenic."

This is not a disclaimer afterthought. It is a design constraint that affects model naming, report wording, and category labeling throughout the codebase.

Privacy

• No data leaves your machine. No telemetry. No uploads. No analytics.
• Reference databases are downloaded via allelix db update and cached locally.
• Analysis runs offline against local database caches. A brief freshness check runs before analysis by default (skipped with --no-update).

Output files contain real annotations of your genome

The JSON / HTML / terminal output of allelix analyze and its focused subcommands contains real annotations against your specific variants — drug-response calls, carrier-status flags, hereditary- disease findings. Wherever you write them via --output <path>, that's where they sit until you delete them. Allelix doesn't auto-clean and won't warn you when you write to /tmp/ or any other shared location. Treat the files as personal data: read them, move them somewhere you control, or delete when you're done. allelix db clean (shipped in v2.2.0) handles the cache side of the lifecycle; output reports are still the user's responsibility to manage.

Configuration

Allelix stores persistent configuration in config.toml (in the data directory, default ~/.local/share/allelix/). A default config is created on first run.

# View current config (annotated with license notes)
allelix config show

# Read a single key
allelix config get sources.cadd
allelix config get license.commercial

# Disable a source permanently
allelix config set sources.gnomad false

# Enable commercial mode (auto-disables non-commercial sources)
allelix config set license.commercial true

# Assert that you hold a commercial CADD license
allelix config set license.cadd true

# Tune the plausibility flag (allele frequencies between 0 and 1)
allelix config set plausibility.homozygous_max_af 0.0001
allelix config set plausibility.heterozygous_max_af 0

CLI flags (--no-gnomad, --no-alphamissense, --no-cadd, --exclude-snpedia, --cadd) override the config for a single run. The config sets the baseline; flags override per-invocation.

Plausibility flag

Genotyping arrays sometimes miscall very rare variants, most visibly as a homozygous call for an allele almost nobody carries. Allelix compares each call with the allele's gnomAD frequency and marks it for review. The row is never hidden (ADR-0041).

The HTML report shows a ⚠ icon next to a flagged genotype, with the reason on hover and in the detail panel. The terminal table marks implausible calls with ⚠ and suspicious ones with ?. JSON reports carry plausibility on every annotation (plausible, suspicious, implausible, or empty when not assessed).

A call is not assessed when gnomAD has no frequency for the allele. Allelix's gnomAD cache covers exome sites with an rsID, so a missing value says nothing about rarity. Calls are also not assessed when the gnomAD database is skipped. Homozygous calls on X are not assessed because a male's single X reads as homozygous; heterozygous X calls are. Y and mitochondrial calls are not assessed. Confirm a flagged call with a clinical-grade test before relying on it.

Database sizes and download times

Not all databases are equal in size. allelix db update downloads them all by default, but you can skip the large ones if disk space or bandwidth is a concern:

gnomAD and AlphaMissense are the largest but add the most interpretive context. gnomAD answers "is this variant rare or common?" — a pathogenic variant carried by 35% of the population reads very differently from one seen in 3 people. AlphaMissense answers "does this missense change likely damage the protein?" — especially valuable for the thousands of variants ClinVar hasn't reviewed yet.

To skip either during download: allelix db update --no-gnomad --no-alphamissense. To disable permanently: allelix config set sources.gnomad false.

Managing your data

Allelix stores reference database caches at ~/.local/share/allelix/ (Linux/macOS) or the XDG-equivalent on other platforms. Default install (no CADD) is ~18 GB on disk; with the CADD opt-in it's ~24 GB.

~/.local/share/allelix/
├── alphamissense.sqlite       ~7.8 GB
├── gnomad.sqlite              ~7.1 GB
├── cadd.sqlite                ~5.8 GB   (only if you opted into --cadd)
├── clinvar.GRCh37.sqlite      ~800 MB
├── clinvar.GRCh38.sqlite      ~800 MB
├── gwas_catalog_associations.tsv  ~745 MB
├── rsid_identity.sqlite       ~457 MB
├── gwas.sqlite                ~202 MB
├── snpedia.sqlite             ~194 MB
└── pharmgkb.sqlite            ~6 MB

The caches are disposable and re-downloadable. Everything here was fetched by allelix db update and can be re-fetched at any time. There's no per-user state in the cache — your genotype files never enter this directory. Safe to delete to reclaim space (or to force a full refresh if you suspect a cache went stale):

# Reclaim all ~18-24 GB, with size report and confirmation prompt
allelix db clean

# Preserve the CADD cache (avoids re-downloading the slowest one, ~5.8 GB)
allelix db clean --keep-cadd

# Show what would be deleted without acting
allelix db clean --dry-run

# Scripted use — skip the confirmation prompt
allelix db clean --yes

# Re-populate from scratch next time you analyze a file
allelix db update

db clean refuses to act on a directory that doesn't contain any recognized allelix cache files — a typo'd --data-dir ~/Documents won't result in rm -rf against an unrelated tree, even with --yes. Pass --force if you've staged caches under a non-standard name and want to delete them anyway.

For scripting and backup integration, allelix db path prints the resolved data directory:

ALLELIX_DATA=$(allelix db path)
du -sh "$ALLELIX_DATA"

# --check additionally verifies the path is writable; exit non-zero if not
allelix db path --check

The one thing worth backing up: config.toml. It lives inside the resolved data directory (typically ~/.local/share/allelix/config.toml) and stores your license assertions (commercial-mode toggle, CADD opt-in confirmation) and per-source enable/disable settings. It's the only non-reproducible state in the install. The caches will rebuild on the next db update; config.toml won't. allelix db clean always preserves it.

To fully uninstall allelix and reclaim everything:

ALLELIX_DATA=$(allelix db path)
allelix db clean --yes                 # reference database caches
rm -f "$ALLELIX_DATA/config.toml"      # license + source-toggle config
pip uninstall allelix

Data Sources & Licensing

Allelix source code is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). Allelix ships with zero third-party data. All reference databases are downloaded by the user at runtime via allelix db update. Each database retains its original license on the user's machine:

Commercial users: When license.commercial = true, non-commercial sources are gated by a three-state permission model. SNPedia is permanently blocked (no commercial license is available). CADD is blocked by default but can be unlocked — the University of Washington offers commercial licenses at https://els2.comotion.uw.edu/product/cadd-scores; after purchasing, assert your license with allelix config set license.cadd true to re-enable CADD in commercial mode. All other databases (ClinVar, ClinPGx, GWAS Catalog, gnomAD, AlphaMissense) are compatible with commercial use. allelix config show displays the permission state for each source.

SNPedia data download

SNPedia data is downloaded automatically by allelix db update from a pre-built cache. If the SNPedia database is not present, allelix analyze runs normally using all other databases and prints a note that SNPedia data is not available.

To rebuild the cache from source (not normally needed):

python scripts/scrape_snpedia.py   # scrape 216K pages from bots.snpedia.com (1-4 hours)
python scripts/parse_snpedia.py    # parse raw wiki markup into structured genotype rows

Known SNPedia source data quality notes

SNPedia appears frozen — no edits have been observed since mid-2023. The data below reflects the state of the wiki at scrape time (May 2026) and is unlikely to change.

Of the 104,806 genotype pages in the archive:

• 103 pages have empty or missing allele fields. These are incomplete entries on the source wiki — the {{Genotype}} template was created but the allele1/allele2 fields were never filled in (e.g., Rs1131692198(;) with |allele1=\n|allele2=\n). All 103 were verified against the live site on 2026-05-21; every one matches the source exactly. The annotator silently skips these — they cannot match any user genotype.

• 1 page has no {{Genotype}} template at all. Rs1799853(T) is a malformed single-allele page ({{is a|genotype}} instead of a proper genotype template). Skipped by the parser.

• 2 pages have a space before the parenthesis in the title (Rs52820871 (G;G) and Rs52820871 (G;T) instead of the standard Rs52820871(G;G) format). The annotator handles both title styles.

None of these are scraping errors. They are editorial inconsistencies on the source wiki. The annotator handles all of them correctly: incomplete entries are skipped, variant title formats are matched, and no false annotations are produced.

The v2.3.1 cache format also preserves each page's SNPedia orientation. Known minus-strand rows are complemented to forward orientation before genotype matching. For palindromic A/T or C/G genotypes whose orientation is unknown, Allelix abstains because the source data cannot distinguish the strands safely. Re-run allelix db update after upgrading so a pre-v2.3.1 SNPedia cache is rebuilt.

Troubleshooting

ImportError: cannot import name 'UTC' from 'datetime'

You're on Python 3.10 or older. Allelix requires 3.11+. python --version to check; upgrade and reinstall.

allelix db update failed partway through

Run it again. The update is idempotent — completed downloads are skipped (signal-matched against the upstream freshness probe), so re-running picks up where it left off. If a specific optional source keeps failing, use its --no-* flag to finish the other sources, then remove the skip flag and re-run the full update later. --only clinvar exists for the ClinVar-only CI and recovery path; other sources do not currently have standalone --only selectors.

If the failure is a network timeout on the same source repeatedly, the issue is likely on the source's end (HuggingFace / NCBI / EBI / etc. transient outage). Wait an hour and retry.

db status shows an annotator as "not ready" but the cache files exist on disk

Almost always a schema or interpreter version bump in a recent allelix release that invalidates the pre-bump cache. The fix is allelix db update — it'll re-ingest only the affected annotators (everything else signal-skips). See the relevant CHANGELOG.md entry for "Cache invalidation" notes per release.

Build mismatch warning when analyzing a known-good file

Either: (a) the file's header claims one build and the position data confidently indicates another (real-world MHG / Tempus exports do this — header says 37, positions are 38), or (b) the position signal is too small or mixed to be authoritative. Allelix requires at least three concordant seed SNPs and an 80% winning ratio. A VCF record without an rsID counts as a seed when it sits at that seed's position on a build, so variant-caller output with an empty ID column is detected by position too. Weaker GRCh37/38 evidence is reported as tentative and the header or fallback remains effective. A tentative GRCh36 winner is the safety exception: Allelix uses GRCh36 so it cannot accidentally query a modern position cache. Modern position-keyed caches are unavailable for that build (see docs/grch36-liftover.md).

If you trust the file's header more than allelix's detection, force the build: --build grch37 or --build grch38. The build banner in the analyze output will reflect what was actually used.

Is my database stale? How fresh is the data?

allelix db status shows the ingestion date of each cache. The freshness model is signal-driven: allelix db update queries an upstream freshness signal (md5 / etag) per source and re-ingests only when the signal changed. There's no time-based staleness — a 6-month-old cache against an unchanged source IS current.

If you want to force a refresh: allelix db update --force re-downloads every cache regardless of freshness signal.

Output reports contain real genome annotations

Anything allelix analyze writes to disk contains real annotations of your genome. Treat the output files (HTML, JSON, terminal redirects) as sensitive — they're as private as the input genotype file. Allelix does not transmit them; the lifecycle is local.

Where does allelix store its data?

See Managing your data above for cache locations, the disposability rule, what to back up, and the uninstall procedure.

Architecture & Design Decisions

The "why" behind major design choices lives in docs/adr/ as Architecture Decision Records. Read these before proposing changes that touch the parser/annotator interfaces, the regulatory posture, or the data-handling model.

Notable load-bearing ADRs:

• ADR-0016 — Data Classification Principle. Classification reads structured fields only. Regex on prose is forbidden in production code.
• ADR-0020 — CPIC API as the per-allele function source. The ClinPGx non-finding filter is a table join keyed on (rsid, base) → clinicalfunctionalstatus, sourced from CPIC's structured API. Supersedes the prose-extraction tiers from earlier versions (ADR-0017, ADR-0018).
• ADR-0007 — Genotype matching requires the user to carry the ALT allele. Applies to ClinVar.
• ADR-0009 — ClinPGx matches the user's exact normalized diploid call.
• ADR-0015 — Mock data generators are the contract. Fixture shape must mirror real data shape; invariants tested.
• ADR-0036 — Annotated VCF output contract. JSON and annotated VCF schemas evolve independently.
• ADR-0037 — Conservative position-based build confidence. A winning build needs at least three matches and an 80% ratio; weaker signals remain diagnostic only.
• ADR-0038 — GWAS effect-modifier disambiguation. Only positively identified odds ratios receive an effect-size modifier; beta and ambiguous effects abstain.
• ADR-0042 — VCF quality gate. The variant caller's FILTER and genotype quality are honoured, low-quality reference blocks are no-calls, and every exclusion is counted in the report.
• ADR-0043 — One rsID-recovery step. Every command that needs rsIDs recovers them for rsID-less input through the same shared step; build detection votes by position instead.
• ADR-0041 — Plausibility flag. Very rare homozygous calls and heterozygous calls with no gnomAD carriers are flagged for review, never suppressed.

Release history: see CHANGELOG.md.

Development

source .venv/bin/activate
pip install -e ".[dev]"

# One-time: install pre-commit hooks
pre-commit install --hook-type pre-commit

ruff check .
ruff format --check .
pytest

The pre-commit hook enforces ruff check + ruff format --check. If a commit is blocked, fix the underlying problem rather than skipping the hook.

For the full real-data release-validation battery — every parser format, VCF/gVCF, PLINK round-trip, edge cases, the GIAB/1000G corpus — see test_data/FULL_TEST_PROTOCOL.md. That document is the project's real-data testing story; running pytest covers the fast suite that gates every commit.

License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE.