varlens

Every variant ranked, with the reasons shown.

varlens reads a VCF file, annotates each variant with ClinVar and gnomAD, and sorts it into one of four priority tiers using plain rules you can audit. Every call comes with the evidence behind it.

View on GitHub Read the benchmark

An educational project written in Python with no external dependencies. It is not a clinical tool and must not be used for diagnosis or medical decisions.

Triage one variant

Change the evidence and watch the tier move. This runs the same rules as the Python tool, in your browser.

Start from an example
0.00001

    Evidence

      How it works

      One command takes a patient VCF and produces a sortable HTML report, plus a TSV if you want one.

      1. VCFStreamed line by line
      2. AnnotateClinVar and gnomAD
      3. Apply the rulesFour tiers, with evidence
      4. ReportHTML and TSV

      Reads large files

      The VCF is streamed, multi-allelic sites are split per allele, and --region scans one chromosome or a coordinate window of a whole-genome file without cutting it first.

      Annotates without a giant download

      ClinVar comes from its VCF. Frequencies come from a local gnomAD file or gnomAD's public API, with adaptive backoff when it rate-limits and an on-disk cache so reruns skip repeated lookups.

      Explains each call

      Each tier carries the evidence lines that produced it, so a reviewer can disagree with a call for a specific reason instead of trusting a score.

      The rules

      The rules are inspired by the ACMG/AMP evidence types and are deliberately short. Defaults are configurable from the command line.

      EvidenceRule (defaults)Effect
      BA1Allele frequency of 5% or moreLow priority Overrides everything else
      BS1Allele frequency of 1% or moreLow priority or a flagged conflict with a ClinVar pathogenic call
      PM2, supportingAbsent, or 0.01% or lessSupporting evidence line
      Loss of functionStop gain, frameshift, canonical splice, start lossRare and absent from ClinVar: Manual review
      ClinVar pathogenic2 or more review starsHigh priority
      ClinVar pathogenicFewer stars, or conflictingManual review
      ClinVar benign1 or more review starsLow priority
      Anything elseNo decisive evidenceUncertain

      ClinVar is shown as its own evidence line rather than as the classic PP5 and BP6 criteria, because ClinGen's Sequence Variant Interpretation group recommended retiring those.

      Does it work? A blind test against ClinVar

      Ranking ClinVar variants using ClinVar's own verdict would be circular, because the answer key would also be an input. So the benchmark hides it. Each ClinVar variant goes through the rules with no ClinVar record, using only the population frequency and molecular consequence stored in ClinVar's VCF. The pathogenic or benign label is used afterwards, only to score the result.

      That makes the question narrower and fairer: how much of the pathogenic versus benign signal do the frequency and consequence rules recover on their own?

      Results have not been generated yet. Run the benchmark on the full ClinVar VCF and it writes its numbers into this page:

      varlens-benchmark clinvar.vcf.gz --markdown BENCHMARK.md --embed docs/index.html

      Run it

      Python 3.9 or newer. The demo uses synthetic data that ships with the repository.

      git clone https://github.com/Print-Samuel/varlens.git
cd varlens
pip install -e ".[dev]"
varlens data/example_patient.vcf --clinvar data/example_clinvar.vcf --freq data/example_freq.vcf --out report.html

      Scan one region of a real genome, looking up frequencies through gnomAD's API:

      varlens sample.vcf.gz --region 21:20000000-26000000 --clinvar clinvar.vcf.gz --freq-api --out report.html

      See what the output looks like in the example report.

      What it does not do

      • It is not a clinical classifier. It prioritises variants for a human to look at, and it has not been validated for diagnosis.
      • Variants are matched exactly on chromosome, position, reference and alternate allele, so normalise indels first.
      • Through gnomAD's API, frequencies are one request per variant: fine for a region, too slow for a whole genome.
      • Loss of function is flagged, not asserted. There is no gene-disease mechanism data and no in-silico predictors.
      • The benchmark only tests what the rules can know without ClinVar's verdict. It says nothing about variants ClinVar has never seen.