TCR to Amino Acid Sequence

Reconstructs the full TCR variable-domain amino acid sequence from V/J gene calls and the CDR3 sequence.

Web app slug: tcr-to-amino-seq

---

When to use

Repertoire and clonotype tables (from Adaptive, MiXCR, etc.) rarely store the full receptor protein. They typically give you only three things per clonotype:

• a V gene call (e.g. TRBV20-1)
• an optional J gene call (e.g. TRBJ2-1)
• the CDR3 sequence

Use this pipeline when you have those columns and need the complete variable-domain amino acid sequence — for example as input to Pseudo-Sequence Alignment, clustering, or any model that expects a full sequence rather than a gene + CDR3 triplet.

---

The core idea

A TCR variable domain is made of seven segments in a fixed order:

FWR1 – CDR1 – FWR2 – CDR2 – FWR3 – CDR3 – FWR4

The key insight is where each segment comes from:

• FWR1, CDR1, FWR2, CDR2, FWR3 are encoded entirely by the germline V gene. Every clonotype that uses the same V allele shares these exact regions.
• FWR4 is encoded entirely by the germline J gene.
• CDR3 is the only hypervariable, junction-formed region — it cannot be looked up, so it is taken directly from your input.

So the full sequence can be reassembled without ever sequencing the whole receptor: look up the germline regions for the called V and J genes, then splice in the clonotype-specific CDR3.

sequence_aa =  FWR1 + CDR1 + FWR2 + CDR2 + FWR3   (from V germline dictionary)
            +  CDR3                                 (from your input)
            +  FWR4                                 (from J germline dictionary)

The germline regions are read from per-species reference dictionaries (currently Human): one for V genes (fwr1_aa, cdr1_aa, fwr2_aa, cdr2_aa, fwr3_aa) and one for J genes (fwr4_aa).

---

Gene-name normalization

The hardest part is not the lookup — it’s that gene names in real-world data are inconsistent across tools. Before lookup, each V/J call is normalized through several steps so that variants of the same gene all resolve to one canonical dictionary entry:

1. Vendor prefix — TCR is rewritten to TR (e.g. Adaptive’s TCRBV20 → TRBV20).

2. Multi-gene calls — when a cell lists several ambiguous genes separated by ,, or, or / (e.g. TRBV20-1 or TRBV20-2), the first option is taken.

3. Zero-padding — leading zeros are stripped from gene and allele numbers (TRBV09 → TRBV9, *01 → *1).

4. Allele resolution, tried in order until one matches the dictionary:

   • exact match including allele (TRBV20-1*1)
   • the gene without its allele (TRBV20-1)
   • the first dictionary entry that starts with that base name
   • a match after stripping all - and * characters

5. Family fallback — if nothing matches, everything after the first - or * is dropped and the lookup is retried against the gene family.

Genes that still don’t resolve are recorded as missing and reported as a warning; rows depending on them produce no sequence (see filtering below). Normalization results are memoized, so a repertoire with millions of rows but a few hundred distinct genes resolves each gene only once.

Tip

Because only the called gene drives the framework/CDR1/CDR2 regions, the quality of the reconstructed sequence is only as good as the V/J calls in your input. Garbage or unrecognized gene calls become missing rows, not wrong sequences.

---

Optional behavior

Option	What it does
Trim CDR3	Removes the first and last residue of each CDR3 (the conserved anchors, typically C … F/W) before splicing, when CDR3 length > 2. Use this when your CDR3 column includes the anchor residues and your reference regions already account for them.
Append mode	When on, the reconstructed columns are added alongside your original columns (duplicates dropped). When off, the output contains only the processed columns.

---

What you get

Each output row carries the canonical V/J names, the (optionally trimmed) CDR3, the individual germline region columns (v_* and j_*), and the assembled full sequence in the sequence_aa column.

A row is only kept if it has all of: a non-empty CDR3, a resolved CDR1 (v_cdr1_aa), and a resolved CDR2 (v_cdr2_aa). In practice this means a row survives only when its V gene was recognized and its CDR3 is present — rows with unresolved V genes or missing CDR3 are dropped rather than emitted as partial sequences.

---

Troubleshooting

Many rows dropped / “Missing V genes” warning The V gene calls aren’t matching the reference dictionary. Check that your V column actually holds gene names (not allele-only strings or numeric IDs) and that they use a recognizable TR/TCR naming convention. The warning lists the exact unmatched gene names.

sequence_aa is empty or short A segment was missing — most often an unresolved V gene (no FWR1–FWR3 / CDR1 / CDR2) or, when a J column is supplied, an unresolved J gene (no FWR4). Confirm the V and (optional) J column names point at the right columns.

Sequences look one residue short on each end of CDR3 Trim CDR3 is enabled. Disable it if your CDR3 column does not include the conserved anchor residues.