vflank

Variant-aware flanking-sequence extraction and masking for ddPCR assay design.

vflank is the front-end of a ddPCR assay-design pipeline. It takes genomic variants — small variants (SNPs/indels) and structural variants (fusions) — and emits the sequence an assay is designed around: the masked flanks of each variant or the chimeric junction of a fusion. Primer/probe design itself is delegated downstream to established tools.

📖 Documentation: https://rhshah.github.io/vFlank/

Features

• Small variants (vflank small) — ±N bp flanks from a MAF, raw + masked FASTA, deduplicated per unique variant (CHR_POS_REF_ALT).
• Fusions / SVs (vflank fusion) — reverse-complement-aware junction sequences from an iCallSV / iAnnotateSV breakpoint table (columns by name).
• SNP masking, two backends — local gnomAD VCFs or the gnomAD GraphQL API (no download), each with --pop-data {genome,exome,both}.
• Reference, two backends — a local indexed FASTA or the UCSC API (--ref-source api, no download) for runs with no reference on disk.
• Patient consensus from a BAM (--bam/--bam-map) — build the flank/junction from the patient's own reads (hom-ALT corrected, het/low-cov handled) so primers match the real template; for both small variants and fusions.
• No silent failures — genome-build guard, flank-truncation detection, and a categorised skip summary + optional TSV report.

Planned: VCF input (small + BND SV) and downstream emit formats. See docs/ARCHITECTURE.md.

Install

pip install vflank                                   # from PyPI (released versions)
pip install git+https://github.com/rhshah/vFlank.git # latest from GitHub
# development:
git clone https://github.com/rhshah/vFlank.git && cd vFlank
pip install -e ".[dev]"

Requires Python ≥ 3.10 (Linux/macOS) and pysam, pandas, typer, rich.

Docker

Images are published to GHCR on each release:

docker run --rm -v "$PWD:/data" ghcr.io/rhshah/vflank \
    small run /data/variants.maf -r /data/GRCh37.fasta -g hg19 -o /data/out.fasta

Quick start

vflank small run variants.maf \
    --ref-genome /path/to/GRCh37.fasta \
    --pop-vcf-dir /path/to/gnomad_v2.1.1/ \
    --genome-build hg19 \
    --flank 200 \
    --output flanking_sequences.fasta

--genome-build defaults to hg19 (GRCh37 / gnomAD v2.1.1); pass -g hg38 for GRCh38 / gnomAD v4. gnomAD v4 has no GRCh37 build.

Masking sources

Common-SNP masking can come from local gnomAD VCFs or the gnomAD API:

• --pop-source vcf (default) — local per-chromosome gnomAD VCFs in --pop-vcf-dir. Reproducible, offline, unlimited scale.
• --pop-source api — the public gnomAD GraphQL API, no download. Best for small cohorts (rate-limited to ~10 requests/min).

# No-download masking via the API (small cohorts):
vflank small run variants.maf -r GRCh37.fasta -g hg19 --pop-source api

Either source honours --pop-data {genome,exome,both} (default genome). both masks a position if it is a common SNP in either the genome or exome cohort. Flanks often fall in non-coding regions where only genomes have data, so genome is the default.

Reference sources

The reference can likewise come from a local file or an API:

• --ref-source file (default) — a local indexed FASTA via --ref-genome. Reproducible, offline, unlimited scale; build sanity-checked by chr1 length.
• --ref-source api — the UCSC API, no download (--ref-genome not needed). Best for one-off / hosted runs; throttled to ~1 request/second, so not for bulk.

# Fully no-download (reference + masking from APIs):
vflank small run variants.maf -g hg19 --ref-source api --pop-source api

Each variant yields two FASTA records (the __{CHROM}_{POS}_{REF}_{ALT} suffix is what keys deduplication; the {SAMPLE}__ prefix appears only with --bam):

>[{SAMPLE}__]{GENE}__{HGVSp}__{HGVSc}__{CHROM}_{POS}_{REF}_{ALT}
{left_flank}[REF/ALT]{right_flank}
>Masked__[{SAMPLE}__]{GENE}__{HGVSp}__{HGVSc}__{CHROM}_{POS}_{REF}_{ALT}
{left_flank_masked}[REF/ALT]{right_flank_masked}

Chromosome notation (chr1 vs 1) is auto-detected from the FASTA and VCFs. With a local FASTA the genome build is sanity-checked against its chr1 length; with --ref-source api the requested --genome-build is trusted (a wrong build surfaces as a UCSC error, not silent wrong sequence).

Project layout

src/vflank/
├── core/   chrom · variant · flanks · popfreq   (pure, testable domain logic)
├── io/     maf · reference · fasta              (file access)
└── cli/    app · small                          (Typer commands)

Documentation

• docs/DEVELOPER.md — setup, running, testing, using vflank as a library, and extending it (new flank sources, CLI commands).
• docs/ARCHITECTURE.md — design, scope boundary, and the milestone roadmap.
• CLAUDE.md — repository conventions and the quality gate.