Metadata-Version: 2.5
Name: mirpy-lib
Version: 4.7.0
Summary: ML-oriented embeddings for immune receptor repertoires (TCR/BCR)
Project-URL: Homepage, https://github.com/antigenomics/mirpy
Project-URL: Repository, https://github.com/antigenomics/mirpy
Project-URL: Documentation, https://antigenomics.github.io/mirpy
Project-URL: Issues, https://github.com/antigenomics/mirpy/issues
Author-email: ISALGO lab <mikhail.shugay@gmail.com>
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: AIRR,BCR,TCR,VDJdb,embedding,immunosequencing,prototypes
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Requires-Dist: numpy
Requires-Dist: polars<2,>=1.0
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: seqtree>=1.0.0
Requires-Dist: vdjtools>=5.1.0
Provides-Extra: ann
Requires-Dist: numba>=0.60; extra == 'ann'
Requires-Dist: numpy<2.5; extra == 'ann'
Requires-Dist: pynndescent; extra == 'ann'
Provides-Extra: annotate
Requires-Dist: vdjmatch; extra == 'annotate'
Provides-Extra: bench
Requires-Dist: huggingface-hub; extra == 'bench'
Requires-Dist: kneed; extra == 'bench'
Requires-Dist: lifelines; extra == 'bench'
Requires-Dist: matplotlib; extra == 'bench'
Requires-Dist: seaborn; extra == 'bench'
Provides-Extra: build
Requires-Dist: biopython; extra == 'build'
Requires-Dist: vdjtools[model]>=5.1.0; extra == 'build'
Provides-Extra: dev
Requires-Dist: psutil>=5; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Provides-Extra: docs
Requires-Dist: pydata-sphinx-theme<1,>=0.15; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Requires-Dist: sphinx-design; extra == 'docs'
Requires-Dist: sphinx<9,>=7.2; extra == 'docs'
Provides-Extra: examples
Requires-Dist: marimo; extra == 'examples'
Requires-Dist: matplotlib; extra == 'examples'
Requires-Dist: umap-learn; extra == 'examples'
Provides-Extra: ml
Requires-Dist: torch; extra == 'ml'
Provides-Extra: parquet
Requires-Dist: pyarrow; extra == 'parquet'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/mirpy_dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="assets/mirpy_light.svg">
    <!-- Absolute PNG fallback: PyPI strips <picture>/<source> and cannot render a relative or
         raw-served SVG, so the logo must be an absolute-URL raster here. GitHub uses the SVG sources. -->
    <img alt="mirpy" src="https://raw.githubusercontent.com/antigenomics/mirpy/master/assets/mirpy_light.png" width="360">
  </picture>
</p>

<h1 align="center">mirpy — ML embeddings for immune repertoires</h1>

<p align="center">
  <a href="https://pypi.org/project/mirpy-lib/"><img alt="PyPI" src="https://img.shields.io/pypi/v/mirpy-lib.svg"></a>
  <a href="https://pypi.org/project/mirpy-lib/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/mirpy-lib.svg"></a>
  <a href="https://github.com/antigenomics/mirpy/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/antigenomics/mirpy/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://docs.isalgo.dev/mirpy/"><img alt="docs" src="https://github.com/antigenomics/mirpy/actions/workflows/docs.yml/badge.svg"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-GPLv3-green"></a>
</p>

<p align="center"><b>
  <a href="https://docs.isalgo.dev/mirpy/getting-started.html">Get started</a> ·
  <a href="https://docs.isalgo.dev/mirpy/usage.html">Guides</a> ·
  <a href="https://docs.isalgo.dev/mirpy/cli.html">Commands</a> ·
  <a href="https://docs.isalgo.dev/mirpy/api.html">API</a> ·
  <a href="https://docs.isalgo.dev/mirpy/math.html">Theory</a> ·
  <a href="https://docs.isalgo.dev/mirpy/notebooks.html">Examples</a> ·
  <a href="https://docs.isalgo.dev/mirpy/glossary.html">Glossary</a>
</b></p>

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

```bash
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](https://docs.isalgo.dev/mirpy/getting-started.html).

## 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 |

```bash
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](https://docs.isalgo.dev/mirpy/embeddings.html) covers fitting
on input rows, compatible control rows or a saved rotation, output columns and
memory limits. [Signatures](https://docs.isalgo.dev/mirpy/signature.html) explains
published rsig corpora and joining vdjtools' vsig on `sample_id`.

## Python quickstart

```python
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](https://docs.isalgo.dev/mirpy/embeddings.html) |
| Filtering before embedding | [Pre-processing](https://docs.isalgo.dev/mirpy/preprocessing.html) |
| Density, MMD, digital donors, codecs and CPU budgets | [User guide](https://docs.isalgo.dev/mirpy/usage.html) |
| Corpus signatures and pass-through channels | [Signatures](https://docs.isalgo.dev/mirpy/signature.html) · [Channels](https://docs.isalgo.dev/mirpy/channels.html) |
| Functions, flags, examples and terminology | [API](https://docs.isalgo.dev/mirpy/api.html) · [Commands](https://docs.isalgo.dev/mirpy/cli.html) · [Examples](https://docs.isalgo.dev/mirpy/notebooks.html) · [Glossary](https://docs.isalgo.dev/mirpy/glossary.html) |
| Mathematical derivations | [Theory](https://docs.isalgo.dev/mirpy/math.html) |

## 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](https://docs.isalgo.dev/mirpy/usage.html#mir-resource-limits)
and [embedding memory guide](https://docs.isalgo.dev/mirpy/embeddings.html#memory-use).

## Development

```bash
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](https://docs.isalgo.dev/mirpy/api.html); 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](https://docs.isalgo.dev/mirpy/math.html) 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`](https://github.com/antigenomics/mirpy/tree/legacy-v2) branch
(`mirpy-lib` 2.x); its functionality lives on in
[vdjtools](https://github.com/antigenomics/vdjtools) and
[vdjmatch](https://github.com/antigenomics/vdjmatch).
