VDJDB: A curated database of T-cell receptor sequences of known antigen specificity

!Splash

VDJdb aggregates published information on T-cell receptor antigen specificity - the ability to recognize certain epitopes in certain MHC contexts - and curates it into a single repository.

Each observation links a receptor to a peptide-MHC complex and its experimental evidence. See terminology for the distinction between the epitope, MHC restriction and source organism.

Routine updates keep the database current, and a validation scheme standardizes how specificity is reported:

• All available information on the experimental setup used to identify an epitope-specific TCR

• Each record is also checked automatically against a database of V/J segment germline sequences,

This repository holds the submissions to the database and the build that validates, assembles and publishes it. chunks/ is the data, one file per publication; everything else is machinery.

Documentation

Start at VDJdb documentation:

• Tutorial: explore your first records.
• How-to guides: submit records,

• Reference: chunk format,

• Explanation: sequence repair,

Column tables, vocabularies and score rules are generated from the package declarations when the site builds. The summary dashboard follows the latest successful build on master; released downloads are dated snapshots.

For corpus checks, distinguish repeated source rows from assembled observations. The build removes duplicate curation within a publication and preserves distinct experiments. See metadata and reference checks.

Using the data

Download the latest release zip from the releases page. A web GUI is at vdjdb.com, served by VDJdb-web.

vdjmatch can resolve a release for you when annotating repertoires. That path is work in progress; see the vdjmatch repository. Standalone annotation from a downloaded release is planned.

Building it

uv sync --extra motifs --extra summary --extra test
uv run vdjdb qc                               # chunk validation, fail-fast
uv run vdjdb build --out out/                 # the definitive tables, then every projection
uv run vdjdb make legacy --tables out/tables  # the legacy files
uv run vdjdb convert airr --tables out/tables # AIRR tables
uv run vdjdb motifs --tables out/tables       # TCRNET + TCREMP
uv run vdjdb summary --legacy out/legacy      # the dashboard, offline
uv run vdjdb identity check --tables out/tables # the identifier invariants
uv run vdjdb corpus build --tables out/tables # the reference corpus: tf-idf over 12 token families
uv run vdjdb diff <reference.zip> out/legacy  # compare against a released zip
VDJDB_REFERENCE_ZIP=reference.zip uv run pytest -q

Use the 2026-06-03 release as reference.zip for the release comparison and tests. The static summary also requires R and pandoc; see build requirements.

10x dextramer assays

The chain co-occurrence caller in processing/dcode_chain_graph.py turns a donor's contig annotations and dextramer UMI matrix into specificity calls. process_donor(dcode, donor) is that call for one donor. The command line takes --dcode, --donors and --out and writes chains.tsv, edges.tsv, clones.tsv, calls.tsv and checks.tsv.

chunks/ISSUE_289.tsv (28,125 rows, the four-donor Immudex dCODE assay) is the committed output of that caller. Deposited ITRAP matrices go through processing/itrap_reprocess.py into the same model: itrap1_tables then run_frames for PMID:37133356, and viral_tables then run_frames for the viral assay. The committed files chunks/PMID_37133356.tsv (1,440 rows) and chunks/DOI_10.64898_2025.12.19.695506.tsv (2,468 rows) are the published assignment tables. The procedure is Process a 10x dextramer assay.

Contributing

New records are submitted as chunks - see the submission guide. A chunk pull request is checked in under three minutes by chunk-check, against the specification documented above.

Citing

Please cite the most recent paper:

Daniil V. Luppov, Anna E. Koneva, Dmitry V. Bagaev, Anastasiia V. Alexandrova, Elizaveta K.

Vlasova, Dmitry M. Chudakov, Chihiro Motozono, Andrew K. Sewell & Mikhail Shugay. VDJdb in 2026:

boosting T-cell receptor recognition evidence using paratope embeddings and AI-based structure

prediction. Nucleic Acids Research, 2026.

doi:10.1093/nar/gkag904

A release of the database itself is archived at doi:10.5281/zenodo.22104776.