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.0.0 pre-release under active development (latest: v2.0.0-alpha.2 — the native V(D)J model engine). Install a pre-release with pip install --pre vdjtools. 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
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; 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 (rolling out by phase — see ROADMAP.md)

  • Model — native V(D)J recombination model: generation probability (Pgen — nt, aa, 1-mismatch, V/J-agnostic), 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).
  • 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.

License

GPL-3.0-or-later.

Project links

Data verified by PyPI on Jul 12, 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 12, 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.1.0.tar.gz (668.2 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.1.0-cp313-cp313-win_amd64.whl (935.5 kB view details)

Uploaded CPython 3.13Windows x86-64

vdjtools-2.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (973.8 kB view details)

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

vdjtools-2.1.0-cp313-cp313-macosx_11_0_arm64.whl (935.9 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

vdjtools-2.1.0-cp312-cp312-win_amd64.whl (935.5 kB view details)

Uploaded CPython 3.12Windows x86-64

vdjtools-2.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (973.8 kB view details)

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

vdjtools-2.1.0-cp312-cp312-macosx_11_0_arm64.whl (935.2 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

vdjtools-2.1.0-cp311-cp311-win_amd64.whl (933.8 kB view details)

Uploaded CPython 3.11Windows x86-64

vdjtools-2.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (975.1 kB view details)

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

vdjtools-2.1.0-cp311-cp311-macosx_11_0_arm64.whl (934.1 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

vdjtools-2.1.0-cp310-cp310-win_amd64.whl (932.5 kB view details)

Uploaded CPython 3.10Windows x86-64

vdjtools-2.1.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (974.6 kB view details)

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

vdjtools-2.1.0-cp310-cp310-macosx_11_0_arm64.whl (932.6 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

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

File metadata

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

File hashes

Hashes for vdjtools-2.1.0.tar.gz
Algorithm Hash digest
SHA256 395bda3e1f5f4ba922bab6a7d9f41960fccd50429e395efc0be4aadffa4afb93
MD5 ece4b10d33473a987394d63aa561325c
BLAKE2b-256 b0875fe6a2fd2c02bf83af04d7a7b38cbf936c468a3d8e3c18e9a678621361fa

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.1.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.1.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: vdjtools-2.1.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 935.5 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.1.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 d271def113f94c43149167926f1c4cd3fd994fe7469592d27d740030f754c73a
MD5 21440ed2e08cf970f03ba911a2e1eef8
BLAKE2b-256 728af3392d6ab27300da31e5eddd6dd79b80c8388e9b454098c743bb8daa897f

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.1.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.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vdjtools-2.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e90a2f4d7e4c1542069b70da05aff284be2f774e80d4e7d2d09c345bb64009f2
MD5 79fd72a1dc76e65ff405b57b564a9bc7
BLAKE2b-256 ac858af80174b5d378c3acc3d5d272eba9669adda4549f12d82559836453e30c

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.1.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.1.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vdjtools-2.1.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9b43de7adb7be2fc3263f00ddc31bea95fb2a5f7c4f989b462524e6f3828d476
MD5 85398dd8661bb6e2baab5b34951b16a9
BLAKE2b-256 325aa5ad10794bf86307c3025e9ae3e467f7670c9c461403d427ebe30f7f3cb1

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.1.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.1.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: vdjtools-2.1.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 935.5 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.1.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 f66c1300dc56b9d355f1fd53cc57ea582f9a47b037fbe6063d29ada879a1ee42
MD5 958a5a9c158cef6a28fa907fd37548c9
BLAKE2b-256 41f3f31982b321945e0f714278510150678adb412b62dbe6802474e504d9cc09

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.1.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.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vdjtools-2.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 45d5e8f953829fe3e6f79cb6e19dc8cb03b72e2235c2d18be739abebf41196e8
MD5 3588cf51f7ed9906a7f9af21c96aa1dc
BLAKE2b-256 f2f0bb3542fc457257fa4d317dd13816aa5890e1b15b1d02fcf06a2983f64441

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.1.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.1.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vdjtools-2.1.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ba97405f4e84f0c1810fddafd5e99ea760c77e490a71e48564e4556d892d8032
MD5 14daacc08c73c7c40c97994385b641d5
BLAKE2b-256 1e1c6ca4f079000bb0e123c79a824faaa06fed945b9713e305cfac7518e35480

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.1.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.1.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: vdjtools-2.1.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 933.8 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.1.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 afcb12e2a729a49c1c4e481a3c3169ca1cf4c1f41e9c9b8e919c9daf963263ff
MD5 6570ce27d01dfdaebcc7bc802d169365
BLAKE2b-256 c61085d2cb19a9f0c6c39212fc297195124661ee2003dda8a3e723f44b40fae0

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.1.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.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vdjtools-2.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2cd6f0140aaeb5ff11963edb004068c0d645af0f6866fee4a172e0cfe806a6fd
MD5 a0ec268fdcc15b5c5f917164298f3c06
BLAKE2b-256 7b5280cc61be903086f8a6641786be7767cae9b4050621181156b15234d73690

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.1.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.1.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vdjtools-2.1.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4f055d2f5873cefe7e694715dd9193275ee3540bf236f2045507e7ff804607fb
MD5 beffc8a18386a1b53ae885653911b237
BLAKE2b-256 193e7141fde811825d5998966bdd171381df00c62854bcbdb111efe88eef97e6

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.1.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.1.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: vdjtools-2.1.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 932.5 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.1.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 d75a904dc10ca21e419b5d19fd106520976a950770612f756fceedd310500f13
MD5 04d82ae45facb1a712f3e7bba1c05594
BLAKE2b-256 38fbac674a837c8adcdd31f788d0437670f79906da5c7f76c1379652446977b9

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.1.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.1.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vdjtools-2.1.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d4c0c57c84d78e48f981c01d2616f2d063985874965ab86dd6f8aeaf547b30fe
MD5 8c211a9292ef007e410956b923e67655
BLAKE2b-256 77657464026a03c288e68de2d963bcede6f05d8d579fe67037a2bf2db149054f

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.1.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.1.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vdjtools-2.1.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 08de9f97a31c79ad300b33caa7e7ca1e4ee4f8d5dafb7316e08f4d1e87191868
MD5 0b2de65a0a702c3f8fdc9c72318420e6
BLAKE2b-256 52c6ad2562630387977be042ab3fc4d970e7da523269eff32cd0d8e6f5cf8cfe

See more details on using hashes here.

Provenance

The following attestation bundles were made for vdjtools-2.1.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

2.2.0

13 files

This release

2.1.0 This release

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