Repository navigation
Releases
0.1.2 - 2026-11-18
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:
traintakes tables extracted from different contigs.scoretakes models trained on the same contigs listed in different orders.
Training
traintakes 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, andscorescores 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, sincetraincannot 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-xgboostbuilds against a sharedlibomp.dylib(as conda-forge'sllvm-openmpprovides) when there is nolibomp.a, with a warning. The release binaries still link libomp statically. - The published
winnowr-xgboostcrate 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 | shDownload 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
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
extractandscore. Inscore, so is an INFO or FORMAT tag the header does not declare, or declares only as another kind. - A
--regionsspan that starts past its contig's end. - A flank over 10000 bp, or a
trainoption out of range (--learning-rate,--min-child-weight,--reg-lambda,--max-leaves,--max-depth). - A
score --outputthat 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. Withauto, the default, it is inferred as run without--pass-onlyonly 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 inextractandscore, 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. scorekeeps records at POS 0, which its sharded writer left out.extractwarns that it does
not read them.scorerejects an--outputthat is a hard link to the input VCF.scorere-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
--regionsspan that starts past its contig's end is an error rather than an empty table,
andstrlenandpileupreject 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. trainrejects non-finite or out-of-range--learning-rate,--min-child-weight,
--reg-lambda,--max-leavesand--max-depthbefore 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. strlenandpileupshare contig sequences across workers, and feature extraction allocates
less per row.
Refactor
- The hidden
strlen --alsooption 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 | shDownload 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
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,stratifyandsubset.- Models are one
<name>.winnowr.jsonfile (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,evaluateandstratify, indel genotype models also drop the calls their thresholds
leave alone when P(keep) is below 0.5 (--keep-fallback indel). Given GIAB's
notinalldifficultregionsstratification (--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,flank5by default;
--reads legacymeasures 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 settingsmapq20,bq10,flank5. The settings
are recorded in the pileup table and in each model trained with them, andscorerefuses
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 | shDownload 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 |