Metadata-Version: 2.2
Name: vdjtools
Version: 2.0.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>=1.0
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: model
Requires-Dist: arda-mapper>=2.5; extra == "model"
Provides-Extra: overlap
Requires-Dist: vdjmatch>=0.0.1; extra == "overlap"
Provides-Extra: cli
Requires-Dist: typer>=0.12; extra == "cli"
Provides-Extra: examples
Requires-Dist: marimo; extra == "examples"
Requires-Dist: huggingface_hub; 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"
Provides-Extra: bench
Requires-Dist: huggingface_hub; 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"
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: arda-mapper>=2.5; extra == "all"
Requires-Dist: vdjmatch>=0.0.1; extra == "all"
Requires-Dist: typer>=0.12; extra == "all"
Description-Content-Type: text/markdown

# vdjtools 2.0

TCR/BCR immune-repertoire analysis — a clean-room **Python + C++** rewrite of the legacy
Groovy/Java [vdjtools](https://doi.org/10.1371/journal.pcbi.1004503), standardised on the
**AIRR schema** and **polars** DataFrames with minimal object-orientation.

Built on the antigenomics ecosystem:
[seqtree](https://github.com/antigenomics/seqtree) (fuzzy search / e-value engine),
[vdjmatch](https://github.com/antigenomics/vdjmatch) (overlap + TCRnet),
[arda](https://github.com/antigenomics/arda) (AIRR annotation + markup repair).

> **Status: v2.0.0 under active development.** The legacy v1.x tool lives on the
> [`legacy-1.x`](https://github.com/antigenomics/vdjtools/tree/legacy-1.x) branch and its
> releases remain available under the repository tags (`v0.0.1` … `1.2.1`).

## Capabilities (rolling out by phase — see [ROADMAP.md](ROADMAP.md))

- **Model** — native V(D)J recombination model: generation probability (Pgen), sequence
  generation, and EM model inference. Supersedes OLGA and IGoR: arda-driven scenario
  enumeration, polars marginal tables, D-D tandem support, and a native (pybind11) Pgen/EM core.
- **Stats** — diversity (Chao1/Shannon/Simpson/…), spectratype, V/J/VJ usage.
- **Features** — CDR physicochemical profiles, k-mer / V+k-mer summaries.
- **Overlap** — sample overlap and TCRnet (via vdjmatch/seqtree).
- **Preprocess** — downsampling, error-correction, VJ-usage batch-effect correction, pooling/joining.
- **Biomarker** — incidence-based association (Fisher) vs HLA / condition / chain-pairing; metaclonotypes.
- **Single-cell** — AIRR Cell / 10x interoperability.

## Install

```bash
conda env create -f environment.yml   # python + mmseqs2 (arda backend) + C++ toolchain
conda activate vdjtools
pip install -e ".[dev,test]"          # builds the _core C++ extension
```

Or run the bootstrap script: `bash setup.sh --dev-parents --tests`.

Pure-analytics use (diversity / spectratype / usage) does not require MMseqs2; the model and
annotation paths do (via arda).

## License

GPL-3.0-or-later.
