Skip to main content

vdjtools

vdjtools — immune-repertoire analysis

PyPI CI docs python license

Get started · Guides · Commands · API · Examples · Glossary

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

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.

Quickstart

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")
vdjtools diversity samples/*.tsv -o diversity.tsv
vdjtools features samples/*.tsv --coverage 0.8 --threads 0 -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/arcsine 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.

For large new sequence draws, select the native sampler and its allocated CPU budget:

vdjtools generate -m TRB -n 10000 --engine native --threads 0 --seed 7 -o generated.tsv

Native draws are identical across thread counts. The default reference sampler preserves historical seeded draws; the two engines use different random streams.

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

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 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
Filter, correct, downsample or pool Pre-processing
Diversity, overlap, gene usage, biomarkers and dynamics User guide
Unrotated features and optional sample PCA Raw features
Published vsig/rsig corpus coordinates Signatures · Methods · Channels
Pgen, generation and model fitting Model workshop
Single-cell data and interoperability Single cell
Functions, flags, examples and terms API · Commands · Examples · Glossary

Recorded performance measurements and model validation 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 still grows with sample count and feature width. Configured randomized corpus fits and TablePCA.fit_features use sparse rows and bounded statistic chunks; their remaining workspace grows with nonzero entries and the requested component count. See CPU/container limits. For file-backed Python-heavy summaries, select --backend process (or io.map_samples(..., backend="process")) to use coarse sample batches. The default thread backend shares resources and supports closures; process startup can dominate small cohorts.

Development

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. The VDJtrack recapture model in vdjtools.dynamics is Pavlova, Zvyagin and Shugay (2024).

License

ISALGO LAB Academic and Non-Commercial Research License. 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.

Configurable statistical features

Opt-in basic uses diversity, V–J usage, junction-length spectratype and separate isotype composition; joint uses diversity, V–J–length usage and separate isotype. Their extended variants add IMGT11 or frozen BLOSUM62 motifs (XXX, XX_X, X_XX), with optional gene or clustered V context. Existing feature/signature defaults stay legacy. See features and corpus fitting for fit/save/apply and the distinction between an available definition and a published rotation.

Public recombination models, corpus bundles and example sources are mirrored on Hugging Face. The dataset card shows selective downloads; downloading the whole mirror is unnecessary.

Metadata

Release files for vdjtools 5.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vdjtools 5.3.2
File Size Uploaded Provenance Actions
vdjtools-5.3.2.tar.gz 1.5 MB With provenance Details for vdjtools-5.3.2.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for vdjtools 5.3.2
File Actions
vdjtools-5.3.2-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details for vdjtools-5.3.2-cp313-cp313-win_amd64.whl
vdjtools-5.3.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for vdjtools-5.3.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
vdjtools-5.3.2-cp313-cp313-macosx_11_0_arm64.whl CPython 3.13 CPython 3.13 macOS 11.0+ ARM64 Details for vdjtools-5.3.2-cp313-cp313-macosx_11_0_arm64.whl
vdjtools-5.3.2-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for vdjtools-5.3.2-cp312-cp312-win_amd64.whl
vdjtools-5.3.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for vdjtools-5.3.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
vdjtools-5.3.2-cp312-cp312-macosx_11_0_arm64.whl CPython 3.12 CPython 3.12 macOS 11.0+ ARM64 Details for vdjtools-5.3.2-cp312-cp312-macosx_11_0_arm64.whl
vdjtools-5.3.2-cp311-cp311-win_amd64.whl CPython 3.11 CPython 3.11 Windows x86-64 Details for vdjtools-5.3.2-cp311-cp311-win_amd64.whl
vdjtools-5.3.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details for vdjtools-5.3.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
vdjtools-5.3.2-cp311-cp311-macosx_11_0_arm64.whl CPython 3.11 CPython 3.11 macOS 11.0+ ARM64 Details for vdjtools-5.3.2-cp311-cp311-macosx_11_0_arm64.whl
vdjtools-5.3.2-cp310-cp310-win_amd64.whl CPython 3.10 CPython 3.10 Windows x86-64 Details for vdjtools-5.3.2-cp310-cp310-win_amd64.whl
vdjtools-5.3.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details for vdjtools-5.3.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
vdjtools-5.3.2-cp310-cp310-macosx_11_0_arm64.whl CPython 3.10 CPython 3.10 macOS 11.0+ ARM64 Details for vdjtools-5.3.2-cp310-cp310-macosx_11_0_arm64.whl

Total release size: 25.5 MB

Release files / vdjtools-5.3.2.tar.gz

Download URL vdjtools-5.3.2.tar.gz
Size 1.5 MB
Tags Source
SHA-256 checksum
How to use checksums
cdf8c730f6a4d3b7d7f76fd077d2689446af75490c068b7e4d38d430b5dec0cf
BLAKE2b-256 checksum
How to use checksums
ed4e200516370389fe809314b34f0f41b3c5be153d2e3be67e676c199e0efdcd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Release files / vdjtools-5.3.2-cp313-cp313-win_amd64.whl

Download URL vdjtools-5.3.2-cp313-cp313-win_amd64.whl
Size 2.0 MB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
4d60b0f0d1a02a6a4c855e411230221549ce2dc70221655075342e7766adf7ea
BLAKE2b-256 checksum
How to use checksums
cc72b91bee4d0f19ceb5c877d45f47b8bf77cc6086a8e7853ed3378d79601716
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Release files / vdjtools-5.3.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL vdjtools-5.3.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 2.0 MB
Tags CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
60dd691688cb0d5beb07ce62b597e4d755fdd0cf43fb3fcf6996ecd206903681
BLAKE2b-256 checksum
How to use checksums
799dbcf4d5f618661cfe6001466924b885566d0555bf63e335f2bc79b82aa144
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Release files / vdjtools-5.3.2-cp313-cp313-macosx_11_0_arm64.whl

Download URL vdjtools-5.3.2-cp313-cp313-macosx_11_0_arm64.whl
Size 2.0 MB
Tags CPython 3.13 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
a23ff5c22d397cf75cd9f0667d8e4e82ae5425e821b724d77431183a111e6c4b
BLAKE2b-256 checksum
How to use checksums
9de8c7c2c1bbc227bdc0f30185fccd2db5ba852df62dfe1866f97e954f7f512f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Release files / vdjtools-5.3.2-cp312-cp312-win_amd64.whl

Download URL vdjtools-5.3.2-cp312-cp312-win_amd64.whl
Size 2.0 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
7493bb7044abcc594e73678998b0360b9f1d72216b4662a5407e049ae8f09a50
BLAKE2b-256 checksum
How to use checksums
dff1fc007abb62ca921d0e4d039573c7f04597d28dd9afd48bd4f21be809a5b8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Release files / vdjtools-5.3.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL vdjtools-5.3.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 2.0 MB
Tags CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
6b4670e74c008fca92b4d1d584717f82706546bff72eb186bd40ffbe98bdf2db
BLAKE2b-256 checksum
How to use checksums
a04900e580e8eddabb5cbf4231286f2541c415785a5b6b3f2be17c864c121db3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Release files / vdjtools-5.3.2-cp312-cp312-macosx_11_0_arm64.whl

Download URL vdjtools-5.3.2-cp312-cp312-macosx_11_0_arm64.whl
Size 2.0 MB
Tags CPython 3.12 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
bbafdeba7aa5484e7e7284d1584ef0906dd8abd84824925ddc6900a3cf672edb
BLAKE2b-256 checksum
How to use checksums
52b4c27bf514b5e9264d17bde9ed6c0880b52dcddc2dc6999b08ad99f0a6decf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Release files / vdjtools-5.3.2-cp311-cp311-win_amd64.whl

Download URL vdjtools-5.3.2-cp311-cp311-win_amd64.whl
Size 2.0 MB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
a2b06c0ec5b8a8f6348db098f2d33fe26a48cbc32ba05281c3d65638de8492a0
BLAKE2b-256 checksum
How to use checksums
01351b143b7f28533d888a7f260fb4de989b1c2ec6082c0f4ca16a5984b6ccd6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Release files / vdjtools-5.3.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL vdjtools-5.3.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 2.0 MB
Tags CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
e20d96ecce6a56647d1e3e66c8181e58144a39cf0e6f5f5ff49beac67d9555e4
BLAKE2b-256 checksum
How to use checksums
cffaf01b577c6e9c8f1e169b1b07fb57208dbaa4d1594b7cdcb083ca8b910a2e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Release files / vdjtools-5.3.2-cp311-cp311-macosx_11_0_arm64.whl

Download URL vdjtools-5.3.2-cp311-cp311-macosx_11_0_arm64.whl
Size 2.0 MB
Tags CPython 3.11 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
1aa7df4c3c905eac67ecb2f79405b62001454a4fc297ce104863d2671c54c940
BLAKE2b-256 checksum
How to use checksums
80b9f20204fdb1a5ca0832c82d34a885779b7bc69c2a98a7d4463b3db7a0c93f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Release files / vdjtools-5.3.2-cp310-cp310-win_amd64.whl

Download URL vdjtools-5.3.2-cp310-cp310-win_amd64.whl
Size 2.0 MB
Tags CPython 3.10 Windows x86-64
SHA-256 checksum
How to use checksums
f3433b0396ab0803448ae56ce0f61dd07a5b13196a3afa24f5bf900ea01e6874
BLAKE2b-256 checksum
How to use checksums
c9296e27ef63c805c3d13689a64568387be55435e3ad6a40ff24f7a5e636dcfa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Release files / vdjtools-5.3.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL vdjtools-5.3.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 2.0 MB
Tags CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
6b5ecec8efc40ba9d41d97b5f786e0223ac998c83e548cbadc8036b5bd03d33e
BLAKE2b-256 checksum
How to use checksums
da57b0edfaf2764088ba8d4bc3d8de5ac512abe91a1ed582a6ddde8b92ea8490
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Release files / vdjtools-5.3.2-cp310-cp310-macosx_11_0_arm64.whl

Download URL vdjtools-5.3.2-cp310-cp310-macosx_11_0_arm64.whl
Size 2.0 MB
Tags CPython 3.10 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
0e406ca58f7c605b0e9cd34711e882aec5cdb3dfd6da12857ac6d2f5125238b1
BLAKE2b-256 checksum
How to use checksums
cc653e2a722c18f41950db12c0518e26794d3554d0506d7389edbd1f90e37fe2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Security for vdjtools 5.3.2

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.

Full provenance

All 13 files in this release have been uploaded with provenance metadata.

Select from 13 files

Attestation for vdjtools-5.3.2.tar.gz

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 Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

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