vdjtools — immune-repertoire analysis
Get started · Guides · Commands · API · Examples · Glossary
Analysis of T- and B-cell receptor repertoire sequencing: read any format, measure diversity and overlap, correct batch effects, score generation probability against a native V(D)J model, and reduce a whole repertoire to one comparable feature vector.
vdjtools reads the output of every common repertoire pipeline into one canonical AIRR table backed by polars, and every analysis takes and returns that same table — so results chain together instead of needing a converter between each step.
A clean-room Python + C++ rewrite of the Groovy/Java vdjtools, built on arda (germline reference and annotation), seqtree (fuzzy search and e-values) and vdjmatch (overlap and TCRnet).
Install
pip install vdjtools
That is the whole installation — every capability below works from it, with no extras to opt into.
Wheels are prebuilt for CPython 3.10–3.13 on Linux, macOS (Apple Silicon) and Windows and include
the native C++ extension; a source install compiles it. The three engines above are base
dependencies, imported lazily so import vdjtools stays light.
Two optional extras exist because each has a working alternative:
pip install "vdjtools[overlap]" # scikit-learn, for cluster_samples(method="mds")
pip install "vdjtools[sc]" # single-cell bridges: anndata, awkward, mudata, pyyaml
Quickstart
from vdjtools import io as vio, stats, overlap
sample = vio.read("clones.tsv") # MiXcr, immunoSEQ, AIRR, Parquet, native — detected
stats.diversity_stats(sample) # richness, Chao1, Shannon, inverse Simpson, d50
stats.segment_usage(sample, "v") # V-gene usage
cohort = vio.read_samples(vio.read_metadata("metadata.txt"), base_dir="samples/")
overlap.overlap_matrix(cohort) # pairwise repertoire overlap
The same thing with no Python:
vdjtools diversity sampleA.tsv sampleB.tsv -o diversity.tsv
vdjtools segment-usage *.tsv --segment v -o usage.tsv
vdjtools overlap *.tsv -o overlap.tsv
Every command writes to -o — TSV, or Parquet when the path ends in .parquet / .pq — or to
stdout, so commands pipe. Analysis commands also take a metadata table (-m plus --base-dir) and
parallelise over samples with -t/--threads.
Getting started walks through this in about ten minutes, with no data to download.
Where to start
| You want to | Go to |
|---|---|
| Get a first result from a file you already have | Getting started |
| Clean, filter, downsample or batch-correct a cohort | Pre-processing |
| Measure diversity, overlap, gene usage, spectratype | Guides |
| Score Pgen, or fit a model to your own reads | Model workshop |
| Reduce each sample to one feature vector for a classifier | Signatures |
| Work with 10x data, or hand off to scirpy / dandelion | Single cell |
| Look up a command or a function | Commands · API |
| Check what a term means | Glossary |
What is in the box
| Module | What it does |
|---|---|
vdjtools.io |
Readers for native vdjtools, AIRR Rearrangement TSV and Parquet; format-detecting converters for MiXcr, MiGec, Adaptive immunoSEQ, IMGT/HighV-QUEST, Vidjil, RTCR, TRUST4 and arda; metadata-driven batches and hive-partitioned cohorts |
vdjtools.stats |
Diversity (richness, Chao1, Efron-Thisted, Shannon, Simpson, d50), coverage-based Hill-number rarefaction with bootstrap intervals, spectratype, V/D/J/C usage |
vdjtools.model |
Native V(D)J recombination model: Pgen over nucleotides and amino acids, the Hamming-1 ball, sequence generation, EM inference, tandem-D support, and a 13-command model workshop |
vdjtools.overlap |
Exact and similarity-aware repertoire overlap, TCRnet and ALICE neighbourhood enrichment, sample clustering |
vdjtools.preprocess |
Format conversion, the three filtering axes, frequency handling, downsampling, error correction, V/J-usage batch correction, pooling and joining |
vdjtools.features |
Junction physicochemical profiles and k-mer summaries |
vdjtools.biomarker |
Incidence association against binary, per-HLA-allele or stratified conditions; co-occurrence pairing; metaclonotypes |
vdjtools.dynamics |
Longitudinal clonotype tracking: paired within-donor expansion testing, the VDJtrack recapture model, an edgeR NB-exact caller |
vdjtools.signature |
One fixed, named, already-standardised feature vector per repertoire, rotated through a published corpus |
vdjtools.sc |
Single-cell ingestion, chain pairing and QC, paired Pgen, round-trip interop with scirpy, dandelion and scRepertoire |
Recombination models, built in
Models for all seven human loci ship in the wheel — no OLGA install and nothing to download:
from vdjtools.model import load_bundled, native
model = load_bundled("TRB", source="olga") # or source="learned"
native.pgen_aa(model, "CASSLAPGATNEKLFF") # 3.595e-08
native.pgen_aa(model, "CASSLAPGATNEKLFF", mismatches=1) # and its whole Hamming-1 ball
Pgen agrees with OLGA to 1e-15 on every locus while being several times faster, and adds tandem-D support that OLGA and IGoR lack. You can also fit a model to your own non-productive reads, audit it against its germline, compare two models parameter by parameter, and render its recombination Bayes net — see the model workshop.
Signatures
One repertoire in, one fixed-width named feature vector out, standardised against a published reference corpus so your matrix and a collaborator's are in the same coordinate system without either of you fitting a scaler:
vdjtools signature --corpus blood samples/*.tsv.gz -o vsig.tsv
mir signature --corpus blood samples/*.tsv.gz -o rsig.tsv # the geometry half, from mirpy
Nine corpora are published, all at 256 components per locus. blood (11,117 real samples, 947 study
groups), tissue (21,131 / 1,934) and deep-tcr (3,936 amplicon samples, TRA+TRB) are fitted on
real repertoires; the synthetic ones need no cohort at all and rebuild byte for byte anywhere.
Artifacts are fetched and digest-verified on first use rather than bundled.
--corpus is required: a signature is comparable to another one only if both were rotated through
the same corpus, and nothing about the numbers would say otherwise.
Signatures ·
How they were fitted ·
Channels
Performance
The Pgen, generation, EM and diversity hot paths are a native C++ core reached through pybind11; everything else is polars. Single thread, Apple M3, 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× |
| Amino-acid Pgen over the Hamming-1 ball | 15 ms/seq | 8.7× |
| Sequence generation, raw draws | 32,100 seq/s | — |
Sequence generation, productive_only=True |
8,960 seq/s | — |
The productive filter costs 3.6× on TRB and 5.1× on IGH (19,900 raw draws/s against 3,930
productive), because out-of-frame and stop-codon draws are discarded and redrawn. Batched Pgen
parallelises over sequences (11× on 16 cores, and identical to the serial result); the EM E-step parallelises
over reads (6.7× on 8 threads). Memory: 63 MB resident for import vdjtools plus one model, 123 MB
with all seven loaded.
Reproduce the in-repo half with RUN_BENCHMARK=1 pytest tests/python -k benchmark.
Development
Uses uv — one repo-local .venv, no conda:
uv venv && source .venv/bin/activate
uv pip install -e ".[dev,test]" # builds the _core C++ extension
pytest tests/python -q
bash setup.sh --dev-parents --tests does the same and editable-installs sibling checkouts of
seqtree, arda and vdjmatch if present. You need a C++ toolchain (Xcode Command Line Tools on macOS,
build-essential on Linux). MMseqs2 is needed only for arda's annotation path.
Citing
For the v2 rewrite, cite this repository. For the original tool, cite
Shugay et al., PLoS Computational Biology 2015.
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 branch, with its releases
under the repository tags v0.0.1 … 1.2.1.
1 maintainer
Metadata
1 maintainer
Release files for vdjtools 4.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| vdjtools-4.5.0.tar.gz | 1.5 MB | Details |
Built distributions (wheels)
Total release size: 23.8 MB
Release files / vdjtools-4.5.0.tar.gz
| Download URL | vdjtools-4.5.0.tar.gz |
|---|---|
| Size | 1.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
56f1e05cac43eb236a03a609fd53e2d0f32a624e969c7baf3cdbd8aed9c2d6b8
|
|
BLAKE2b-256 checksum How to use checksums |
1cd6c50d40f9f3b7449fc8691a9d903792df016ee928b2a4c1f534cf8f862030
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / vdjtools-4.5.0-cp313-cp313-win_amd64.whl
| Download URL | vdjtools-4.5.0-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
ef0f1f13727d2b1772b8208ccc4da46daa910f2d1d1d865cd5b82eb943975251
|
|
BLAKE2b-256 checksum How to use checksums |
2706fd8018fd8fcf554bbab321ac2f83cda5f02deb7ac5ff0eb0e2784b521aa1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / vdjtools-4.5.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | vdjtools-4.5.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.9 MB |
| Tags | CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
ae3c403b8767ab30170d85235f4a38dc9028513aa45755284129a3006f9582c0
|
|
BLAKE2b-256 checksum How to use checksums |
df23a82ab1c04abb0ad9df30769eeccc9d9e331751aefe1a7f42d9c3126819e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / vdjtools-4.5.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | vdjtools-4.5.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
a47283f495e68c6e4816bc4f8c06ed3a5dd567dbbbf171cd32abc9f314c5c6a1
|
|
BLAKE2b-256 checksum How to use checksums |
96fc1d075ceca42d4852e0aa2af8eff32cc092963534c41f67b2972108568dac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / vdjtools-4.5.0-cp312-cp312-win_amd64.whl
| Download URL | vdjtools-4.5.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
615fe7a37c26fe03c280164df21fcf205a7660b6d847a6fa50613558525f04f5
|
|
BLAKE2b-256 checksum How to use checksums |
33e02112623131cf1e2b9171e05fe35e9919aa48b9c0048e3b645b1ff7ca232f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / vdjtools-4.5.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | vdjtools-4.5.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.9 MB |
| Tags | CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
8e14d2664f0100ab6f6bc3820f5e65abc1c4a709492016f0459c67428cfac6eb
|
|
BLAKE2b-256 checksum How to use checksums |
1b35966f48747cf44a069046eafce5279d2666da8dad48ade59fc4ec16830b77
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / vdjtools-4.5.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | vdjtools-4.5.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
33cbb6dc248646854526250011bbc18285d0b092e4c31464796dc584e49d3c68
|
|
BLAKE2b-256 checksum How to use checksums |
87250f26634a336ce01b8fdf3755903a6d13f1cd2d2de0e47bc2f0a1c7fcf748
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / vdjtools-4.5.0-cp311-cp311-win_amd64.whl
| Download URL | vdjtools-4.5.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
273dc10bb7ed3d7168cc930579798395d74587d2c6258034df2bfb2829310aa4
|
|
BLAKE2b-256 checksum How to use checksums |
41370cf5d4734593e7b20e6426e6d336734cc77814f8ba7aeaf5f5baf429acf8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / vdjtools-4.5.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | vdjtools-4.5.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.9 MB |
| Tags | CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
c8a552217d8dadc032023083eb78d9df93944654e7949a05e11de42bc4e1d4bf
|
|
BLAKE2b-256 checksum How to use checksums |
12a2e7b4984e2f49bd492de4a9a8fbc36a8bc1993ed04943f222eedebb7b941e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / vdjtools-4.5.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | vdjtools-4.5.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
ba4baaee52a035066073db49c765bf3efb876895370b5f5ae9395cda819d17d2
|
|
BLAKE2b-256 checksum How to use checksums |
290f3d42134f2dfba9624ef1a3045a80fbfd7bb2f26a403e30c0ec3a72ac57ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / vdjtools-4.5.0-cp310-cp310-win_amd64.whl
| Download URL | vdjtools-4.5.0-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
3029ac0261b9161f29d4877bb40a0e1ddf6688c6eedd0ce80550f343006a1101
|
|
BLAKE2b-256 checksum How to use checksums |
e73ae575d4eb774304322317a1c943a23292aea40d1ba52d4049c121108f202a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / vdjtools-4.5.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | vdjtools-4.5.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.9 MB |
| Tags | CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
fb619d19aee099b90730e7d73ef4e83b8f718a1393ec6a1073744c3e8bf3bfaf
|
|
BLAKE2b-256 checksum How to use checksums |
1a6500df2c36fedb899c2b309240adbe0b4f335c4d87e3007985fbc9f3af2854
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / vdjtools-4.5.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | vdjtools-4.5.0-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d4bd7e2e9779b80f1a03edd31ad51d017a8023cae1058cd20d102993db7156da
|
|
BLAKE2b-256 checksum How to use checksums |
71f242548f2bbe01545d10aff309b51561e2d34253a793cb091e2cc27a195839
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency log
