Metadata-Version: 2.5
Name: vdjmatch
Version: 1.2.2
Summary: Fast, control-calibrated annotation of T-cell receptor antigen specificity
Project-URL: Homepage, https://github.com/antigenomics/vdjmatch
Project-URL: Repository, https://github.com/antigenomics/vdjmatch
Project-URL: Documentation, https://antigenomics.github.io/vdjmatch/
Author-email: ISALGO laboratory <mikhail.shugay@gmail.com>
License: ISALGO LAB Academic and Non-Commercial Research License
        Version 1.0
        
        Copyright (c) 2026 ISALGO LAB. All rights reserved.
        
        0. DEFINITIONS
        
           "Software" means the software, source code, scripts, models, trained
           parameters, and associated documentation files distributed under this
           license, together with any Modification thereof.
        
           "Modification" means any change to, adaptation of, translation of, or work
           derived from the Software, in whole or in part.
        
           "Output" means any data produced by running the Software, including
           predictions, scores, embeddings, annotations, labels, rankings, alignments,
           simulated or synthetic data, and any file derived from them.
        
           "Model" means any machine-learning or statistical system whose parameters
           are fitted from data, including neural networks, gradient-boosted trees,
           regression models, and any set of trained parameters, whether or not
           distributed together with code.
        
           "You" means the individual or legal entity exercising the rights granted
           below.
        
           "Non-Commercial Use" means use for academic, educational, or scientific
           research purposes from which no commercial advantage or monetary
           compensation is sought or obtained, whether directly or indirectly.
        
           "Commercial Use" means any use that is not Non-Commercial Use, including
           without limitation: (a) use in or to develop a product, service, or
           pipeline that is sold, licensed, rented, or otherwise monetized;
           (b) use by a for-profit entity in connection with its business operations,
           including internal evaluation, benchmarking, or research and development;
           (c) use to provide services to third parties for a fee, including
           consulting, contract research, or hosted or cloud-based provision of the
           Software's functionality; (d) use in research performed under contract for,
           or funded directly by, a for-profit entity for that entity's proprietary
           benefit; and (e) any use described in Section 3.
        
        1. GRANT OF RIGHTS
        
           Permission is hereby granted, free of charge, to any person obtaining a
           copy of the Software, to use, copy, modify, merge, publish, and distribute
           the Software for Non-Commercial Use only, subject to all conditions below.
           No rights are granted other than those expressly stated here; all rights
           not expressly granted are reserved by the copyright holder.
        
        2. PROHIBITED USE
        
           Commercial Use of the Software is prohibited without a separate written
           license signed by the copyright holder.
        
        3. MACHINE-LEARNING AND MODEL TRAINING
        
           3.1 The following are permitted under this license only when the resulting
               Model and its Outputs are themselves put to Non-Commercial Use:
        
               (a) training, fine-tuning, pre-training, continued training, or
                   retraining any Model on the Software, on its source code, or on
                   its Output;
               (b) using the Output as training data, labels, targets, weak
                   supervision, reward or preference signal, validation data, or test
                   data for any Model;
               (c) using the Software or its Output to filter, clean, augment, score,
                   rank, deduplicate, or otherwise curate a data set used to train
                   any Model;
               (d) distilling, pruning, quantizing, compressing, or otherwise
                   deriving a second Model from any Model distributed as part of the
                   Software, or from that Model's Output;
               (e) using the Software or its Output to benchmark, evaluate, validate,
                   tune hyperparameters of, or select among Models;
               (f) embedding the Software, or a Model trained in any of the ways
                   above, in an automated or agent-driven pipeline.
        
           3.2 Each activity listed in Section 3.1 is Commercial Use, and therefore
               prohibited without a separate written license, whenever the resulting
               Model, its Outputs, its parameters, or any system containing it is:
               sold, licensed, rented, hosted, or otherwise monetized; used by or on
               behalf of a for-profit entity in connection with its business
               operations; used to provide services to third parties for a fee; or
               used to support an application for, prosecution of, or exploitation of
               a patent or other proprietary right held by a for-profit entity.
        
           3.3 A Model is subject to this Section regardless of how much of the
               Software or its Output contributed to that Model, and regardless of
               whether the Software or its Output can be recovered from the trained
               parameters. Intermediate steps do not remove a Model from the scope of
               this Section: a Model trained on a data set that was itself produced,
               curated, or filtered using the Software remains subject to it.
        
           3.4 Where a Model is trained partly on the Software or its Output and
               partly on other material, Section 3.2 applies to that Model in full.
        
           3.5 Publication of research results, including trained parameters released
               for Non-Commercial Use under terms no less restrictive than this
               license, is permitted and encouraged.
        
        4. REDISTRIBUTION
        
           You may distribute the Software, with or without Modification, provided
           that You:
        
           (a) retain this license in full, including the copyright notice of
               Section 0 and the disclaimer of Section 9, in all copies and in all
               Modifications;
           (b) do not sublicense the Software or impose any additional or different
               terms, so that every recipient receives exactly the rights and
               restrictions granted here and no more;
           (c) mark each Modification with a prominent notice stating that the file
               has been changed, by whom, and on what date;
           (d) charge no fee for the Software itself, beyond the actual cost of
               physical media or transmission.
        
        5. ATTRIBUTION
        
           Any publication, presentation, preprint, poster, or derived work that makes
           use of the Software must cite this repository, or the corresponding
           publication where one is specified in the repository. Any released Model
           covered by Section 3 must state in its accompanying documentation that the
           Software was used in its construction.
        
        6. NO TRADEMARK OR PATENT RIGHTS
        
           This license grants no right to use the names, trademarks, or logos of
           ISALGO LAB, the copyright holder, or any contributor, whether to endorse or
           promote any work or otherwise, without prior written permission. This
           license grants no patent rights, express or implied, under any patent owned
           or controlled by the copyright holder.
        
        7. TERM AND TERMINATION
        
           The rights granted here apply for as long as You comply with this license
           and terminate automatically, without notice, upon any breach. Rights may be
           reinstated in writing by the copyright holder. Sections 2, 3, 6, 8, and 9
           survive termination. Upon termination You must cease all use of the
           Software and destroy all copies in Your possession, except copies retained
           solely for archival purposes required by law or institutional policy.
        
        8. COMMERCIAL AND TRIAL LICENSING
        
           Parties seeking Commercial Use, use of the Software or its Output in
           training a Model for Commercial Use, an evaluation or trial license, or any
           rights beyond those granted here should contact ISALGO LAB. Such licenses are
           granted only in writing.
        
        9. DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
        
           THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
           IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
           FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
           THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
           LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
           FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
           DEALINGS IN THE SOFTWARE.
        
           The Software is a research tool. It is not validated for clinical,
           diagnostic, therapeutic, or any other use on which health, safety, or
           financial decisions depend.
        
        10. SEVERABILITY
        
           If any provision of this license is held unenforceable, that provision
           shall be modified to the minimum extent necessary to make it enforceable,
           and the remaining provisions shall remain in full effect.
License-File: LICENSE
Keywords: AIRR,E-value,TCR,VDJdb,antigen-specificity,immunology,repertoire
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: polars<2,>=1.41.2
Requires-Dist: scipy>=1.9
Requires-Dist: seqtree>=1.3.2
Requires-Dist: threadpoolctl
Requires-Dist: vdjtools>=5.9.1
Provides-Extra: bench
Requires-Dist: huggingface-hub; extra == 'bench'
Requires-Dist: matplotlib; extra == 'bench'
Requires-Dist: psutil; extra == 'bench'
Requires-Dist: rapidfuzz; extra == 'bench'
Requires-Dist: scikit-learn; extra == 'bench'
Requires-Dist: seaborn; extra == 'bench'
Provides-Extra: cli
Requires-Dist: tqdm; extra == 'cli'
Provides-Extra: control
Requires-Dist: huggingface-hub; extra == 'control'
Requires-Dist: seqtree[control]; extra == 'control'
Provides-Extra: diagnostics
Requires-Dist: leidenalg<0.13,>=0.11; extra == 'diagnostics'
Provides-Extra: ndn
Requires-Dist: arda-mapper>=2.38.3; extra == 'ndn'
Provides-Extra: notebook
Requires-Dist: huggingface-hub; extra == 'notebook'
Requires-Dist: marimo; extra == 'notebook'
Requires-Dist: matplotlib; extra == 'notebook'
Provides-Extra: ods
Requires-Dist: ezodf; extra == 'ods'
Provides-Extra: precursor
Requires-Dist: numpy; extra == 'precursor'
Provides-Extra: test
Requires-Dist: biopython>=1.84; extra == 'test'
Requires-Dist: hypothesis; extra == 'test'
Requires-Dist: pytest>=7.4; extra == 'test'
Provides-Extra: vdjam
Requires-Dist: biopython>=1.84; extra == 'vdjam'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/vdjmatch_dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="assets/vdjmatch_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.
         Use the light (dark-on-transparent) raster so it reads on PyPI's white page. -->
    <img alt="vdjmatch" src="https://raw.githubusercontent.com/antigenomics/vdjmatch/master/assets/vdjmatch_light.png" width="340">
  </picture>
</p>

<h1 align="center">vdjmatch — TCR peptide–MHC annotation</h1>

<p align="center">
  <a href="https://pypi.org/project/vdjmatch/"><img alt="PyPI" src="https://img.shields.io/pypi/v/vdjmatch"></a>
  <a href="https://github.com/antigenomics/vdjmatch/actions/workflows/tests.yml"><img alt="tests" src="https://github.com/antigenomics/vdjmatch/actions/workflows/tests.yml/badge.svg"></a>
  <a href="https://docs.isalgo.dev/vdjmatch/"><img alt="docs" src="https://github.com/antigenomics/vdjmatch/actions/workflows/docs.yml/badge.svg"></a>
  <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-blue">
  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-Academic%20%26%20Non--Commercial-green"></a>
</p>

<p align="center"><b>
  <a href="https://docs.isalgo.dev/vdjmatch/tutorial.html">Get started</a> ·
  <a href="https://docs.isalgo.dev/vdjmatch/how-to.html">Guides</a> ·
  <a href="https://docs.isalgo.dev/vdjmatch/cli.html">Commands</a> ·
  <a href="https://docs.isalgo.dev/vdjmatch/api.html">API</a> ·
  <a href="https://docs.isalgo.dev/vdjmatch/examples.html">Examples</a>
</b></p>

`vdjmatch` annotates selected T-cell receptors and repertoires against
[VDJdb](https://github.com/antigenomics/vdjdb-db), preserving query identities and
reporting peptide–MHC candidates, competing evidence and optional background calibration.
Native sequence search uses [`seqtree`](https://github.com/antigenomics/seqtree);
repertoire ingestion reuses published `vdjtools` readers.
Dependency versions and native CPU budgets are managed by the installed package.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/algorithm-overview-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="assets/algorithm-overview.svg">
  <img alt="VDJmatch workflow: shared receptor-table validation and curated VDJdb search, followed by receptor annotation or matched-reference repertoire enrichment" src="https://raw.githubusercontent.com/antigenomics/vdjmatch/master/assets/algorithm-overview.png" width="100%">
  </picture>
</p>

## Quick start

```sh
python -m pip install vdjmatch
vdjmatch annotate sample.tsv -o annotation
```

Use AIRR `junction_aa` (including conserved anchors) and V calls. The curated
VDJdb reference is fetched on first use; add `--vdjdb reference.zip` for offline
input. Single TRA/TRB receptors and paired receptors are supported. Exact hits
are retained by default. Scores describe sequence evidence, not proof of binding.

For a small offline example, download the [examples directory](examples/) and run
`sh examples/annotate.sh annotation-demo` from the repository root.

## Choose a reference

The existing `match` command and `Annotator` API support three reference choices:

| Reference | Python | CLI |
| --- | --- | --- |
| Official vdjdb-db release | `Annotator.latest()` | `vdjmatch match queries.tsv` |
| Your VDJdb-format table/archive | `Annotator.from_path("reference.tsv")` | `vdjmatch match queries.tsv --reference reference.tsv` |
| Your labeled chains or pairs | `Annotator.from_labels(rows, locus="TRB")` | `vdjmatch match queries.tsv --reference labels.csv --reference-format labels --locus TRB` |

`--vdjdb` remains an alias for `--reference`. Ordinary queries retain exact matches.
Use `--exclude-exact` only when explicitly evaluating a classifier or assessing
record reliability; it filters hits while retaining the complete reference model.

A simple single-chain reference needs `junction_aa,label` (or `epitope` instead of
`label`). Supply `--locus TRA/TRB` or a reference `locus` column. For paired tables,
use `junction_aa_alpha,junction_aa_beta,label` and add `--paired`; each reference row
links its actual TRA/TRB pair. V/J, species and MHC metadata are optional. Missing
query locus fields use the explicit hint or the reference's sole locus; supplied
query metadata is retained. The sequences include conserved junction anchors.

```python
from vdjmatch import Annotator

single = Annotator.from_labels([("CASSQYF", "class-a"), ("CATSRYF", "class-b")], locus="TRB")
calls = single.annotate(["CASSQYF", "CWWWWWWWF"])

paired = Annotator.from_labels([("CAVQYF", "CASSQYF", "class-a")])
```

Labeled references are indexed directly without VDJdb-specific curation or
reference-diagnostic preparation. Their labels are opaque class names, reported
in the existing `epitope` output fields. They default to uncalibrated matching;
request `--evalue` with the appropriate organism/controls for calibration.
Run [the synthetic single/paired example](examples/labeled_references.py) for a
complete Python example.

## Documentation

| Need | Guide |
| --- | --- |
| Learn the workflow | [Getting started](https://docs.isalgo.dev/vdjmatch/tutorial.html) · [Rendered notebooks](https://docs.isalgo.dev/vdjmatch/notebooks.html) |
| Annotate a cohort or use an offline reference | [How-to guides](https://docs.isalgo.dev/vdjmatch/how-to.html) · [Runnable examples](https://docs.isalgo.dev/vdjmatch/examples.html) |
| Look up inputs, options and outputs | [CLI reference](https://docs.isalgo.dev/vdjmatch/cli.html) · [Python API](https://docs.isalgo.dev/vdjmatch/api.html) |
| Understand methods and formulas | [Scoring](https://docs.isalgo.dev/vdjmatch/scoring.html) · [Evidence and calibration](https://docs.isalgo.dev/vdjmatch/explanation.html) |
| Test repertoire enrichment | [Matching, nulls and count units](https://docs.isalgo.dev/vdjmatch/repertoire-method.html) |
| Estimate precursor frequency | [Method](https://docs.isalgo.dev/vdjmatch/pgen.html) · [Experimental compendium](https://docs.isalgo.dev/vdjmatch/compendium.html) |

The legacy Java/Groovy implementation remains on [`legacy-java`](https://github.com/antigenomics/vdjmatch/tree/legacy-java)
and [Java tag 1.3.1](https://github.com/antigenomics/vdjmatch/tree/1.3.1), with
JitPack artifact `com.github.antigenomics:vdjmatch:1.3.1`.

## License

ISALGO LAB Academic and Non-Commercial Research License v1.0. See [LICENSE](LICENSE).

CPU budgets use `threads=0` for automatic parallel work, capped at 16 allocated CPUs.
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.

Candidate-only annotation coalesces up to 256 complete query identities and
64 MiB of queued expanded tables per reduction. Native search and alias expansion
keep small blocks; larger complete-query frames are consumed directly.
