Skip to content

v4.3.0 — reach the features the rotation is fitted on

Choose a tag to compare

@mikessh mikessh released this 28 Sep 10:16
· 209 commits to master since this release

Three things a caller needed and could not reach. None of them is a new statistic — everything
below already existed inside the library; what changed is the route to it.

named= — the statistics the rotation is fitted on

The rotation is fitted on features with domain names (diversity, depth, clone-size fractions,
junction length, isotype composition, SHM, cross-locus yield) and emits coordinates that have none.
Those features were computed for every sample and discarded.

vdjtools signature --corpus blood --components 32 --named all -o sig.tsv
vsig(sample, corpus, n_components=32, named=True)      # or named=("div", "depth")

named=() is the default and reproduces the pre-4.3 output byte for byte. Which blocks are
reportable is declared on RawGroup(named=True), never inferred from width — pchem is 30
columns and is not reportable, shm is one and is. Values carry their declared transform, not a
natural scale: vsig:div:TRB:1D_c = 2.386 is a log10, not a clone count.

This is not merely convenient. The diversity floor of any study using this library is made of
exactly these blocks; without a documented route to them there is no floor, and a signature that
beats nothing gets reported as if it beat something.

channel_table() and a kind column

Every (block, feature) with its transform, support, emitted loci, and a kind — rotated,
named, or channel. --describe prints the same three kinds and gained a transform column.

fit_cohort — fit a corpus on your own repertoires

corpus.fit took feature rows; fit_cohort takes frames, runs the existing process pool, and
returns the same Corpus type the published artifacts are. sig="rsig" resolves through a
featuriser registry rather than an import, because nothing in vdjtools may import mir.

With the caveat that is the point of the function. Measured on 5,376 raw columns over seven
loci with one logistic head, at matched widths: a rotation fitted on 612 training repertoires beat
the shipped blood artifact on the training out-of-fold number at 4 of 5 widths (median 0.5039
against 0.4968) and on an external cohort at 0 of 5 (median 0.4757 against 0.5270). Fitting
in-cohort improves the number the configuration is selected on and neither held-out read-out.

mask is a feature block, not QC

vsig:mask:<L>:present / :estimable were documented beside v_fallback_frac under quality
control, so the natural reading was "diagnostics, drop before modelling". Measured on 874 labelled
samples with a second cohort held out entirely, adding the five presence flags moved the external
ROC-AUC from 0.6243 to 0.6676
for 17 extra columns. 720 of 7,399 (sample, locus) pairs sit below a
five-clonotype floor, almost all TRD and TRG, and which donors those are tracks lymphocyte content.

No corpus is invalidated

A channel is pass-through: the rotation is indexed by raw_columns and nothing else, and
corpus.apply fills every registered channel from the sample. Verified against the published
4.1.0 naive artifact downloaded fresh from its release — all 18 new rsig TRB channels finite, no
channel column missing. No refit, no new download.


Full notes in CHANGELOG.md.
Pair with mirpy-lib 4.3.0 for the geometry half; run both against the same corpus name and join on
sample_id.