Worked examples#
Six runnable notebooks under examples/. Each one is a complete piece of work with its data,
its commands and its conclusions in one file, so it can be read start to finish or edited and
re-run against your own samples.
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 'mirpy-lib[examples]'
marimo edit examples/signature_pipeline.py # interactive, cells re-run as you edit
marimo run examples/signature_pipeline.py # read-only app, no code shown
python examples/signature_pipeline.py # plain script; prints, no UI
Obtain the example scripts from the repository before running these commands; they are
not included in the installed wheel. The downloadable examples fetch data from Hugging Face
on first run and store raw inputs under examples/.data/; the theory example uses bundled data. If you already hold a copy,
drop it under ./data_dump/ (gitignored) and it is used instead of downloading.
Start here#
Read this one first. A directory of AIRR TSVs to one row per sample, joined to your own metadata sheet — the commands, the join, and how to read the result. Uses downloadable AIRR inputs; read Clonotype and sample embeddings for the RFF workflow instead.
Clonotypes to vectors. What it means to place a receptor sequence at a point, what the coordinates stand for, and the distance approximation the placement rests on. Clusters antigen-specific TCRs and colours a UMAP by epitope.
Going further#
Why the geometry half is transformed differently from the statistics half — read live from the registry, not typed into the notebook — and how many principal components survive a refit on a disjoint set of donors. The answer is smaller than “90% of the variance” suggests.
Which receptors have more similar neighbours than a background model predicts. Fits a density over sequence space, runs neighbourhood enrichment against a generation-probability background, and reads out the convergent family that drives the signal.
Tracking one donor’s repertoire through time with a covariate-disentangled trajectory, fitting a generative model over repertoire states, and drawing a synthetic donor from it — a “what if this donor had been sicker” counterfactual.
The results the library rests on, each with the measurement that supports it: the distance laws, the correspondence between embedding distance and sequence distance, and how much the choice of reference panel matters. Runs on bundled data.
Note
The full benchmark suite — VDJdb specificity tables, density benchmarks and cohort analyses — lives in a companion analysis repository, not here. This repository keeps the library, its tests, and these examples.