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.

Working model APIs and CLIs default to isalgo, targeting seven human loci and mouse TRA/TRB/IGH/IGK/IGL. All twelve fitted models ship in the package; see the validation table for exact Pgen support and fixed-model observation likelihood. olga-legacy selects frozen OLGA models (olga is its alias). learned and arda alias fresh isalgo; their previous parameter families require a pinned previous release.

Metadata

Release files for vdjtools 5.4.0

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.4.0
File Size Uploaded Provenance Actions
vdjtools-5.4.0.tar.gz 1.8 MB With provenance Details for vdjtools-5.4.0.tar.gz

Built distributions (wheels)

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

Total release size: 28.7 MB

Release files / vdjtools-5.4.0.tar.gz

Download URL vdjtools-5.4.0.tar.gz
Size 1.8 MB
Tags Source
SHA-256 checksum
How to use checksums
d2178d66da9009915c5c0c4eed291dbacb8d70d95bc6836528dcfb4355f458d5
BLAKE2b-256 checksum
How to use checksums
bf6e63e3553a2ab4011c8e6a7edf677c8c3d2a3f221cce94f65c23fa0d9e1eaf
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 30, 2026.

Transparency log

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

Download URL vdjtools-5.4.0-cp313-cp313-win_amd64.whl
Size 2.2 MB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
dfcda4d7dc052304c48742a0d1f27420b03d2b4dbace36a8d9b7aecf521b1493
BLAKE2b-256 checksum
How to use checksums
4e5948206b1c88a213c7315f21569562b4c0beb013938844ff413345d621fb1a
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 30, 2026.

Transparency log

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

Download URL vdjtools-5.4.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 2.3 MB
Tags CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
653f27e82a7f6be8f331dfbeee4bf6938ba3695d21386b26a50f8d4533f9713e
BLAKE2b-256 checksum
How to use checksums
378afcdc264606b109fc95b45cc5a5ee6a74bddc27bc17d6c1e4cbff1abad1a8
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 30, 2026.

Transparency log

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

Download URL vdjtools-5.4.0-cp313-cp313-macosx_11_0_arm64.whl
Size 2.2 MB
Tags CPython 3.13 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
569b9251a25d4d6e9bf70787c4320d37beec6b1a798bffd71629414fa4d8f5ec
BLAKE2b-256 checksum
How to use checksums
11d3bb57bf8bdd7b6b4067fb30e25ae346ea962cea3f89d11919a426f2f0fd3c
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 30, 2026.

Transparency log

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

Download URL vdjtools-5.4.0-cp312-cp312-win_amd64.whl
Size 2.2 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
981df37ff747e02c987e389c99f5518d0772d69324eb375b9ed1347de09b990e
BLAKE2b-256 checksum
How to use checksums
88c61ac1706d73398724768af3e109d3c2e71a2a039f127f7c5a52ebf87d8e37
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 30, 2026.

Transparency log

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

Download URL vdjtools-5.4.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 2.3 MB
Tags CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
59fbecb0291bdf060f8e0c3ff11a3e3825e76f5b253e5089b0f0280b5c6be075
BLAKE2b-256 checksum
How to use checksums
50d6b138168579103fd9ea224e9f9da0a77c8ee74eb19200a76ca958474c5d66
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 30, 2026.

Transparency log

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

Download URL vdjtools-5.4.0-cp312-cp312-macosx_11_0_arm64.whl
Size 2.2 MB
Tags CPython 3.12 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
b013653f400c30b6567fb0e2ab9d9951df82b32a21fe8077910b856e0ed5aa08
BLAKE2b-256 checksum
How to use checksums
66a4f039740dbc2e25311bfdda16dea81364e112873b57f806ecfec7fde94d32
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 30, 2026.

Transparency log

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

Download URL vdjtools-5.4.0-cp311-cp311-win_amd64.whl
Size 2.2 MB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
3a434db474f42f08232ddcd53813894b8abf86cd44fe0da2207caa2c70dbafaf
BLAKE2b-256 checksum
How to use checksums
5d9f156e4846b411d1c3ee9ee0e27d8ba694e641fe0f3d3dfecee83d9b9f3923
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 30, 2026.

Transparency log

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

Download URL vdjtools-5.4.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 2.3 MB
Tags CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
699dc1927863eb5897e0b56b29a62c092c9d8b56a8c419123737cb7440b8e150
BLAKE2b-256 checksum
How to use checksums
af2442e9a261ea75d3d07993adf4ae9c83875f0daa00c2e755af3edaa9ba0f73
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 30, 2026.

Transparency log

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

Download URL vdjtools-5.4.0-cp311-cp311-macosx_11_0_arm64.whl
Size 2.2 MB
Tags CPython 3.11 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
fd59779c9ac4635868ef6557e9d58a560ad0d26acc092c53e0df81ec74aaea1e
BLAKE2b-256 checksum
How to use checksums
c2fb58d0cf85f34eb6c9d419c85b6391501e205708c2c0190dda23703a690b48
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 30, 2026.

Transparency log

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

Download URL vdjtools-5.4.0-cp310-cp310-win_amd64.whl
Size 2.2 MB
Tags CPython 3.10 Windows x86-64
SHA-256 checksum
How to use checksums
ba59394cca94df04cbd217abd6fd1e689d3d2c9895c55d40c5018d49702d91a5
BLAKE2b-256 checksum
How to use checksums
1b239eab661089553c06f88f5fc9c1002f786d43740af311d1d05c634398e974
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 30, 2026.

Transparency log

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

Download URL vdjtools-5.4.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 2.3 MB
Tags CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
948aaff5ba5a420b50c61539d98998fdfd65d3612eb0a7bbf165f9d6d2b5930a
BLAKE2b-256 checksum
How to use checksums
a831a2ae412884c584551ec9247b6b0b095f08d67e04446cc2ba8d8fc6060568
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 30, 2026.

Transparency log

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

Download URL vdjtools-5.4.0-cp310-cp310-macosx_11_0_arm64.whl
Size 2.2 MB
Tags CPython 3.10 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
ee08123fc0d1db9c0b168bf3834cacfe76b843c604ce33c13fa2e9793fcf0016
BLAKE2b-256 checksum
How to use checksums
a858c2eee7a87812c394b530f7a2faf66f6b57614f7a04da10e5216b48cebb6f
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 30, 2026.

Transparency log

Security for vdjtools 5.4.0

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.4.0.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 30, 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