mirpy — ML embeddings for immune repertoires
Get started · Guides · Commands · API · Theory · Examples · Glossary
Turn T- and B-cell receptor tables into clonotype coordinates, sample RFF vectors, or published corpus signatures. PyPI package mirpy-lib, Python import mir. Native alignment and repertoire IO come from seqtree and vdjtools.
Install
pip install mirpy-lib
Optional extras: [parquet] for streaming clonotype Parquet, [ann] for approximate
neighbours, [ml] for Torch codecs, [bench] for evaluation, and [examples] for
marimo notebooks. See installation and first steps.
Choose your output
| Command | Output |
|---|---|
mir embed clonotypes |
Clonotype coordinates with sample/clonotype IDs |
mir embed repertoires |
One weighted RFF vector per sample, plus separate channels |
mir pca |
Optional sample PCs from an RFF table |
mir embeddings / mir signature |
Existing corpus-standardised rsig features |
mir embed clonotypes samples/*.tsv -o clonotypes.tsv --threads 1
mir embed repertoires samples/*.tsv --save-basis basis -o rff.tsv --threads 1
mir embed repertoires held_out/*.tsv --basis basis -o held_out_rff.tsv --threads 1
mir pca rff.tsv --fit rotation.npz --n-components 32 -o pcs.tsv
mir pca held_out_rff.tsv --rotation rotation.npz -o held_out_pcs.tsv
The sample path is clonotype coordinates → shared clonotype basis → RFF → weighted mean → optional sample PCA. Every sample must use the same basis and weighting. Save and reuse the basis and, if fitted, the sample rotation. RFF is applied before averaging. rsig is a different representation; its corpus rotations cannot rotate RFF.
The embedding guide covers fitting
on input rows, compatible control rows or a saved rotation, output columns and
memory limits. Signatures explains
published rsig corpora and joining vdjtools' vsig on sample_id.
Python quickstart
import mir # establish runtime limits before numerical libraries
import polars as pl
from mir.embedding.tcremp import TCREmp
sample = pl.DataFrame({
"v_call": ["TRBV10-3*01", "TRBV20-1*01"],
"j_call": ["TRBJ2-7*01", "TRBJ1-2*01"],
"junction_aa": ["CASSIRSSYEQYF", "CSARVSGYYGYTF"],
})
model = TCREmp.from_defaults("human", "TRB")
coordinates = model.embed(sample) # interleaved V, J, junction distances per prototype
Find the right page
| Task | Guide |
|---|---|
| RFF tables, shared bases and sample PCA | Embeddings |
| Filtering before embedding | Pre-processing |
| Density, MMD, digital donors, codecs and CPU budgets | User guide |
| Corpus signatures and pass-through channels | Signatures · Channels |
| Functions, flags, examples and terminology | API · Commands · Examples · Glossary |
| Mathematical derivations | Theory |
Resource budgets
Import mir before numerical libraries in a fresh interpreter. Sample workers use
serial inner kernels and retain one sample each; only compact RFF rows survive.
The final table still grows with cohort size and RFF width, and a deep input sample
can dominate memory. Use --threads 1 for serial sample processing or a positive
count within your allocation. Known large allocations check container memory.
See the resource contract
and embedding memory guide.
Development
bash setup.sh --dev-parents --docs --tests
source .venv/bin/activate
python -m pytest tests/ -q -m "not integration and not benchmark"
env -C docs make html
Uses a repo-local uv environment. Public APIs and architecture are documented in the API reference; no private agent files are needed to use the package.
Citing
Method: Kremlyakova et al., TCREMP: a bioinformatic pipeline for efficient embedding of T-cell receptor sequences, J Mol Biol 437 (2025) 169205.
See the mathematical foundations for derivations.
License
GPL-3.0-or-later. The classical v1.x/v2 repertoire toolkit — parsing, overlap, diversity, TCRnet,
GLIPH — is frozen on the legacy-v2 branch
(mirpy-lib 2.x); its functionality lives on in
vdjtools and
vdjmatch.
Release files for mirpy-lib 4.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mirpy_lib-4.7.0.tar.gz | 5.7 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mirpy_lib-4.7.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 7.8 MB
Release files / mirpy_lib-4.7.0.tar.gz
| Download URL | mirpy_lib-4.7.0.tar.gz |
|---|---|
| Size | 5.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f05100c5f33ca8ba88883775a94dad10509b1c13f7484a2f1d86a0feee81d727
|
|
BLAKE2b-256 checksum How to use checksums |
b2ba1f5b1a0c4bca430912480f1797ed905d0dd23b07b8209f191bc5cb6f3403
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / mirpy_lib-4.7.0-py3-none-any.whl
| Download URL | mirpy_lib-4.7.0-py3-none-any.whl |
|---|---|
| Size | 2.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
05601e5595f25e369c08ffe6e19c68fc21e42d42b5f57f3425c8d97231d5eb2c
|
|
BLAKE2b-256 checksum How to use checksums |
02418171fa7822a095030c1f9a06748e65adda0511d6f434a364d6a665d8d51b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency log
