Metadata-Version: 2.2
Name: vdjtools
Version: 5.1.0
Summary: TCR/BCR repertoire analysis — Pgen/generation/inference, diversity, overlap, biomarkers (Python + C++)
Keywords: immunology,tcr,bcr,airr,repertoire,pgen,olga,igor,bioinformatics
Author-Email: Mikhail Shugay <mikhail.shugay@gmail.com>
License: GPL-3.0-or-later
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Project-URL: Homepage, https://github.com/antigenomics/vdjtools
Project-URL: Repository, https://github.com/antigenomics/vdjtools
Project-URL: Documentation, https://antigenomics.github.io/vdjtools/
Requires-Python: >=3.10
Requires-Dist: polars<2,>=1.0
Requires-Dist: numpy
Requires-Dist: threadpoolctl>=3
Requires-Dist: scipy
Requires-Dist: typer>=0.12
Requires-Dist: arda-mapper>=2.36.0
Requires-Dist: seqtree>=1.0.0
Requires-Dist: vdjmatch>=0.1.2
Requires-Dist: huggingface_hub
Provides-Extra: model
Provides-Extra: overlap
Requires-Dist: scikit-learn; extra == "overlap"
Provides-Extra: preprocess
Provides-Extra: sc
Requires-Dist: scikit-learn; extra == "sc"
Requires-Dist: pyyaml; extra == "sc"
Requires-Dist: anndata; extra == "sc"
Requires-Dist: awkward; extra == "sc"
Requires-Dist: mudata; extra == "sc"
Provides-Extra: interop
Requires-Dist: scirpy; extra == "interop"
Requires-Dist: sc-dandelion; extra == "interop"
Provides-Extra: examples
Requires-Dist: marimo; extra == "examples"
Requires-Dist: matplotlib; extra == "examples"
Requires-Dist: scikit-learn; extra == "examples"
Provides-Extra: oracle
Requires-Dist: olga; extra == "oracle"
Provides-Extra: test
Requires-Dist: pytest>=7.4; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: tomli>=1.1; python_version < "3.11" and extra == "test"
Provides-Extra: bench
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pybind11>=2.12; extra == "dev"
Provides-Extra: all
Requires-Dist: scikit-learn; extra == "all"
Description-Content-Type: text/markdown

<p align="center">
  <!-- GitHub honours <source> and gets the SVG in both colour schemes; PyPI strips <picture>/<source>
       and cannot render SVG, so it falls through to the absolute-URL PNG in the <img>. -->
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/antigenomics/vdjtools/master/assets/vdjtools_dark.svg">
    <source srcset="https://raw.githubusercontent.com/antigenomics/vdjtools/master/assets/vdjtools_light.svg">
    <img alt="vdjtools" src="https://raw.githubusercontent.com/antigenomics/vdjtools/master/assets/vdjtools_light.png" width="340">
  </picture>
</p>

<h1 align="center">vdjtools — immune-repertoire analysis</h1>

<p align="center">
  <a href="https://pypi.org/project/vdjtools/"><img alt="PyPI" src="https://img.shields.io/pypi/v/vdjtools"></a>
  <a href="https://github.com/antigenomics/vdjtools/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/antigenomics/vdjtools/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://docs.isalgo.dev/vdjtools/"><img alt="docs" src="https://github.com/antigenomics/vdjtools/actions/workflows/docs.yml/badge.svg"></a>
  <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-blue">
  <img alt="license" src="https://img.shields.io/badge/license-GPLv3-green">
</p>

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

Read receptor tables, measure diversity and overlap, fit recombination models,
and export statistical feature tables or published corpus signatures. vdjtools is
a Python/C++ rewrite of the original Groovy/Java tool, using AIRR column names and
Polars frames. arda, seqtree and vdjmatch supply the shared native/reference engines.

## Install

```bash
pip install vdjtools
```

Prebuilt CPython wheels include the native extension. A source install needs a C++
toolchain. Optional extras include `[overlap]` for sample MDS, `[sc]` for single-cell
bridges and `[examples]` for marimo notebooks. See [getting started](https://docs.isalgo.dev/vdjtools/getting-started.html).

## Quickstart

```python
from vdjtools import io, stats   # import before numerical libraries

sample = io.read("clones.tsv")
diversity = stats.diversity_stats(sample)
v_usage = stats.segment_usage(sample, "v")
```

```bash
vdjtools diversity samples/*.tsv -o diversity.tsv
vdjtools features samples/*.tsv --coverage 0.8 --threads 1 -o features.tsv
vdjtools signature --corpus blood samples/*.tsv -o vsig.tsv
```

`features` exports unrotated measurements and channels without a corpus.
Declared log/CLR/logit transforms remain; “raw” means before corpus scaling,
winsorization and PCA. `signature` applies the published vsig corpus transform.
These are different outputs. mirpy's rsig geometry half joins vsig on `sample_id`;
mirpy's sample RFF vectors are a separate representation.

Fit your own sample PCA on selected measurements, compatible control rows, or reuse
a saved rotation:

```bash
vdjtools pca features.tsv --columns feature_columns.txt --fit rotation.npz --components 32 -o pcs.tsv
vdjtools pca new_features.tsv --rotation rotation.npz -o new_pcs.tsv
```

The [raw feature/PCA guide](https://docs.isalgo.dev/vdjtools/features.html) explains
feature selection, coverage, imputation, feature-space identities and saved rotations.

## Find the right page

| Task | Guide |
|---|---|
| Load, measure and compare your first samples | [Getting started](https://docs.isalgo.dev/vdjtools/getting-started.html) |
| Filter, correct, downsample or pool | [Pre-processing](https://docs.isalgo.dev/vdjtools/preprocessing.html) |
| Diversity, overlap, gene usage, biomarkers and dynamics | [User guide](https://docs.isalgo.dev/vdjtools/usage.html) |
| Unrotated features and optional sample PCA | [Raw features](https://docs.isalgo.dev/vdjtools/features.html) |
| Published vsig/rsig corpus coordinates | [Signatures](https://docs.isalgo.dev/vdjtools/signature.html) · [Methods](https://docs.isalgo.dev/vdjtools/signature-methods.html) · [Channels](https://docs.isalgo.dev/vdjtools/channels.html) |
| Pgen, generation and model fitting | [Model workshop](https://docs.isalgo.dev/vdjtools/model.html) |
| Single-cell data and interoperability | [Single cell](https://docs.isalgo.dev/vdjtools/singlecell.html) |
| Functions, flags, examples and terms | [API](https://docs.isalgo.dev/vdjtools/api.html) · [Commands](https://docs.isalgo.dev/vdjtools/cli.html) · [Examples](https://docs.isalgo.dev/vdjtools/notebooks.html) · [Glossary](https://docs.isalgo.dev/vdjtools/glossary.html) |

Recorded [performance measurements](https://docs.isalgo.dev/vdjtools/index.html#performance)
and [model validation](https://docs.isalgo.dev/vdjtools/model.html) describe the
native Pgen, generation and inference engines.

## Resource budgets

Import `vdjtools` before numerical libraries in a fresh interpreter. Native batch
APIs use allocation-aware CPU budgets; sample workers use serial inner kernels.
Signature `--jobs` and analysis `--threads` select bounded workers, with `0` for the
detected allocation. Excessive or nested budgets raise. The final feature table
and PCA workspace still grow with sample count and feature width. See
[CPU/container limits](https://docs.isalgo.dev/vdjtools/usage.html#cpu-container-limits).

## Development

```bash
bash setup.sh --dev-parents --tests
source .venv/bin/activate
uv pip install -e ".[docs]"
pytest tests/python -q -m "not slow and not heavy and not benchmark"
env -C docs make html
```

Uses a repo-local uv environment and a C++ toolchain. See the API reference for
public functions and the model workshop for native model workflows.

## Citing

For the v2 rewrite, cite this repository. For the original tool, cite
[Shugay et al., *PLoS Computational Biology* 2015](https://doi.org/10.1371/journal.pcbi.1004503).
The VDJtrack recapture model in `vdjtools.dynamics` is Pavlova, Zvyagin and Shugay (2024).

## License

GPL-3.0-or-later. The legacy Groovy/Java v1.x tool lives on the
[`legacy-1.x`](https://github.com/antigenomics/vdjtools/tree/legacy-1.x) branch, with its releases
under the repository tags `v0.0.1` … `1.2.1`.
