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

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.