Column reference

Every table below is built from vdjdb.schema while this page renders. There is no generated file to refresh, so no copy of these tables can disagree with the build.

vdjdb.txt - the release table

Column	Title	Description
complex.id	complex.id	TCR alpha and beta chain records having the same complex identifier belong to the same T-cell clone.
gene	Gene	TCR chain: alpha or beta.
cdr3	CDR3	TCR complementarity determining region 3 (CDR3) amino acid sequence.
v.segm	V	TCR Variable segment allele.
j.segm	J	TCR Joining segment allele.
species	Species	TCR parent species.
mhc.a	MHC A	First MHC chain allele.
mhc.b	MHC B	Second MHC chain allele (defaults to Beta2Microglobulin for MHC class I).
mhc.class	MHC class	MHC class (I or II).
antigen.epitope	Epitope	Amino acid sequence of the epitope.
antigen.gene	Epitope gene	Representative parent gene of the epitope.
antigen.species	Epitope species	Representative parent species of the epitope.
reference.id	Reference	Pubmed reference / URL / or submitter details in case unpublished.
vdjdb.score	Info	VDJdb confidence score, the higher is the score the more confidence we have in the antigen specificity annotation of a given TCR clonotype/clone. Zero score indicates that there are insufficient method details to draw any conclusion.
TCR_hash	TCR hash	SHA256 hash of TCR structure used for structure visualization.
method	Method	Details on method used to assay TCR specificity.
meta	Meta	Various meta-information: cell subset, donor status, etc.
cdr3fix	CDR3fix	Details on CDR3 sequence fixing (if applied) and consistency between V, J and reported CDR3 sequence.
web.method	Internal	Internal: coarse identification method for fast filtering.
web.method.seq	Internal	Internal: coarse sequencing method for fast filtering.
web.cdr3fix.nc	Internal	Internal: CDR3 has non-canonical V or J anchor residues.
web.cdr3fix.unmp	Internal	Internal: CDR3 could not be mapped onto V or J germline.

vdjdb.txt - the vdjdb-web variant

The variant served by vdjdb-web adds five evidence.* columns and a TCR_hash row that the release table does not have.

Column	Title	Description
complex.id	complex.id	TCR alpha and beta chain records having the same complex identifier belong to the same T-cell clone.
gene	Gene	TCR chain: alpha or beta.
cdr3	CDR3	TCR complementarity determining region 3 (CDR3) amino acid sequence.
v.segm	V	TCR Variable segment allele.
j.segm	J	TCR Joining segment allele.
species	Species	TCR parent species.
mhc.a	MHC A	First MHC chain allele.
mhc.b	MHC B	Second MHC chain allele (defaults to Beta2Microglobulin for MHC class I).
mhc.class	MHC class	MHC class (I or II).
antigen.epitope	Epitope	Amino acid sequence of the epitope.
antigen.gene	Epitope gene	Representative parent gene of the epitope.
antigen.species	Epitope species	Representative parent species of the epitope.
reference.id	Reference	Pubmed reference / URL / or submitter details in case unpublished.
vdjdb.score	Info	VDJdb confidence score, the higher is the score the more confidence we have in the antigen specificity annotation of a given TCR clonotype/clone. Zero score indicates that there are insufficient method details to draw any conclusion.
TCR_hash	TCR hash	SHA256 hash of TCR structure used for structure visualization.
method	Method	Details on method used to assay TCR specificity.
meta	Meta	Various meta-information: cell subset, donor status, etc.
cdr3fix	CDR3fix	Details on CDR3 sequence fixing (if applied) and consistency between V, J and reported CDR3 sequence.
web.method	Internal	Internal: coarse identification method for fast filtering.
web.method.seq	Internal	Internal: coarse sequencing method for fast filtering.
web.cdr3fix.nc	Internal	Internal: CDR3 has non-canonical V or J anchor residues.
web.cdr3fix.unmp	Internal	Internal: CDR3 could not be mapped onto V or J germline.
evidence.validation.same.study	Validation same study	Antigen specificity validated within the same study.
evidence.validation.independent	Validation independent	Antigen specificity independently validated in another study.
evidence.structure.contacts	Structure model with contacts	Structural model with annotated TCR-pMHC contacts available.
evidence.structure.quality	Structure good quality model	Good-quality structural model available.
evidence.structure.native	Structure native	Native (experimental) TCR-pMHC structure available.

vdjdb.slim.txt

Column	Title	Description
gene	Gene	TCR chain: alpha or beta.
cdr3	CDR3	TCR complementarity determining region 3 (CDR3) amino acid sequence.
species	Species	TCR parent species.
antigen.epitope	Epitope	Amino acid sequence of the epitope.
antigen.gene	Epitope gene	Representative parent gene of the epitope.
antigen.species	Epitope species	Representative parent species of the epitope.
complex.id	complex.id	TCR alpha and beta chain records having the same complex identifier belong to the same T-cell clone.
v.segm	V	TCR Variable segment allele.
j.segm	J	TCR Joining segment allele.
mhc.a	MHC A	First MHC chain allele.
mhc.b	MHC B	Second MHC chain allele (defaults to Beta2Microglobulin for MHC class I).
mhc.class	MHC class	MHC class (I or II).
reference.id	Reference	Pubmed reference / URL / or submitter details in case unpublished.
vdjdb.score	Info	VDJdb confidence score, the higher is the score the more confidence we have in the antigen specificity annotation of a given TCR clonotype/clone. Zero score indicates that there are insufficient method details to draw any conclusion.
TCR_hash	TCR hash	SHA256 hash of TCR structure used for structure visualization.
j.start	J start	First amino acid position of the J germline part of CDR3, 0-based, junction space.
v.end	V end	Last amino acid position of the V germline part of CDR3, 0-based, junction space.

vdjdb_full.txt

Column	Title
cdr3.alpha	CDR3 alpha
v.alpha	V alpha
j.alpha	J alpha
cdr3.beta	CDR3 beta
v.beta	V beta
d.beta	D beta
j.beta	J beta
species	Species
mhc.a	MHC A
mhc.b	MHC B
mhc.class	MHC class
antigen.epitope	Epitope
antigen.gene	Epitope gene
antigen.species	Epitope species
reference.id	Reference
method.identification	Identification method
method.frequency	Frequency
method.singlecell	Single cell
method.sequencing	Sequencing
method.verification	Verification
meta.study.id	Study id
meta.cell.subset	Cell subset
meta.subject.cohort	Subject cohort
meta.subject.id	Subject id
meta.replica.id	Replica id
meta.clone.id	Clone id
meta.epitope.id	Epitope id
meta.tissue	Tissue
meta.donor.MHC	Donor MHC
meta.donor.MHC.method	Donor MHC method
meta.structure.id	Structure id
cdr3fix.alpha	CDR3fix alpha
cdr3fix.beta	CDR3fix beta
vdjdb.score	Info
TCR_hash	TCR hash

The definitive tables

records and chains are the database. Every shipped file is a join and a pivot away from them.

records

Column	Title	Description
record_id	Record id	Stable VDJdb record identifier. Assigned once, never reused, and it survives a content change – a curator fixing a typo amends a record rather than deleting one and creating another.
pmhc_id	pMHC id	Identifies a presented peptide: PM plus 16 hex digits of a sha256 over the epitope and the two curated MHC chains. Keys on the allele as curated, never on a predicted one, so a new mhcmatch model cannot renumber it.
epitope_id	Epitope id	Identifies the peptide alone, across every allele presenting it: EP plus 16 hex digits of a sha256 over antigen.epitope.
species	Species	TCR parent species.
mhc_a	MHC A	First MHC chain allele.
mhc_b	MHC B	Second MHC chain allele (defaults to Beta2Microglobulin for MHC class I).
mhc_class	MHC class	MHC class (I or II).
antigen_epitope	Epitope	Amino acid sequence of the epitope.
antigen_gene	Epitope gene	Representative parent gene of the epitope.
antigen_species	Epitope species	Representative parent species of the epitope.
reference_id	Reference	Pubmed reference / URL / or submitter details in case unpublished.
meta_study_id	Study id
meta_cell_subset	Cell subset
meta_subject_cohort	Subject cohort
meta_subject_id	Subject id
meta_replica_id	Replica id
meta_clone_id	Clone id
meta_tissue	Tissue
meta_epitope_id	Epitope id
meta_donor_MHC	Donor MHC
meta_donor_MHC_method	Donor MHC method
meta_structure_id	Structure id
meta_subset_frequency	Subset frequency	Kept for debugging; dropped by the legacy build.
method_identification	Identification method
method_frequency	Frequency	Frequency of this clonotype in the isolated epitope-reactive population, as the submitter wrote it: `x/X`, `X%` or a bare float. Free text on purpose - it is what every release has shipped, and some studies report only the ratio.
method_singlecell	Single cell
method_sequencing	Sequencing
method_verification	Verification
method_frequency_count	Frequency count	Reads, UMIs or cells supporting this clonotype, parsed from an unambiguous `x/X` `method.frequency`. Null where the submitted value is a float or a percentage: the count is absent, not zero.
method_frequency_total	Frequency total	The sample total `method.frequency.count` is out of, from the same `x/X`.
method_pairing	Pairing	How alpha and beta chains were paired. Kept for debugging; dropped by the legacy build.
vdjdb_score	Info	VDJdb confidence score, the higher is the score the more confidence we have in the antigen specificity annotation of a given TCR clonotype/clone. Zero score indicates that there are insufficient method details to draw any conclusion.
chunk_file	Chunk file	The chunk the record was read from. One chunk is one publication.
chunk_row	Chunk row	0-based row within the chunk; with chunk.file it points at the curated line.
chunk_id	Chunk id	Kept for debugging; dropped by the legacy build.
submitter	Submitter	Kept for debugging; dropped by the legacy build.
comment	Comment	Kept for debugging; dropped by the legacy build.

chains

Column	Title	Description
record_id	Record id	Stable VDJdb record identifier. Assigned once, never reused, and it survives a content change – a curator fixing a typo amends a record rather than deleting one and creating another.
gene	Gene	TCR chain: alpha or beta.
clonotype_id	Clonotype id	Identifies a receptor chain: CT plus 16 hex digits of a sha256 over species, gene, CDR3, V and J. Records reporting the same chain share it, and motif evidence attaches at this level. Derived from its own key, so no chunk being added or removed can change it.
clone_id	Clone id	Identifies an alpha/beta pair: CX plus 16 hex digits of a sha256 over the record’s two sorted clonotype ids. Empty string on a record reporting one chain, which is the curated state and not missing data.
cdr3	CDR3	TCR complementarity determining region 3 (CDR3) amino acid sequence.
v_segm	V	TCR Variable segment allele.
d_segm	D	TCR Diversity segment allele.
j_segm	J	TCR Joining segment allele.
v_end	V end	Last amino acid position of the V germline part of CDR3, 0-based, junction space.
j_start	J start	First amino acid position of the J germline part of CDR3, 0-based, junction space.
cdr3nt	CDR3 nucleotide	Most plausible nucleotide junction behind the amino-acid one, inferred from the recombination model – not observed. Two models agree on only 7.2 % of these, so it is a representative history, never evidence.
cdr3nt_pgen	CDR3nt Pgen	Generation probability of the inferred nucleotide junction.
cdr3nt_margin	CDR3nt margin	How far the inferred junction beat the runner-up: its Pgen divided by the next candidate’s. Near 1 means the choice among synonymous histories was near-arbitrary.
v_inferred	V inferred	V call proposed by the recombination model, filled only where the curator named none. Recovers the curated V on 23.8 % of human TRB and 50.1 % of TRA when it is hidden – the junction carries little V. Never overwrites v.segm.
j_inferred	J inferred	J call proposed by the recombination model, filled only where the curator named none. Recovers the curated J on 97.5 % of human TRB and 95.8 % of TRA.
d_inferred	D inferred	D allele of the recombination scenario that produced cdr3nt. Not the curated d.segm, which it matches at gene level on 76.5 % of beta chains.
d_start	D start	First nucleotide of the D segment in cdr3nt, 0-based, half-open with d.end.
d_end	D end	One past the last nucleotide of the D segment in cdr3nt.
d_posterior	D posterior	Posterior probability of the gene d.inferred names, from the same recombination scenario weights that named it – so the number is the probability of that call. Naming the D is 74.35 % correct at gene level on human TRB against nucleotide truth; filter on this rather than reading d.inferred alone.
v_end_inferred	V end inferred	V/J boundary from a germline alignment over the junction, in v.end’s space. A fallback, never an override: filled only where the markup engine declined and -1 everywhere else, so coalescing it with v.end cannot overwrite an alignment answer. Against observed nucleotide boundaries it is exact on 92.9 % of junctions where v.end is 71.8 %, so where v.end is -1 this carries a better answer than nothing.
j_start_inferred	J start inferred	As v.end.inferred, for j.start.
cdr3_original	CDR3 as submitted	The CDR3 as the reference publication reported it, before repair.
fix_needed	Fix needed	Whether the repaired CDR3 differs from the submitted one.
fix_good	Fix good	Whether the CDR3 could be placed on both germline segments.
v_fix_type	V fix type	How the V side was repaired: NoFixNeeded, FixAdd, FixTrim, FixReplace, TruncatedGermline (the boundary is real but a lower bound, because IMGT ships that allele’s germline record stopping inside the anchor region), or a Failed* reason.
j_fix_type	J fix type	How the J side was repaired.
v_canonical	V anchor canonical	Whether the CDR3 begins with Cys104, which a TCR junction does by definition. False marks a record kept for what it reports and filterable by anyone who wants only canonical junctions.
j_canonical	J anchor canonical	Whether the CDR3 ends with Phe118 or Trp118, which a TCR junction does by definition. False marks a record kept and filterable, not a variant.
v_canonical_submitted	V anchor canonical as submitted	Whether the submitted CDR3 began with Cys104, before any repair.
j_canonical_submitted	J anchor canonical as submitted	Whether the submitted CDR3 ended with Phe118 or Trp118, before any repair.
cdr3_one_cysteine	Single cysteine	Whether the CDR3 carries no cysteine after the Cys104 it opens with.
v_segm_submitted	V as submitted	The V call as the reference publication reported it, before IMGT harmonisation and allele disambiguation. Compare with v.segm to see what the build decided.
j_segm_submitted	J as submitted	The J call as the reference publication reported it, before harmonisation.
d_segm_submitted	D as submitted	The D call as the reference publication reported it, before harmonisation. Beta only; the alpha locus has no D.
v_segm_arda	V called by the markup engine	The V allele the markup engine aligned the junction against, which is evidence about the sequence rather than about what was reported. It is NOT what ships: v.segm carries the curated call. Empty where the engine named no allele.
j_segm_arda	J called by the markup engine	The J allele the markup engine aligned against. Not what ships; see v.segm.arda.
TCR_hash	TCR hash	SHA256 hash of TCR structure used for structure visualization.

epitopes

Column	Title
antigen_epitope	Epitope
antigen_species	Epitope species
antigen_gene	Epitope gene
epitope_length	Epitope length
mhc_class	MHC class
records	Records
chains	Chains
references	References
clonotypes	Clonotypes
proteome_peptide	Proteome peptide
proteome_substitution	Substitution

restriction

Column	Title
antigen_epitope	Epitope
antigen_species	Epitope species
mhc_a	MHC A
mhc_b	MHC B
mhc_class	MHC class
mhc_a_status	MHC A status
mhc_b_status	MHC B status
records	Records
references	References
alleles_reported	Alleles reported
mhc_a_top	Top-scoring allele
mhc_a_rank	Curated allele rank
mhc_a_percentile	Curated allele percentile
promiscuity	Promiscuity
mhcmatch_version	mhcmatch version

evidence

Column	Title
record_id	Record id
gene	Gene
evidence_id	Evidence id
evidence_type	Evidence type
evidence_source	Evidence source
evidence_value	Evidence value
evidence_score	Evidence score
first_seen_release	First seen release

The motif files

⚠ These two files are parsed positionally by vdjdb-web, which hands Tablesaw a fixed column-type array with no header check. An inserted, removed or reordered column mistypes or shifts every column after it, without an error. Column order is a contract.

cluster_members.txt

Column	Title
species	Species
antigen.epitope	Epitope
antigen.gene	Epitope gene
antigen.species	Epitope species
mhc.a	MHC A
mhc.b	MHC B
mhc.class	MHC class
gene	Gene
cdr3aa	CDR3
x	x
y	y
cid	Cluster id
csz	Cluster size
v.segm	V
j.segm	J
v.end	V end
j.start	J start
v.segm.repr	V representative
j.segm.repr	J representative

motif_pwms.txt

Column	Title
species	Species
antigen.epitope	Epitope
gene	Gene
aa	Residue
pos	Position
len	Length
v.segm.repr	V representative
j.segm.repr	J representative
cid	Cluster id
csz	Cluster size
count	Count
count.bg	Background count
total.bg	Background total
count.bg.i	Imputed background count
total.bg.i	Imputed background total
need.impute	Imputed
freq	Frequency
freq.bg	Background frequency
I	Information
I.norm	Normalised information
height.I	Letter height
height.I.norm	Normalised letter height
antigen.gene	Epitope gene
antigen.species	Epitope species
mhc.a	MHC A
mhc.b	MHC B
mhc.class	MHC class