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

Decision Tree by Scenario

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.