vdjtools

vdjtools — immune-repertoire analysis

PyPI CI docs python license

TCR/BCR immune-repertoire analysis — a clean-room Python + C++ rewrite of the legacy Groovy/Java vdjtools, standardised on the AIRR schema and polars DataFrames with minimal object-orientation.

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

Status: v2.2.0 — the native V(D)J model engine plus the full analytics suite (diversity, overlap/TCRnet, preprocessing, biomarkers, single-cell), CDR features, and legacy-format ingestion (MiXcr, MiGec, immunoSEQ, IMGT/HighV-QUEST, Vidjil, RTCR). Clonotype columns follow the AIRR junction convention (junction_nt / junction_aa). The legacy v1.x tool lives on the legacy-1.x branch and its releases remain available under the repository tags (v0.0.1 … 1.2.1).

Install

pip install vdjtools

Prebuilt wheels ship for CPython 3.10–3.13 on Linux, macOS (Apple Silicon), and Windows; the native _core C++ extension is bundled (the source distribution compiles it on install). The pure-analytics paths (diversity / spectratype / usage / overlap) work out of the box; the model and annotation paths additionally pull in arda (MMseqs2):

pip install "vdjtools[model]"

Development

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.

Quickstart — recombination model engine

Precomputed models for all 7 human loci ship in the wheel — no OLGA or download needed:

from vdjtools.model import load_bundled, native
from vdjtools.model.generate import generate

model = load_bundled("TRB", source="olga")     # or source="learned" (fit to real repertoires)

native.pgen_nt(model, "TGTGCCAGCAGC...")        # nucleotide generation probability (native C++)
native.pgen_aa(model, "CASSLAPGATNEKLFF")       # amino-acid Pgen (codon-marginalised)
native.pgen_aa(model, "CASSLAPGATNEKLFF", mismatches=1)   # + the whole Hamming-1 ball
native.pgen_aa_batch(model, seqs, mismatches=1, threads=0)  # Pgen over many CDR3s, thread-parallel (~11×)
generate(model, 1000)                           # sample a repertoire -> polars DataFrame

Matches OLGA's Pgen to machine precision across all 7 loci, and adds tandem-D (D-D) support that OLGA/IGoR lack. Learn a model from your own out-of-frame reads with model.infer.infer_native.

Explore any model's recombination Bayes net interactively (entropy, mutual information, marginals):

pip install "vdjtools[examples]"
marimo edit notebooks/model_explorer.py

Command line

pip install vdjtools installs the vdjtools command — the model engine (OLGA/IGoR-style) and the repertoire analytics (over sample files or a metadata table, like the legacy tool):

# recombination model engine — built-in models for all 7 loci (no download)
vdjtools models                                # list the bundled models
vdjtools generate -m TRB -n 1000 -o gen.tsv    # sample sequences   (cf. olga-generate_sequences)
vdjtools pgen seqs.tsv -m TRB -o pgen.tsv      # Pgen per CDR3       (cf. olga-compute_pgen)
vdjtools pgen seqs.tsv -m TRB --mismatches 1   # + the Hamming-1 ball; --v-col/--j-col to condition

# repertoire analytics — sample files, or a cohort via -m/--metadata + --base-dir
vdjtools diversity      sampleA.tsv sampleB.tsv -o diversity.tsv
vdjtools overlap        *.tsv -o overlap.tsv
vdjtools segment-usage  *.tsv --segment v -o usage.tsv
vdjtools spectratype    *.tsv -o spectra.tsv

Native vdjtools and AIRR Rearrangement inputs are auto-detected; every command writes TSV to -o (or stdout, so it pipes). Run vdjtools <command> --help for options.

Performance

The Pgen / generation / EM / diversity hot paths are a native C++ (pybind11) core; everything else is polars. Amino-acid Pgen matches OLGA to machine precision (1e-15) across all 7 loci while being several times faster, and the built-in models keep the resident set small. Single thread, Apple M3 (arm64), bundled human TRB model:

operation throughput vs OLGA
nucleotide Pgen (single-D VDJ) ~0.5 ms/seq 9×
amino-acid Pgen ~0.6–0.9 ms/seq 8.6×
Pgen + Hamming-1 ball (1 substitution) ~15 ms/seq 8.7×
sequence generation ~32 000 seq/s —

Nucleotide Pgen (via the same transfer-matrix DP as the aa path — an in-frame CDR3 is an aa query with one codon fixed per position) is exact vs OLGA across all loci. Batched Pgen / 1-mismatch over many CDR3s parallelises over sequences (native.pgen_aa_batch, ~11× on 16 cores, bitwise-identical to the serial result); the EM E-step parallelises over reads (~6.7× on 8 threads); diversity/rarefaction run on a native iNEXT kernel (bootstrap + parallel batch). Memory stays light — ~63 MB resident for import vdjtools plus one loaded model, ~123 MB with all seven bundled models resident. Reproduce with appendix/bench_pgen.py and the test_*_benchmark.py suites (RUN_BENCHMARK=1).

Capabilities (see ROADMAP.md and the API reference)

  • IO — canonical clonotype frame on AIRR junction columns (junction_nt / junction_aa); readers for native vdjtools, AIRR Rearrangement TSV, and Parquet, plus format-detecting converters for MiXcr (v1/2 + v3/4), MiGec, Adaptive immunoSEQ (v1/v2), IMGT/HighV-QUEST, Vidjil, and RTCR (vdjtools.io.convert); metadata-driven batch + hive-partitioned cohorts.
  • Model — native V(D)J recombination model: generation probability (Pgen — nt, aa, 1-mismatch, V/J-agnostic, thread-parallel batch), sequence generation, and EM inference, all in a native (pybind11) core. Supersedes OLGA and IGoR: arda-driven scenario enumeration, polars marginal tables, read-parallelised EM, and tandem-D (D-D) support. Concordant with OLGA across all 7 loci; precomputed OLGA + real-data-learned models bundled (load_bundled).
  • 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), similarity-aware overlap, clustering.
  • 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, chain pairing + QC, and paired α/β Pgen.

License

GPL-3.0-or-later.

Project links

Data verified by PyPI on Jul 13, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (3.10.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for mikessh from gravatar.com mikessh

Credits

Author: Mikhail Shugay

GitHub Statistics

Data verified by PyPI on Jul 13, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GNU General Public License v3 or later (GPLv3+) (GPL-3.0-or-later)

Requires

Python >=3.10

Provides Extra

model overlap preprocess sc examples oracle test bench docs dev all

Tags

immunology tcr bcr airr repertoire pgen olga igor bioinformatics

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vdjtools-2.2.0.tar.gz (681.3 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

vdjtools-2.2.0-cp313-cp313-win_amd64.whl (949.1 kB view details)

Uploaded CPython 3.13Windows x86-64

vdjtools-2.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (989.1 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

vdjtools-2.2.0-cp313-cp313-macosx_11_0_arm64.whl (947.4 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

vdjtools-2.2.0-cp312-cp312-win_amd64.whl (949.1 kB view details)

Uploaded CPython 3.12Windows x86-64

vdjtools-2.2.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (988.9 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

vdjtools-2.2.0-cp312-cp312-macosx_11_0_arm64.whl (947.0 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

vdjtools-2.2.0-cp311-cp311-win_amd64.whl (947.5 kB view details)

Uploaded CPython 3.11Windows x86-64

vdjtools-2.2.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (990.4 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

vdjtools-2.2.0-cp311-cp311-macosx_11_0_arm64.whl (945.8 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

vdjtools-2.2.0-cp310-cp310-win_amd64.whl (946.2 kB view details)

Uploaded CPython 3.10Windows x86-64

vdjtools-2.2.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (990.0 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

vdjtools-2.2.0-cp310-cp310-macosx_11_0_arm64.whl (943.7 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

Details for the file vdjtools-2.2.0.tar.gz.

File metadata

  • Download URL: vdjtools-2.2.0.tar.gz
  • Upload date:
  • Size: 681.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for vdjtools-2.2.0.tar.gz
Algorithm Hash digest
SHA256 3945882326884f0a977ad8ea9d0226a4ff3f6f837be852a88c2bee3690ab85b8
MD5 a129068d8c1a9741aaf7ea3a6f9c62a0
BLAKE2b-256 2ab3ac8a3eab0e825a1cfee980a959c87ec51a9b52a7e513c9b8d435650d4ae1

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.2.0.tar.gz:

Publisher: publish.yml on antigenomics/vdjtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vdjtools-2.2.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: vdjtools-2.2.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 949.1 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for vdjtools-2.2.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 ae2be917d62d871e5b7cd30757af4e13fae22b9acdb5a28602828745a1650e00
MD5 2d8c4ba8241e8f2c646b5c90793fa083
BLAKE2b-256 940698926a37398edc25afff7ad75f0abb2de358c7cbfe21c442c6f787f12134

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.2.0-cp313-cp313-win_amd64.whl:

Publisher: publish.yml on antigenomics/vdjtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vdjtools-2.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vdjtools-2.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 8691465bee015654781a9a83e9940e295cd193efec791ceee0b496dbf9bfef1d
MD5 03228d09312ab0685fc0c3ddf0c0d452
BLAKE2b-256 3d46953f83a84602718b05ec8da8af73a1be5b1f5960c0ceac0f70a5c05caa1f

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on antigenomics/vdjtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vdjtools-2.2.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vdjtools-2.2.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b0d73c6834f6af8c6f3eb08f7ce2d5581644f5541a8cb7840dbc25bcfe1b8758
MD5 b51a00c332d9f8f709f3142aeda03b9a
BLAKE2b-256 9eb1c63df99584289817b11d1e231548941e813bf8f130787f13ee17ff882b32

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.2.0-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: publish.yml on antigenomics/vdjtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vdjtools-2.2.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: vdjtools-2.2.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 949.1 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for vdjtools-2.2.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 56da962f5fd14b61fbe57aba06458a74c1fe1616e3f1cfaaac03e0790b6cacc1
MD5 c1649d4a758f85f159ae2116e919b2f8
BLAKE2b-256 26ba71efbba03324b1a34524118283606755343829af9db66b659a1384503fc7

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.2.0-cp312-cp312-win_amd64.whl:

Publisher: publish.yml on antigenomics/vdjtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vdjtools-2.2.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vdjtools-2.2.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 c912892c6ed7dcd229dee1d2e404287f72af300c15d934ebf7dedc0c29a5d321
MD5 edfa982b784126ac91ecb7d4026457c3
BLAKE2b-256 d628750f0c7dd449118ad1047d4a72bb13e7fa3b7a17cbe8a6f1605024b1006e

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.2.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on antigenomics/vdjtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vdjtools-2.2.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vdjtools-2.2.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0c6a48e4a93c1e9ddce768b2caddc771b683d5320dfe29a3ad28960644c45ea2
MD5 00129bed8f74df70c925ac9e4f126cca
BLAKE2b-256 4784d86d569ee5682b2de1c2dce60441c31470aa5f6a26007aa2685fb7c83db3

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.2.0-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: publish.yml on antigenomics/vdjtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vdjtools-2.2.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: vdjtools-2.2.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 947.5 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for vdjtools-2.2.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 6eff7ce10e6987ce8e85f867092c5fcf6579f406964288860a6e1ce291da9b38
MD5 ebd88fb2e47c4eafb80826e145ecef0a
BLAKE2b-256 141ee382ea8b3271ff7a0f9b631111b0eb8c4d47e9688f92a9c8b0aca15ef8e0

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.2.0-cp311-cp311-win_amd64.whl:

Publisher: publish.yml on antigenomics/vdjtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vdjtools-2.2.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vdjtools-2.2.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 c95a902a3ec2a7548665e2a89d4c1f48d5b8aa1b98c7df1023d925a3576081e6
MD5 bf0d93161bb3ec683b51549092f627c5
BLAKE2b-256 75ce74c769ccf789985c6365c3bae04cc103e58b0f7a05e569928fb01009c335

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.2.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on antigenomics/vdjtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vdjtools-2.2.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vdjtools-2.2.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 880d5378f0a772429af956139154d3f7e74a5c4e4d02addbb69de667a5e70af9
MD5 e04fc059e19039333db8428a51ae0446
BLAKE2b-256 b4a32f9b5618459e58a29b8997dd512b0ef312d0e618621eb3d337c5da095f3e

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.2.0-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: publish.yml on antigenomics/vdjtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vdjtools-2.2.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: vdjtools-2.2.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 946.2 kB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for vdjtools-2.2.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 14b9258500b321a2a1ac833c6e606912e42c51a09ed76563c4b1304f7153e69f
MD5 f9af20212eb2e94bb98fe8cfc61382ab
BLAKE2b-256 6aa42e9e0d49c37355b428fa3ab2d1d1c13f0d931e612c6cb431bc3cb9f58eee

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.2.0-cp310-cp310-win_amd64.whl:

Publisher: publish.yml on antigenomics/vdjtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vdjtools-2.2.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vdjtools-2.2.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 0048af207358f48b3d7d256873505c9c01e7d1839579b7fe038e0267719b4367
MD5 f35b5589ce8dc9bc850486253c25c049
BLAKE2b-256 bd40d668d06c02f895a966de7408944581599df313aacbc12278327508b95ff6

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.2.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on antigenomics/vdjtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vdjtools-2.2.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vdjtools-2.2.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a95754403e399dcc680d7a4bbc120932b75dc8c1ee63726c491b0f27dcedf3db
MD5 6f4434972775bfb38d0d906eacd30c78
BLAKE2b-256 ac3b757f8283c909cebe195b356d51a57cdb9159da116c429969c78a2792ccf7

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.2.0-cp310-cp310-macosx_11_0_arm64.whl:

Publisher: publish.yml on antigenomics/vdjtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

3.10.0

13 files

3.9.3

13 files

3.9.2

13 files

3.9.1

13 files

3.9.0

13 files

3.8.0

13 files

3.7.3

13 files

3.7.0

13 files

3.6.1

13 files

3.6.0

13 files

3.4.0

13 files

3.2.0

13 files

3.1.2

13 files

3.1.1

13 files

3.1.0

13 files

3.0.0

13 files

2.9.0

13 files

2.8.0

13 files

2.7.0

13 files

2.6.0

13 files

2.5.1

13 files

2.3.0

13 files

2.2.1

13 files

This release

2.2.0 This release

13 files

2.1.0

13 files

2.0.0

13 files

Pre-release

2.0.0a2

13 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page