VCFWAVE(1)

📦

version 1.0.12 · 2 versions

1.0.12 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
1.0.9 · ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ VCFWAVE(1) ✨

okay bestie, this is the manual page for vcfwave, from the vcfwave (VCF transformation) family. grab a snack, hydrate, and let's get into it 💅

🎀 NAME 🎀

vcfwave — reduces complex alleles by pairwise alignment with BiWFA

🦋 SYNOPSIS 🦋

vcfwave

like. that's it. no flags required, no arguments required, she just exists ✨

💖 DESCRIPTION 💖

vcfwave reduces complex alleles into simpler primitive representation using pairwise alignment with BiWFA.

ngl, variant callers are often not perfect. that's just the tea ☕ so here's the glow-up: vcfwave, together with its companion tool vcfcreatemulti, can take an existing VCF file that has multiple complex overlapping and even nested alleles and — like Humpty Dumpty — take them all apart and put them back together again into a more sane VCF output. the result? we get rid of false positives and often greatly simplify the output. we made these tools for the output from long-read pangenome genotypers — with 10K base pair realignments — and it's used in the Human Pangenome Reference Consortium analyses (HPRC). iconic, honestly 👑

vcfwave realigns reference and alternate alleles with the recently introduced super fast bi-wavefront aligner (WFA). vcfwave parses out the original 'primitive' alleles into multiple VCF records, and vcfcreatemulti puts them together again. these tools can handle insertions, deletions, inversions and nested sequences. in both tools, information is tracked on original positions and genotypes are handled. new records have IDs that reference the source record ID. deletion alleles will result in haploid (missing allele) genotypes overlapping the deleted region. periodt.

a typical workflow will call vcfwave to realign all ALT alleles against the reference and spit out simplified VCF records. next, use a tool such as bcftools norm -m- to normalise the VCF records and split out multiple ALT alleles into separate VCF records. finally, use vcfcreatemulti to create multi-allele VCF records again. the whole pipeline is giving main character energy 🌈

🚀 PERFORMANCE 🚀

unlike traditional aligners that run in quadratic time, the recently introduced wavefront aligner WFA runs in time O(ns+s^2), proportional to the sequence length n and the alignment score s, using O(s^2) memory (or O(s) using the ultralow/BiWFA mode). so WFA does not choke on longer alignments. she's built different, fr fr 🔥

speed-wise, vcfwave can still be faster. see also the performance docs for some metrics and discussion.

📚 READING 📚

see also the humpty dumpty companion tool vcfcreatemulti. they're a duo, you can't separate them 💞

⚙️ Options ⚙️

-h, --help — shows help message and exits. the classic. the beloved. the "hello bestie what do you do" flag 🫶

see more below. like, a lot more. keep scrolling.

🚦 EXIT VALUES 🚦

0 — Success. she ate and left no crumbs ✨
not 0 — Failure. it's giving tragedy 😭

🧪 EXAMPLES 🧪

current command line options:

>>> head("vcfwave -h",26)
>
usage: vcfwave [options] [file]
>
Realign reference and alternate alleles with WFA, parsing out the
'primitive' alleles into multiple VCF records. New records have IDs that
reference the source record ID.  Genotypes/samples are handled
correctly. Deletions generate haploid/missing genotypes at overlapping
sites.
>
options:
    -p, --wf-params PARAMS  use the given BiWFA params (default: 0,19,39,3,81,1)
                            format=match,mismatch,gap1-open,gap1-ext,gap2-open,gap2-ext
    -f, --tag-parsed FLAG   Annotate decomposed records with the source record position
                            (default: ORIGIN).
    -L, --max-length LEN    Do not manipulate records in which either the ALT or
                            REF is longer than LEN (default: unlimited).
    -K, --inv-kmer K        Length of k-mer to use for inversion detection sketching (default: 17).
    -I, --inv-min LEN       Minimum allele length to consider for inverted alignment (default: 64).
    -t, --threads N         Use this many threads for variant decomposition (default is 1).
                            For most datasets threading may actually slow vcfwave down.
    --quiet                 Do not display progress bar.
    -d, --debug             Debug mode.
>
Note the -k,--keep-info switch is no longer in use and ignored.
>
Type: transformation

heads up bestie: the -k,--keep-info switch is no longer in use and is ignored. don't come for me, I'm just the messenger 💀

vcfwave picks complex regions and simplifies nested alignments. for example:

>>> sh("grep 10158243 ../samples/10158243.vcf")
grch38#chr4     10158243        >3655>3662      ACCCCCACCCCCACC ACC,AC,ACCCCCACCCCCAC,ACCCCCACC,ACA     60      .       AC=64,3,2,3,1;AF=0.719101,0.0337079,0.0224719,0.0337079,0.011236;AN=89;AT=>3655>3656>3657>3658>3659>3660>3662,>3655>3656>3660>3662,>3655>3660>3662,>3655>3656>3657>3658>3660>3662,>3655>3656>3657>3660>3662,>3655>3656>3661>3662;NS=45;LV=0     GT      0|0     1|1     1|1     1|0     5|1     0|4     0|1     0|1     1|1     1|1     1|1     1|1     1|1     1|1     1|1     4|3     1|1     1|1     1|1     1|0     1|0     1|0     1|0     1|1     1|1     1|4     1|1     1|1     3|0     1|0     1|1     0|1     1|1     1|1     2|1     1|2     1|1     1|1     0|1     1|1     1|1     1|0     1|2     1|1     0

this aligns and adjusts the genotypes accordingly, splitting into multiple records — one for each unique allele found in the alignments. so satisfying to watch 🦋

>>> sh("../build/vcfwave -L 1000 ../samples/10158243.vcf|grep -v ^\#")
grch38#chr4     10158244        >3655>3662_1    CCCCCACCCCCAC   C       60      .       AC=1;AF=0.011236;AN=89;AT=>3655>3656>3657>3660>3662;NS=45;LV=0;ORIGIN=grch38#chr4:10158243;LEN=12;TYPE=del        GT      0|0     0|0     0|0     0|0     1|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0
grch38#chr4     10158244        >3655>3662_2    CCCCCACCCCCACC  C       60      .       AC=3;AF=0.033708;AN=89;AT=>3655>3656>3660>3662;NS=45;LV=0;ORIGIN=grch38#chr4:10158243;LEN=13;TYPE=del     GT      0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     1|0     0|1     0|0     0|0     0|0     0|0     0|0     0|0     0|1     0|0     0
grch38#chr4     10158245        >3655>3662_3    CCCCACCCCCACC   C       60      .       AC=64;AF=0.719101;AN=89;AT=>3655>3656>3657>3658>3659>3660>3662;NS=45;LV=0;ORIGIN=grch38#chr4:10158243;LEN=12;TYPE=del     GT      0|0     1|1     1|1     1|0     0|1     0|0     0|1     0|1     1|1     1|1     1|1     1|1     1|1     1|1     1|1     0|0     1|1     1|1     1|1     1|0     1|0     1|0     1|0     1|1     1|1     1|0     1|1     1|1     0|0     1|0     1|1     0|1     1|1     1|1     0|1     1|0     1|1     1|1     0|1     1|1     1|1     1|0     1|0     1|1     0
grch38#chr4     10158251        >3655>3662_4    CCCCACC C       60      .       AC=3;AF=0.033708;AN=89;AT=>3655>3656>3657>3658>3660>3662;NS=45;LV=0;ORIGIN=grch38#chr4:10158243;LEN=6;TYPE=del    GT      0|0     0|0     0|0     0|0     0|0     0|1     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     1|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|1     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0
grch38#chr4     10158256        >3655>3662_5    CC      C       60      .       AC=2;AF=0.022472;AN=89;AT=>3655>3660>3662;NS=45;LV=0;ORIGIN=grch38#chr4:10158243;LEN=1;TYPE=del   GT      0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|1     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     1|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0|0     0
grch38#chr4     10158257        >3655>3662_6    C       A       60      .       AC=1;AF=0.011236;AN=89;AT=>3655>3656>3657>3660>3662;NS=45;LV=0;ORIGIN=grch38#chr4:10158243;LEN=1;TYPE=snp GT      0|0     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     .|.     0

and here's more run commands, for the regression girlies 🧚

./vcfwave -L 10000 ../samples/grch38#chr8_36353854-36453166.vcf > ../test/data/regression/vcfwave_4.vcf
                     run_stdout("vcfwave -L 10000 ../samples/grch38#chr8_36353854-36453166.vcf", ext="vcf")
                     output in vcfwave_4.vcf

./vcfwave -L 10000 ../samples/grch38#chr4_10083863-10181258.vcf > ../test/data/regression/vcfwave_5.vcf
                     run_stdout("vcfwave -L 10000 ../samples/grch38#chr4_10083863-10181258.vcf", ext="vcf")
                     output in vcfwave_5.vcf

🔄 Inversions 🔄

(the original labels this bit ## Inversions — cute, we kept the vibe)

we can also handle inversions. this test case includes one that was introduced by building a variation graph with an inversion and then decomposing it into a VCF with vg deconstruct and finally "popping" the inversion variant with vcfbub (https://github.com/pangenome/vcfbub). okay queen of pipelines 💅

From

a 281 >1>9 AGCCGGGGCAGAAAGTTCTTCCTTGAATGTGGTCATCTGCATTTCAGCTCAGGAATCCTGCAAAAGACAG CTGTCTTTTGCAGGATTCCTGTGCTGAAATGCAGATGACCGCATTCAAGGAAGAACTATCTGCCCCGGCT 60 . AC=1;AF=1;AN=1;AT=>1>2>3>4>5>6>7>8>9,>1<8>10<6>11<4>12<2>9;NS=1;LV=0 GT 1

>>> sh("../build/vcfwave ../samples/inversion.vcf|grep INV")
##INFO=<ID=INV,Number=0,Type=Flag,Description="Inversion detected">
a       281     >1>9    AGCCGGGGCAGAAAGTTCTTCCTTGAATGTGGTCATCTGCATTTCAGCTCAGGAATCCTGCAAAAGACAG  CTGTCTTTTGCAGGATTCCTGTGCTGAAATGCAGATGACCGCATTCAAGGAAGAACTATCTGCCCCGGCT  60      .       AC=1;AF=1.000000;AN=1;AT=>1>2>3>4>5>6>7>8>9;NS=1;LV=0;LEN=70;INV=YES;TYPE=mnp  GT      1

note the INV=YES info. it's right there. she said yes 💖

📜 LICENSE 📜

👑 AUTHORS 👑

Erik Garrison, Pjotr Prins and other vcflib contributors.

okay that's the whole page bestie, you made it to the end 🎀 this one came out of the vcflib crew — vcfwave (vcflib), no cap. now go realign something and slay ✨🦋💅

📦 where this page comes from

debian trixie: libvcflib-tools 1.0.12+dfsg-1 · MIT
ubuntu questing: libvcflib-tools 1.0.12+dfsg-1
ubuntu resolute: libvcflib-tools 1.0.12+dfsg-2 · MIT
ubuntu stonking: libvcflib-tools 1.0.12+dfsg-2 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms