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.