Worked examples#
Fifteen runnable notebooks under examples/, each a complete piece of work — its data, its
commands and its conclusions in one file. Several reproduce a published result, so you can see what
the library does on data whose answer is already known.
They are marimo notebooks, which are plain Python files with
@app.cell decorators rather than JSON. That means they diff and review like source code, and
they run three ways:
pip install 'vdjtools[examples]'
marimo edit examples/preprocess.py # interactive, cells re-run as you edit
marimo run examples/preprocess.py # read-only app, no code shown
python examples/preprocess.py # plain script; prints, no UI
Data is fetched from Hugging Face on first run and cached under examples/.data/, so a fresh
pip install is enough — no local paths and no pre-staged files. If you already hold a copy,
drop it under ./data_dump/ (gitignored) and it is used instead of downloading. Notebooks that
need an extra say so; examples/README.md gives the exact install line for each.
Start here#
What to do to real data before measuring anything. The three independent filtering axes — productive, abundance, and sequencing artefact — on real Britanova samples from three sequencing batches, with what each filter removes and what it costs you.
A complete study, read three ways on one cohort: 78 donors aged 0–103. Diversity falls with age, repertoires become more clonal, and individual repertoires drift apart — each measured in a way that removes the sequencing-depth confound rather than assuming it away.
Describing a cohort#
The out-of-core pattern: every sample streamed once into a partitioned Parquet store, then every statistic a single streamed query over it. Slide the sample count toward thousands and watch peak memory stay flat. No data to download.
Amino-acid properties of the junction — hydropathy, charge, volume, the Kidera factors — per sample, correlated with donor age across the ageing cohort. Junction hydropathy carries the strongest single association.
Comparing repertoires#
Three different questions that all get called “overlap”: identical clonotypes, clonotypes within one substitution, and graded sequence similarity. The third finds shared structure between repertoires that share no identical clonotype, which the first two report as zero.
Following clonotypes through a vaccination time course — yellow fever, influenza, TBE. Which clones emerged, expanded, persisted, contracted or vanished, tested within donor, plus a recapture model for the clones you did not resample.
Finding sequences associated with a phenotype#
The core of Emerson et al. (Nat Genet 2017) on their published cohort: an incidence-based screen for public TCR-beta chains associated with CMV serostatus or HLA-A*02, checked live against VDJdb.
The streaming version of that screen over the whole cohort, with peak memory reported, for when the candidate set is the whole repertoire rather than a shortlist.
The interactive superset: condition, test and match scope as controls, with a co-occurrence panel for finding chains that travel together — alpha/beta partners, or one clone’s relatives.
Reproducing a published TRBV9 junction motif in ankylosing spondylitis, and why it takes an HLA-B27-matched comparison to say anything: B27 is 26/27 tied to disease in that cohort, so the unmatched contrast cannot separate disease from carriage.
Features for a model#
Three feature choices that are easy to get wrong, each measurable in seconds: why the amino-acid block is arcsine-transformed rather than logged, why an ambiguous V call must be resolved rather than stripped, and why the number of components kept is a real choice.
A folder of AIRR files to one row per sample, joined to your metadata sheet — both halves of the signature, the commands and the join. The end-to-end recipe; lives in the companion repository.
Single-cell data#
10x contigs in, alpha/beta receptors out: chain-multiplicity QC, doublet handling, pairing, then unsupervised clustering of beta junctions graded against dextramer antigen labels.
vdjtools sitting in the middle of the single-cell ecosystem rather than replacing any of it. One flat AIRR table is the seam: hand it to each container, read it back, and attach a score to an AnnData you did not build.
Recombination models#
Build, fit, check, compare and score a V(D)J generation model end to end — from a custom germline library through expectation-maximisation to held-out likelihood. Runs offline in seconds on a toy locus.
What is actually inside a recombination model: the dependency graph between events, per-event entropy, mutual information, and every marginal table. Uses the models shipped in the wheel, so there is nothing to download.