GPTomics/bio-immunoinformatics-epitope-prediction

Version Compatibility

Reference examples tested with: BepiPred-3.0, pandas 2.2+

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.

Notes specific to this skill: BepiPred-3.0 ships as the bepipred3 package and auto-downloads ESM-2 weights on first run; its default threshold is 0.1512 (NOT 0.5). DiscoTope-3.0, ElliPro, SEPPA, NetChop, and NetCTLpan are standalone/web (IEDB or DTU). The IEDB classic and next-generation REST APIs wrap most predictors. Re-verify thresholds and the supported-method list against current docs.

Epitope Prediction

"Predict the B-cell and T-cell epitopes in my antigen" -> Identify antibody-binding (B-cell) and MHC-presented (T-cell) immunogenic regions, with appropriately different confidence for each.

• Python: bepipred3 for linear B-cell epitopes; IEDB REST API for B-cell/T-cell tools
• CLI/web: DiscoTope-3.0 for conformational B-cell epitopes (structure-based); NetMHCpan/MHCflurry (EL) for T-cell epitopes

The Single Most Important Modern Insight -- "epitope prediction" is two fields at different maturity, wrongly conflated

T-cell epitope prediction is mature and trustworthy because it reduces to MHC binding/presentation — a sharply constrained problem (a peptide fits the groove or it does not) with an enormous mass-spec eluted-ligand training corpus; NetMHCpan-4.1 and MHCflurry routinely exceed AUC 0.9 for class I. B-cell epitope prediction is unreliable: linear sequence-based predictors land around AUC 0.6, and even the ESM-2-based BepiPred-3.0 falls to AUC 0.663 on the real IEDB external test set. This is structural, not a tuning problem the next network will fix: ~90% of natural B-cell epitopes are conformational/discontinuous — residues clustered in 3D but far apart in sequence — which a sequence-only model is by construction blind to. The single most damaging mistake in this domain is letting the well-deserved confidence in MHC/T-cell prediction leak into unwarranted confidence in B-cell prediction. Write down which problem is being solved before running anything.

Tool Taxonomy

| Tool | Citation | Target | Input | When | |------|----------|--------|-------|------| | NetMHCpan-4.1 EL / MHCflurry | Reynisson 2020; O'Donnell 2020 | T-cell (MHC-I presentation) | sequence + HLA | Default T-cell path; EL encodes processing | | NetMHCIIpan / NetCTLpan | Nilsson 2023; Stranzl 2010 | T-cell (CD4 / integrated CTL) | sequence + HLA | CD4 epitopes; integrated cleavage+TAP+MHC | | DiscoTope-3.0 | Høie 2024 | B-cell (conformational) | 3D structure (AlphaFold OK) | The only defensible B-cell method when a structure exists | | BepiPred-3.0 | Clifford 2022 | B-cell (linear) | sequence | Linear/denatured-target reagents; misses ~90% native | | ElliPro / SEPPA 3.0 | Ponomarenko 2008; Zhou 2019 | B-cell (conformational) | 3D structure | Fast geometric baseline; SEPPA for glycoproteins | | Propensity scales | Kolaskar 1990 etc. | B-cell (linear) | sequence | Obsolete; decoration, not data |

Decision Tree by Scenario

| Scenario | Recommended | Why | |----------|-------------|-----| | T-cell (CD8) epitopes | NetMHCpan-4.1 EL / MHCflurry | Mature; defer to mhc-binding-prediction | | T-cell (CD4) epitopes | NetMHCIIpan-4.3 | Defer to mhc-class-ii-prediction; less reliable | | B-cell, structure available or foldable | DiscoTope-3.0 on AlphaFold model | Conformational; ~no penalty for predicted structures | | B-cell glycoprotein (Env/S/HA) | SEPPA 3.0 | Models glycan shielding | | B-cell, sequence only, peptide/denatured target | BepiPred-3.0 (linear/top-X%) | Legitimate narrow use; state the conformational caveat | | B-cell, sequence only, native antibody response | Fold a structure first, then DiscoTope-3.0 | Linear prediction structurally cannot see native epitopes | | Broadly-protective vaccine | + conservation + HLA population coverage | A high-scoring epitope in a hypervariable loop is worthless |

Predict Linear B-Cell Epitopes (BepiPred-3.0)

Goal: Score per-residue linear B-cell epitope probability from sequence, for a linear/denatured-target use case.

Approach: Run the bepipred3 CLI (or package) on a FASTA; it emits per-residue probabilities, a binary FASTA (upper = epitope), and top-X% selections. Use the default threshold 0.1512 or the top-X% mode; treat output as a hypothesis that misses most native conformational epitopes.

# bepipred3 auto-downloads ESM-2 weights on first run; default threshold 0.1512 (NOT 0.5)
python bepipred3_CLI.py -i antigen.fasta -o bp3_out/ -pred vt_pred -t 0.1512
# or select the top 20% scoring residues per sequence instead of a fixed cutoff:
python bepipred3_CLI.py -i antigen.fasta -o bp3_out/ -pred vt_pred -top 20

Predict Conformational B-Cell Epitopes (DiscoTope-3.0)

Goal: Identify antibody-accessible surface patches from a 3D structure (the defensible B-cell path).

Approach: Provide a single antigen chain (experimental or AlphaFold). DiscoTope-3.0 scores per-residue conformational propensity and was trained on predicted structures, so AF2 models incur essentially no penalty (AUC 0.799 vs 0.807). Gate trust by pLDDT — accuracy drops ~5 percentile points per 10-point pLDDT decrease — and remember AUC-PR is only ~0.22 (low precision, many false positives).

def gate_discotope_by_plddt(df, plddt_col='pLDDT', score_col='DiscoTope-3.0 score', min_plddt=70):
    '''Keep DiscoTope-3.0 calls only in confidently-folded regions; low-pLDDT loops
    (where antibodies often bind) are exactly where structure-based calls are least
    reliable. df: per-residue DiscoTope-3.0 output joined with model pLDDT.'''
    return df[df[plddt_col] >= min_plddt].sort_values(score_col, ascending=False)

T-Cell Epitopes Reduce to MHC Presentation

Goal: Nominate CD8/CD4 epitopes from an antigen.

Approach: Tile the antigen and score with EL-mode MHC presentation (class I: mhc-binding-prediction; class II: mhc-class-ii-prediction). Do NOT add NetChop by default — EL models are trained on eluted ligands that already survived proteasomal cleavage and TAP, so the processing signal is implicit; explicit cleavage prediction is largely redundant and can double-penalize. Reserve NetChop/NetCTLpan for long source proteins as a cleavage sanity check or alleles lacking EL coverage.

Per-Method Failure Modes

Linear predictor used for native antibody response

Trigger: running BepiPred on a folded viral spike to predict neutralizing epitopes. Mechanism: native epitopes are conformational; sequence models cannot see them. Symptom: "predicted epitopes" that no native antibody targets. Fix: fold a structure and use DiscoTope-3.0; reserve linear predictors for peptide/denatured targets.

Predicting epitopes of a wrong model

Trigger: DiscoTope on a low-confidence AlphaFold surface loop or a monomer of an oligomeric antigen. Mechanism: a subtly wrong surface moves the predicted epitope; an oligomer interface looks exposed in the monomer. Symptom: false-positive epitopes at buried/flexible sites. Fix: gate by pLDDT; model the biological assembly when the antigen oligomerizes.

Propensity-scale cargo cult

Trigger: reporting Kolaskar-Tongaonkar/Parker/Emini "antigenic regions" as data. Mechanism: these are coarse 1980s physicochemical descriptors at/near random. Symptom: confident-looking but uninformative B-cell calls. Fix: treat as obsolete decoration; everything they encode is subsumed by BepiPred/structure methods.

Confusing presentation with immunodominance

Trigger: ranking vaccine epitopes purely by binding/presentation score. Mechanism: immunodominance depends on repertoire, competition, processing kinetics, immune history — none modeled. Symptom: a strong predicted binder that is subdominant or ignored in vivo. Fix: treat presentation as necessary-not-sufficient; validate by ELISpot/tetramer.

Quantitative Thresholds

| Threshold | Source | Rationale | |-----------|--------|-----------| | BepiPred-3.0 default 0.1512 | Clifford 2022 | Balances sens/spec on their benchmark; NOT 0.5 | | Linear B-cell AUC ~0.6 | Field benchmarks | Barely above random; report as hypothesis | | DiscoTope-3.0 AUC-ROC ~0.80, AUC-PR ~0.22 | Høie 2024 | Moderate ranking, low precision (minority class) | | pLDDT >= 70 to trust DiscoTope calls | Høie 2024 | ~5 percentile-point drop per 10-point pLDDT loss | | ~90% of B-cell epitopes conformational | B-cell literature | Why sequence-only prediction has a low ceiling | | Skip NetChop on EL-mode predictions | Reynisson 2020 | EL training already encodes cleavage/TAP |

Common Errors

| Error / symptom | Cause | Solution | |-----------------|-------|----------| | Over-trusting B-cell predictions | Conflated with mature T-cell prediction | State the maturity asymmetry; treat B-cell as hypothesis | | Few/no BepiPred epitopes | Applied 0.5 threshold | Use default 0.1512 or top-X% mode | | False epitopes in flexible loops | Low-pLDDT AlphaFold model | Gate by pLDDT; assess model quality | | Epitope worthless across strains | No conservation analysis | Add IEDB Epitope Conservancy + MSA | | Redundant/over-penalized T-cell calls | NetChop stacked on EL model | Use EL presentation as the primary filter | | Vaccine "designed" in silico | Over-trusting reverse-vaccinology scores | Treat VaxiJen/Vaxign as candidate funnels; validate experimentally |

References

• Clifford JN, Høie MH, Deleuran S, Peters B, Nielsen M, Marcatili P. 2022. BepiPred-3.0: improved B-cell epitope prediction using protein language models. Protein Science 31(12):e4497.
• Høie MH, Gade FS, Johansen JM, et al. 2024. DiscoTope-3.0: improved B-cell epitope prediction using inverse folding latent representations. Frontiers in Immunology 15:1322712.
• Jespersen MC, Peters B, Nielsen M, Marcatili P. 2017. BepiPred-2.0: improving sequence-based B-cell epitope prediction using conformational epitopes. Nucleic Acids Research 45(W1):W24-W29.
• Kringelum JV, Lundegaard C, Lund O, Nielsen M. 2012. Reliable B cell epitope predictions: impacts of method development and improved benchmarking (DiscoTope-2.0). PLoS Computational Biology 8(12):e1002829.
• Ponomarenko J, Bui HH, Li W, et al. 2008. ElliPro: a new structure-based tool for the prediction of antibody epitopes. BMC Bioinformatics 9:514.
• Stranzl T, Larsen MV, Lundegaard C, Nielsen M. 2010. NetCTLpan: pan-specific MHC class I pathway epitope predictions. Immunogenetics 62(6):357-368.
• Reynisson B, Alvarez B, Paul S, Peters B, Nielsen M. 2020. NetMHCpan-4.1 and NetMHCIIpan-4.0. Nucleic Acids Research 48(W1):W449-W454.
• Calis JJA, Maybeno M, Greenbaum JA, et al. 2013. Properties of MHC class I presented peptides that enhance immunogenicity. PLoS Computational Biology 9(10):e1003266.
• Bui HH, Sidney J, Li W, Fusseder N, Sette A. 2007. Development of an epitope conservancy analysis tool. BMC Bioinformatics 8:361.

Related Skills

• immunoinformatics/mhc-binding-prediction - T-cell (CD8) epitope prediction reduces to class I presentation
• immunoinformatics/mhc-class-ii-prediction - T-cell (CD4) epitopes; the class II presentation regime
• immunoinformatics/immunogenicity-scoring - ranking epitope candidates by likely T-cell response
• structural-biology/alphafold-predictions - fold an antigen with AlphaFold to enable DiscoTope-3.0
• database-access/entrez-fetch - retrieve antigen sequences/structures for epitope mapping