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

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.

Frozen reference bundles, vdjtools models and examples are hosted in AIRR feature signatures. Run mir reference rna-blood to print a checksum-verified local bundle directory; use its matching basis and rotation as described in the embedding guide.

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

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 from Immune Repertoire and Single-cell Sequencing Data, J Mol Biol 437(15) (2025) 169205. PubMed · DOI.

See the mathematical foundations for derivations.

License

ISALGO LAB Academic and Non-Commercial Research License v1.0. See LICENSE.

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.

Configured statistical references

Reference bundles can opt into vdjtools' basic or joint statistical features and their IMGT11/BLOSUM62 motif variants via feature_definition=. The bundle records the definition and vocabulary for compatible saved-PCA application. Configured fitting delegates to vdjtools' sparse TablePCA.fit_features, preserving raw median-impute/StandardScaler coordinates without a dense training table. Sample workers join before the BLAS phase. Existing rsig and sample RFF behavior stays unchanged; see the embedding guide.

New synthetic reference/background calls default to vdjtools' isalgo family. Use olga-legacy (olga alias) for frozen OLGA parameters and reference sampler streams. learned and arda alias fresh isalgo; old fitted weights require a pinned previous release. Existing corpus, prototype and embedding artifacts remain unchanged; changing a default does not refit a saved reference.

CPU budgets use threads=0 for automatic parallel work, capped at 16 allocated CPUs (eight for Torch training/inference). Use 1 for serial work or a positive count to override the automatic cap within the scheduler/container allocation. Sample workers keep their inner numerical kernels serial.