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.

Native Windows installation uses the same pip install command; WSL is not required. The Windows workflow builds and installs a wheel, then checks batched receptor embedding and sample PCA with the native dependencies.

Choose your output

mir embed clonotypes samples/*.tsv -o clonotypes.tsv
mir embed repertoires samples/*.tsv --save-basis basis -o rff.tsv
mir embed repertoires held_out/*.tsv --basis basis -o held_out_rff.tsv
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

Logical CPUs are hardware threads, not physical cores: a 40-logical-CPU node may have 20 physical cores. Automatic sizing uses visible topology and respects affinity, SLURM and container limits; unknown topology falls back to the logical allocation. Explicit positive budgets may use SMT threads within that allocation.

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. Automatic budgets use the physical cores visible within the CPU allocation and manage inner kernels automatically. An explicit positive count overrides the automatic budget within your allocation. Known large allocations check container memory. See the resource contract and embedding memory guide.

Agent skill

The mirpy skill routes embedding, density and signature workflows to the public APIs and guides. Copy skills/mirpy into your agent’s skill directory or read it in this checkout.

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.