Skip to content

Releases

0.1.2 - 2026-11-18

Choose a tag to compare

@github-actions github-actions released this 18 Nov 09:24
5f2d8fb

0.1.2: train on tables of different contigs, --dp-median, faster training

This release adds options for held-out-chromosome training and evaluation and for scoring partial-genome VCFs, and speeds up training. On the smoke test (strlen, extract and score in genotyper and veto modes), every output is byte-identical to 0.1.1's except the feature table, whose values are identical and whose metadata now records the depth dp_norm divided by. 0.1.1 models load and score as before. Models trained with 9 or more threads can differ in their last bits from 0.1.1's (see Training below).

What can stop a pipeline

Nothing that worked in 0.1.1 is an error in 0.1.2. Some inputs that 0.1.1 rejected are now accepted:

  • train takes tables extracted from different contigs.
  • score takes models trained on the same contigs listed in different orders.

Training

  • train takes tables extracted from different contigs, e.g. one sample's odd chromosomes (extract --contigs) with other samples' whole genomes. The model records every contig any table covers, and score scores the calls on all of them. Tables that record different lengths of a shared contig are still rejected, and a table that shares no contig with the others gets a warning, since train cannot check its reference. Tables of the same contigs give the same model as before.
  • evaluate --contigs (with --happy) reports F1 on only some of a table's contigs, e.g. the chromosomes held out from training.
  • Two more local XGBoost patches make training faster. On an Apple M5, a training round took 29% less time at 15 threads and 41% less at 30. With 9 or more threads, a multi-class model's class trees are built at the same time, each with a share of the threads, so the model can differ in its last bits from the one 0.1.1 trains with the same thread count. A thread count still always trains the same model.

Scoring partial-genome VCFs

dp_norm divides each call's depth by the median depth of the VCF's calls. For a VCF of only part of the genome (e.g. a target footprint), that median is on another scale from the whole-genome tables the models were trained on. extract and score now take --dp-median to set it: pass the median that a whole-genome extract or score of the same sample logs.

Packaging

  • On macOS, winnowr-xgboost builds against a shared libomp.dylib (as conda-forge's llvm-openmp provides) when there is no libomp.a, with a warning. The release binaries still link libomp statically.
  • The published winnowr-xgboost crate includes its integration tests.

Should I upgrade?

Yes, if you train on held-out chromosomes, score VCFs of only part of the genome, or train with many threads. Scores with a given model are unchanged. To reproduce a model exactly, train it with the same winnowr version and thread count.


Release Notes

Bug Fixes

  • Link the shared libomp when WINNOWR_LIBOMP_PREFIX has no libomp.a (#18)

Documentation

  • Call notinalldifficultregions the not-difficult regions (#16)

Features

  • Add --dp-median to fix the depth normalization of extract and score (#20)
  • Let train mix tables extracted from different contigs (#22)
  • Add --contigs to evaluate (#21)

Performance

  • Build the classes' trees at once and the smaller child's histogram (#23)

Install winnowr 0.1.2

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/fg-labs/winnowr/releases/download/v0.1.2/winnowr-installer.sh | sh

Download winnowr 0.1.2

File Platform Checksum
winnowr-aarch64-apple-darwin.tar.xz Apple Silicon macOS checksum
winnowr-aarch64-unknown-linux-gnu.tar.xz ARM64 Linux checksum
winnowr-x86_64-unknown-linux-gnu.tar.xz x64 Linux checksum

0.1.1 - 2026-11-16

Choose a tag to compare

@github-actions github-actions released this 16 Nov 21:29
v0.1.1
1e9db10

0.1.1: on crates.io, sturdier hap.py label joining, strict VCF header checks

The first release on crates.io (cargo install --locked winnowr). It is mostly correctness fixes. On the smoke test (strlen, extract and score in genotyper and veto modes), every output is byte-identical to 0.1.0's. hap.py labels are unchanged on six GIAB combined-validation tables (HG001, HG002 v4.2.1 and v5.0q, HG005, HG006 and HG007). 0.1.0 models load and score as before.

What can stop a pipeline

These used to be accepted silently, crash, or give an empty result. They are now errors:

  • A FILTER the VCF header does not declare, or a record htslib flags (e.g. on an undeclared contig), in extract and score. In score, so is an INFO or FORMAT tag the header does not declare, or declares only as another kind.
  • A --regions span that starts past its contig's end.
  • A flank over 10000 bp, or a train option out of range (--learning-rate, --min-child-weight, --reg-lambda, --max-leaves, --max-depth).
  • A score --output that is a hard link to the input VCF.

The hidden strlen --also option is removed.

hap.py labels

extract --happy used to decide from a single label whether hap.py had been run with --pass-only. One stray label could strip padded and multi-allelic PASS calls of their labels across the genome. The new --happy-pass-only auto|yes|no lets you say how hap.py was run. Pass yes if you run hap.py with --pass-only, as recommended. auto, the default, now needs at least half of the non-PASS calls hap.py could have scored to show it, and logs the evidence.

Should I upgrade?

Yes. Scores and models are unchanged on well-formed input. Check that your VCFs declare every FILTER, INFO and FORMAT tag they use. Pass --happy-pass-only yes when you extract training tables from hap.py run with --pass-only.


Release Notes

The first release published to crates.io (winnowr and winnowr-xgboost).

Features

  • extract --happy-pass-only <auto|yes|no> (with --happy) says whether hap.py was run with
    --pass-only. With auto, the default, it is inferred as run without --pass-only only when
    at least half of the non-PASS calls hap.py could have scored have a record no PASS call
    explains, rather than from a single label. The mode and its evidence are logged, with a warning
    when the labels contradict it.
  • A workflow attaches the full source tarball, with the XGBoost sources, and its SHA-256 to each
    GitHub release.
  • A user guide, at https://winnowr.readthedocs.io.

Bug Fixes

  • A FILTER the VCF header does not declare, or a record htslib flags (e.g. on an undeclared
    contig), is an error naming the record in extract and score, rather than a crash. In
    score, so is an undeclared INFO or FORMAT tag, or one declared only as another kind, rather
    than an exit from htslib or a field written under the wrong name.
  • score keeps records at POS 0, which its sharded writer left out. extract warns that it does
    not read them.
  • score rejects an --output that is a hard link to the input VCF.
  • score re-genotypes only diploid calls. A corrupt tract length or length change gives a call
    no re-genotype target rather than an unbounded allocation, and a read past the end of the
    reference FASTA is an error.
  • A --regions span that starts past its contig's end is an error rather than an empty table,
    and strlen and pileup reject flanks over 10000 bp.
  • In genotyper mode with --expected-f1, a call's own drop threshold (e.g.
    --outside-indel-t-drop) applies before a flip or re-genotype.
  • train rejects non-finite or out-of-range --learning-rate, --min-child-weight,
    --reg-lambda, --max-leaves and --max-depth before reading the tables, and warns and skips
    the refit when the validation fraction holds out no block.
  • Lowercase inserted bases are matched to the upper-case reference context.
  • hap.py labels split from PASS multi-allelic calls, and those at padded SNPs and indels, are
    attached to the right call.
  • On Linux, XGBoost's OpenMP wait policy measures other work only on the CPUs winnowr may use (its
    CPU affinity and cgroup quota).
  • XGBoost no longer prints an "Empty dataset" warning when winnowr counts a model's classes.

Performance

  • With LLVM's libomp and a positive blocktime, XGBoost's OpenMP teams keep a fixed size (a second
    local XGBoost patch), which avoids resizing them between parallel regions. Models are unchanged.
  • strlen and pileup share contig sequences across workers, and feature extraction allocates
    less per row.

Refactor

  • The hidden strlen --also option is removed.
  • More enum-like options list their possible values in --help.
  • winnowr-xgboost's public API is trimmed before its first publish.

Install winnowr 0.1.1

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/fg-labs/winnowr/releases/download/v0.1.1/winnowr-installer.sh | sh

Download winnowr 0.1.1

File Platform Checksum
winnowr-aarch64-apple-darwin.tar.xz Apple Silicon macOS checksum
winnowr-aarch64-unknown-linux-gnu.tar.xz ARM64 Linux checksum
winnowr-x86_64-unknown-linux-gnu.tar.xz x64 Linux checksum

0.1.0 - 2026-11-15

Choose a tag to compare

@github-actions github-actions released this 15 Nov 12:59
v0.1.0
008c6c5

0.1.0: first release

The first release of winnowr. It filters and re-genotypes germline small-variant calls with XGBoost models trained on hap.py-labelled feature tables: extract builds the tables, strlen and pileup measure read evidence, train fits the models, and score applies them to a VCF. evaluate and stratify report their accuracy, and subset restricts a table to some contigs or regions. The user guide is at https://winnowr.readthedocs.io.

Should I use it?

Use 0.1.1 or later. It gives the same outputs on well-formed input and models trained with 0.1.0 work unchanged, with correctness fixes on top. It is also the first version on crates.io.


Release Notes

The first release of winnowr: machine-learned filtering and genotyping of germline small-variant
calls, with XGBoost models trained on hap.py-labelled feature tables.

Features

  • extract, strlen, pileup, train, score, evaluate, stratify and subset.
  • Models are one <name>.winnowr.json file (model format 3) with the XGBoost booster embedded.
  • Training holds out whole 10 kb genomic blocks for early stopping, then refits the final model on
    every call (--refit-final, on by default).
  • In score, evaluate and stratify, indel genotype models also drop the calls their thresholds
    leave alone when P(keep) is below 0.5 (--keep-fallback indel). Given GIAB's
    notinalldifficultregions stratification (--regions notinalldifficultregions=PATH), they drop
    indel calls outside it when P(drop) is at least 0.6, in place of the model's drop threshold
    (--outside-indel-t-drop).
  • Repeat-length features (winnowr strlen) measure reads with --reads mapq20,flank5 by default;
    --reads legacy measures reads of any MAPQ with two flank bases.
  • Pileup features (winnowr pileup, train --pileup-features) count reference, alternate and
    other reads at MAPQ 0, 1-19 and 20 or more, with the settings mapq20,bq10,flank5. The settings
    are recorded in the pileup table and in each model trained with them, and score refuses
    evidence measured with other settings.
  • XGBoost 3.5.0-dev (upstream 293cad1a8) is vendored and linked statically, with one local
    patch that keeps OpenMP teams a fixed size under libgomp.

Install winnowr 0.1.0

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/fg-labs/winnowr/releases/download/v0.1.0/winnowr-installer.sh | sh

Download winnowr 0.1.0

File Platform Checksum
winnowr-aarch64-apple-darwin.tar.xz Apple Silicon macOS checksum
winnowr-aarch64-unknown-linux-gnu.tar.xz ARM64 Linux checksum
winnowr-x86_64-unknown-linux-gnu.tar.xz x64 Linux checksum