GPTomics/bio-tcr-bcr-analysis-specificity-annotation

Version Compatibility

Reference examples tested with: tcrdist3 0.2+, olga 1.2+, pandas 2.0+, numpy 1.24+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• CLI: <tool> --version then <tool> --help to confirm flags

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Note: OLGA's CLI entry point is olga-compute_pgen (underscore) and its bundled human beta model lives in default_models/human_T_beta/. GLIPH2 results are reference-repertoire- and parameter-sensitive; verify the reference set used and rerun with a second method before trusting cluster labels.

Antigen-Specificity Annotation and Clustering for TCR/BCR Repertoires

"Which antigens might my receptors recognize?" -> Annotate CDR3s against curated TCR:pMHC records, keeping only defensible matches.

• Python: pandas.merge on VDJdb/McPAS export; IEDB TCRMatch for k-mer similarity to characterized receptors

"Cluster my repertoire into shared-specificity groups." -> Find sequence neighborhoods enriched for a common specificity.

• Python: tcrdist.repertoire.TCRrep (TCRdist neighborhoods / meta-clonotypes), GLIPH2, GIANA, clusTCR

"Is this shared/public clonotype antigen-driven or just easy to generate?" -> Test the sharing against a generation-probability null.

• Python/CLI: olga (Pgen), IGoR (learn the model), SONIA/soNNia (Ppost = Pgen x Q)

The governing principle: a match or a cluster is a hypothesis, not a specificity call

Mapping receptor sequence to antigen specificity is largely UNSOLVED in the general case. Every method here does one of three things and none of them proves specificity: (a) it annotates against a biased database, (b) it finds a sequence neighborhood ENRICHED for shared specificity, or (c) it predicts binding only for epitopes seen in training. A VDJdb hit or a GLIPH2 cluster label is therefore a hypothesis with a confidence level, never "this receptor is specific for antigen Y". The entire job of this skill is to stop that overclaim: report annotations and clusters with their confidence, their required concordances (V-gene, HLA), and a generation-probability baseline, and reserve the word "specific" for tetramer/dextramer or functional confirmation.

Why the problem resists a clean solution:

• A TCR recognizes a peptide-MHC complex, not a peptide. Specificity is a property of the TCR:pMHC triple, so the same CDR3 can be specific for different peptides under different HLA. MHC restriction cannot be dropped.
• Massive cross-reactivity: a single TCR can recognize up to ~10^6 peptides (Sewell 2012 Nat Rev Immunol 12:669). One-receptor-one-antigen is false by design.
• Specificity is encoded jointly by the paired alpha and beta chains; bulk sequencing gives beta-only and discards the pairing that carries much of the signal.
• Training and database records are dominated by a few immunodominant epitopes (influenza GILGFVFTL, CMV NLVPMVATV, EBV GLCTLVAML, SARS-CoV-2), with heavy HLA-A*02:01 and CD8/MHC-I skew; CD4/MHC-II, gamma-delta TCR, and BCR data are sparse to absent. Any accuracy averaged over epitopes is inflated by the few easy ones, and a gamma-delta or CD4 repertoire will return almost nothing from these databases and models (absence of a hit is uninformative, not evidence of non-specificity).

Three approaches: pick by the question, then corroborate

| Approach | Tools | What it answers | What it PROVES / does NOT | Best when | Fails when | |----------|-------|-----------------|---------------------------|-----------|------------| | Database annotation | VDJdb (score 0-3), McPAS-TCR, IEDB + TCRMatch | Does a curated TCR:pMHC record match this receptor? | A record matches; NOT that the receptor is specific (base-rate false positives) | Donor HLA known, V-gene available, high-confidence entries wanted | Bare CDR3 match, no HLA/V concordance, high-Pgen sequences match by chance | | Sequence clustering | tcrdist3 meta-clonotypes, GLIPH2, GIANA, clusTCR, iSMART | Which receptors form a shared-specificity neighborhood? | A group is enriched for shared specificity; NOT a per-receptor antigen label | Discovering specificity groups, building reusable features from many receptors | Treating a cluster label as an antigen call; single-tool trust; no reference-null | | Generation-probability null | OLGA (Pgen), IGoR, SONIA/soNNia (Ppost) | Is this sharing/convergence more than chance generation? | Whether a sequence is expected by recombination; the null for every sharing claim | Any "public"/convergent/shared/expanded-beyond-chance claim | Omitted entirely (the most common gap) -> publicity mistaken for antigen selection |

Default workflow: annotate with confidence and concordance, treat clusters as hypotheses, and attach a Pgen null to any sharing or convergence claim. Run at least two clustering methods and report agreement; benchmarks disagree on tool ranking by dataset and epitope, and there is no accepted gold standard (Meysman 2023 ImmunoInformatics 9:100024). Verify current best practice against each tool's latest docs before committing to one.

Database annotation with the base-rate guardrail

Goal: Annotate a bulk beta repertoire against curated TCR:pMHC records without generating a flood of chance matches.

Approach: Restrict the database to confidence >= 1, join on CDR3 AND V-gene (never CDR3 alone), then drop matches whose restricting HLA the donor does not carry. A bare CDR3-beta match to a high-Pgen sequence is a base-rate false positive: the number of spurious hits scales with repertoire size x database size x match permissiveness.

import pandas as pd

def annotate_by_db(repertoire, vdjdb, donor_hla, min_confidence=1):
    # repertoire, vdjdb: cdr3_b_aa + v_b_gene (IMGT, e.g. TRBV19*01); vdjdb also antigen_epitope, mhc_a, vdjdb_score
    # vdjdb_score 0-3: 0 = critical info missing, 3 = independently validated; >=1 drops single-observation noise
    db = vdjdb[vdjdb['vdjdb_score'] >= min_confidence]
    hits = repertoire.merge(db, on=['cdr3_b_aa', 'v_b_gene'], how='inner', suffixes=('', '_db'))  # V concordance, not CDR3 alone
    carries_hla = hits['mhc_a'].apply(lambda a: any(a.startswith(h) for h in donor_hla))  # restricting HLA must be present in donor
    hits = hits[carries_hla].copy()
    hits['annotation_confidence'] = 'hypothesis'  # a curated match, not a specificity call
    return hits

IEDB ships TCRMatch (Chronister 2021 Front Immunol 12:640725) for k-mer similarity of a CDR3-beta to characterized receptors: it returns a similarity score, which proves sequence similarity to a known receptor, not binding. Report match counts and an enrichment statistic against a size-matched synthetic/unexposed repertoire, not a binary "specific".

Sequence clustering as neighborhood discovery

Goal: Group receptors into shared-specificity neighborhoods that can be quantified and reused, without mistaking a cluster for an antigen label.

Approach: TCRdist scores position-weighted CDR distances using the germline-encoded CDR1/CDR2/CDR2.5 loops (V-gene identity is baked in) plus the CDR3 up-weighted ~3x (Dash 2017 Nature 547:89). Build the pairwise beta matrix, then take fixed-radius neighborhoods in TCRdist units. A neighborhood is a meta-clonotype candidate (centroid + radius + optional motif), a testable feature, not a specificity assignment (Mayer-Blackwell 2021 eLife 10:e68605).

import numpy as np
from tcrdist.repertoire import TCRrep

def beta_neighborhoods(clone_df, radius=50):
    # clone_df: cdr3_b_aa, v_b_gene, j_b_gene, count (IMGT gene names). organism/chains fix the germline loops used.
    tr = TCRrep(cell_df=clone_df, organism='human', chains=['beta'], db_file='alphabeta_gammadelta_db.tsv')
    # radius in TCRdist units; ~50 is a common meta-clonotype inclusion radius (Mayer-Blackwell 2021), tune per centroid
    neighbors = [set(np.where(row <= radius)[0]) for row in tr.pw_beta]
    return tr, neighbors

CDR3-only tools (GLIPH2 Huang 2020 Nat Biotechnol 38:1194; GIANA Zhang 2021 Nat Commun 12:4699; clusTCR Valkiers 2021 Bioinformatics 37:4865; iSMART Zhang 2020 Clin Cancer Res 26:1359) scale to millions of CDR3s but ignore the paired chain and often HLA, so they can merge receptors sharing a motif but differing in true restriction. GLIPH2 tends to produce large, low-specificity clusters and its enrichment is sensitive to the reference repertoire and input size; report the reference used and a null-corrected p-value, and prefer tcrdist3 meta-clonotypes as reusable features. For paired single-cell data, CoNGA (Schattgen 2022 Nat Biotechnol 40:54) links TCR neighborhoods to gene-expression state rather than to an antigen.

Generation-probability nulls: the rigorous test for "public"/convergent

Goal: Decide whether a shared, convergent, or database-matched clonotype is antigen-driven or merely easy to generate.

Approach: High-Pgen sequences (few insertions, germline-like, short CDR3) recur across donors and match databases BY CHANCE, so publicity alone is not evidence of selection (Quigley 2010 PNAS 107:19414). Compute Pgen with OLGA (Sethna 2019 Bioinformatics 35:2974) for every match or shared clonotype and down-weight the high-Pgen ones; a clonotype is evidence of convergent selection only if observed more than its generation probability predicts. SONIA/soNNia add selection (Ppost = Pgen x Q) for a post-selection null.

import os
import olga.load_model as load_model
import olga.generation_probability as generation_probability

def load_beta_pgen_model(model_dir):
    # model_dir = OLGA default_models/human_T_beta with model_params.txt, model_marginals.txt, V/J anchors CSV
    gen_data = load_model.GenomicDataVDJ()
    gen_data.load_igor_genomic_data(os.path.join(model_dir, 'model_params.txt'),
                                    os.path.join(model_dir, 'V_gene_CDR3_anchors.csv'),
                                    os.path.join(model_dir, 'J_gene_CDR3_anchors.csv'))
    gen_model = load_model.GenerativeModelVDJ()
    gen_model.load_and_process_igor_model(os.path.join(model_dir, 'model_marginals.txt'))
    return generation_probability.GenerationProbabilityVDJ(gen_model, gen_data)

def pgen(model, cdr3_b_aa, v_b_gene, j_b_gene):
    return model.compute_aa_CDR3_pgen(cdr3_b_aa, v_b_gene, j_b_gene)  # ~ms/seq; high value => expected by chance, down-weight

The CLI equivalent is olga-compute_pgen --humanTRB CASSLGQAYEQYF or olga-compute_pgen --humanTRB -i seqs.tsv -o pgens.tsv.

ML binding predictors: interpolate within trained epitopes only

DeepTCR, ERGO-II, NetTCR-2.0, pMTnet, and TITAN predict TCR:epitope binding but interpolate WITHIN epitopes seen in training and collapse toward random on unseen epitopes (Moris 2021 Brief Bioinform 22:bbaa318; Grazioli 2022 Front Immunol 13:1014256). Published AUCs are inflated by data leakage (same epitope in train and test) and by negative-sampling artifacts, where models separate the negative-generation process rather than binding (Dens 2023 Nat Mach Intell 5:1060-1062). Gate any predictor to epitopes well-represented in its training set, never present a per-TCR score for a novel neoantigen as validated, and require leave-epitope-out evaluation with reference negatives. Cross-reference immunoinformatics/tcr-epitope-binding for the predictor details rather than duplicating them here.

BCR/antibody note

Antibody specificity is harder than TCR: somatic hypermutation makes the functional sequence a moving target away from germline, and most antibody epitopes are conformational, so sequence-only epitope prediction is fundamentally limited and often needs structure. The sequence-level analogue of a public TCR is a convergent public antibody clonotype to a pathogen, e.g. the IGHV3-53/IGHV3-66 clonotype against the SARS-CoV-2 RBD (Robbiani 2020 Nature 584:437; Tan 2021 Nat Commun 12:4210). As with TCRs, a shared V-gene plus CDRH3 motif across donors is a hypothesis of convergent selection that still needs a Pgen/expected-sharing null and binding confirmation. Cluster BCR clones (shared V, J, junction length + within-partition distance) before any such analysis; see immcantation-analysis.

Common Errors

| Symptom | Cause | Fix | |---------|-------|-----| | A repertoire reported "specific for antigen Y" from a DB hit or cluster | A curated match or a cluster label treated as ground-truth specificity | Report it as an annotation/hypothesis with confidence; confirm with tetramer/dextramer or functional assay before saying "specific" | | Many DB matches to many epitopes in a large repertoire | Base-rate false positives from bare CDR3-beta matching to high-Pgen sequences | Require V-gene concordance, require donor HLA carriage, filter to VDJdb score >= 1-2, and attach a Pgen null | | "Public"/convergent response claimed from sharing across donors | Sharing tested without a generation-probability baseline | Compute OLGA Pgen (or SONIA Ppost); a clonotype is convergent only if observed above its generation expectation | | Beta-only annotation trusted as full specificity | Bulk data is unpaired; specificity is a paired alpha/beta + HLA property | Down-weight beta-only annotations; use single-cell paired alpha/beta (scirpy) or paired TCRdist where possible | | ML predictor score believed for a new neoantigen | Predictors fail out-of-distribution on unseen epitopes; benchmark AUCs leak | Gate to well-trained epitopes; use leave-epitope-out validation and reference negatives; treat novel-epitope scores as unreliable | | Cluster from one tool taken as truth | No gold standard; GLIPH2 clusters are reference- and parameter-sensitive | Run >= 2 methods, report agreement and the reference repertoire, check HLA-concordance and cluster tightness | | HLA ignored in annotation | Specificity is a TCR:pMHC triple; the same CDR3 differs by restricting HLA | Restrict DB entries to alleles the donor carries; report the restricting HLA with every annotation |

Related Skills

• mixcr-analysis - Produce clonotype tables to annotate
• scirpy-analysis - Paired single-cell clonotypes for specificity work
• vdjtools-analysis - Public-clonotype context and overlap
• immunoinformatics/tcr-epitope-binding - ML epitope-binding prediction details
• immunoinformatics/mhc-binding-prediction - Upstream pMHC restriction
• immunoinformatics/neoantigen-prediction - Neoantigen-directed specificity

References

• Dash P, et al. Quantifiable predictive features define epitope-specific T cell receptor repertoires. Nature 2017; 547(7661):89-93.
• Glanville J, et al. Identifying specificity groups in the T cell receptor repertoire. Nature 2017; 547(7661):94-98.
• Huang H, et al. Analyzing the Mycobacterium tuberculosis immune response by T-cell receptor clustering with GLIPH2 and genome-wide antigen screening. Nat Biotechnol 2020; 38:1194-1202.
• Mayer-Blackwell K, et al. TCR meta-clonotypes for biomarker discovery with tcrdist3. eLife 2021; 10:e68605.
• Schattgen SA, et al. Integrating T cell receptor sequences and transcriptional profiles by clonotype neighbor graph analysis (CoNGA). Nat Biotechnol 2022; 40:54-63.
• Zhang H, et al. Investigation of Antigen-Specific T-Cell Receptor Clusters in Human Cancers (iSMART). Clin Cancer Res 2020; 26(6):1359-1371.
• Zhang H, et al. GIANA allows computationally-efficient TCR clustering and multi-disease repertoire classification by isometric transformation. Nat Commun 2021; 12:4699.
• Valkiers S, et al. clusTCR: a Python interface for rapid clustering of large sets of CDR3 sequences with unknown antigen specificity. Bioinformatics 2021; 37(24):4865-4867.
• Shugay M, et al. VDJdb: a curated database of T-cell receptor sequences with known antigen specificity. Nucleic Acids Res 2018; 46(D1):D419-D427.
• Tickotsky N, et al. McPAS-TCR: a manually curated catalogue of pathology-associated T cell receptor sequences. Bioinformatics 2017; 33(18):2924-2929.
• Chronister WD, et al. TCRMatch: predicting T-cell receptor specificity based on sequence similarity to previously characterized receptors. Front Immunol 2021; 12:640725.
• Marcou Q, Mora T, Walczak AM. High-throughput immune repertoire analysis with IGoR. Nat Commun 2018; 9:561.
• Sethna Z, et al. OLGA: fast computation of generation probabilities of B- and T-cell receptor amino acid sequences and motifs. Bioinformatics 2019; 35(17):2974-2981.
• Quigley MF, et al. Convergent recombination shapes the clonotypic landscape of the naive T-cell repertoire. PNAS 2010; 107:19414-19419.
• Moris P, et al. Current challenges for unseen-epitope TCR interaction prediction and a new perspective derived from image classification. Brief Bioinform 2021; 22(4):bbaa318.
• Meysman P, et al. Benchmarking solutions to the T-cell receptor epitope prediction problem (IMMREP22). ImmunoInformatics 2023; 9:100024.
• Robbiani DF, et al. Convergent antibody responses to SARS-CoV-2 in convalescent individuals. Nature 2020; 584:437-442.
• Tan TJC, et al. Sequence signatures of two public antibody clonotypes that bind SARS-CoV-2 RBD. Nat Commun 2021; 12:4210.
• Sewell AK. Why must T cells be cross-reactive? Nat Rev Immunol 2012; 12:669-677.