/by-epitope-analysis

id: "skill_1e4ec544986d41da9964c6db5f309c53"
name: "by-epitope-analysis"
display-name: "BY Epitope Analysis"
short-description: "Interface identification, residue classification, and hotspot scoring for protein and antibody binder design. Use when selecting hotspot residues for PXDesign or BoltzGen input from a co-crystal structure."
category: "research"
keywords: "epitope, hotspot, interface, contact analysis, PDB, druggability, pocket, design input"
version: "1.0"
last-updated: "2026-05-20"
mcp_tools: ["mcp__by-pdb__pdb_search", "mcp__by-pdb__pdb_get_chains", "mcp__by-pdb__pdb_download", "mcp__by-pdb__pdb_interface_residues"]

Skill: BY Epitope Analysis

You are an expert structural biologist performing epitope analysis and hotspot residue selection for protein and antibody binder design. This skill covers interface identification, residue classification, hotspot scoring, druggability assessment, and producing residue selections for PXDesign or BoltzGen input.

---

When to Use This Skill

Use this skill when you need to:

• ✅ Convert a co-crystal structure into a hotspot residue list for PXDesign / BoltzGen
• ✅ Classify and score interface residues from a target+binder PDB entry
• ✅ Decide whether an epitope is concave/convex/flat and pick a design tool accordingly
• ✅ Assess druggability of an epitope for biologics
• ✅ Refine an epitope selection produced by `by-research` before committing to design

**Don't use this skill for:**

• ❌ Sequence-only target analysis with no structure → use `by-research` to find a structure first
• ❌ Picking PDB entries from a target name → use `mcp__by-pdb__pdb_search` directly
• ❌ Predicting structures from sequence → use Protenix (see `protenix` skill)
• ❌ Liability scanning (CDR loops, developability) → use `by-screening`

---

Quick Start

Run the hotspot selection script on a downloaded PDB with chain assignments:

python scripts/select_hotspots.py \
  --pdb /tmp/5JXE.cif \
  --target-chain A \
  --binder-chains H,L \
  --cutoff 5.0 \
  --top-n 6 \
  --out /tmp/hotspots.json

Expected output:

✓ Loaded structure 5JXE
✓ Interface residues detected: 18 (cutoff 5.0 A)
✓ Ranked 18 candidates; selected 6 hotspots
✓ Wrote /tmp/hotspots.json

The JSON contains a ranked list of `{chain, resseq, resname, score, classification, rationale}` plus a `range_notation` string ready to paste into BoltzGen entity YAML.

---

Installation

| Software | Version | License | Commercial Use | Installation Command | |----------|---------|---------|----------------|---------------------| | Python | ≥3.9 | PSF | ✅ Permitted | preinstalled | | BioPython | ≥1.81 | Biopython License | ✅ Permitted | `pip install biopython` | | NumPy | ≥1.24 | BSD-3 | ✅ Permitted | `pip install numpy` |

**License Compliance:** All packages permit commercial use in AI applications.

**System requirements:** No GPU. ~50 MB RAM per structure. Network only required if downloading PDB entries (the script accepts a local CIF/PDB path).

---

Inputs

**Required:**

• **Structure file** (CIF or PDB): co-crystal of target + binder
• Resolution < 3.0 A strongly preferred; flag entries > 3.5 A
• Single biological assembly (run `pdb_get_chains` to confirm chain labels)
• **Target chain ID** (e.g., `A`): the antigen
• **Binder chain ID(s)** (e.g., `H,L` for Fab, `H` for VHH): the existing binder

**Alternative inputs:**

• **PDB ID** (e.g., `5JXE`): fetched via `mcp__by-pdb__pdb_download` before analysis
• **Pre-computed interface JSON** from `mcp__by-pdb__pdb_interface_residues`: skips

the structural pass and goes straight to scoring

**Optional:**

• **Distance cutoff** (default 5.0 A): see Decision Points
• **Top-N** (default 6): how many hotspots to return
• **Exclude residues**: glycosylation sites, mutation-sensitive positions

See `references/hotspot-scoring.md` for the full scoring rubric and threshold guidance.

---

Outputs

**Primary results** (written to `--out` path):

• `hotspots.json`:

  {
    "pdb_id": "5JXE",
    "target_chain": "A",
    "binder_chains": ["H", "L"],
    "cutoff_a": 5.0,
    "interface_size_a2": 1080.0,
    "topology": "flat",
    "druggability": "moderate",
    "hotspots": [
      {"chain": "A", "resseq": 56, "resname": "TYR", "score": 0.91,
       "classification": "polar_anchor", "rationale": "Aromatic + H-bond, buried at 4.0 A"}
    ],
    "range_notation": "A54,A56,A58,A61,A63,A68",
    "boltzgen_binding": "54,56,58,61,63,68",
    "pxdesign_hotspots": [54, 56, 58, 61, 63, 68]
  }

**Reports:**

• Console summary table (residue, score, classification, rationale)
• Topology + druggability classification with recommended design tool

**Downstream-ready formats:**

• `boltzgen_binding` string ready to drop into entity YAML `binding:` field
• `pxdesign_hotspots` int list ready for PXDesign target YAML

---

Clarification Questions

**⚠️ CRITICAL: ASK THIS FIRST.** Always confirm the user has a co-crystal structure or a justified single-chain target before proceeding.

1. **Structure available?** (ASK THIS FIRST)

• Do you have a co-crystal PDB ID, a local CIF/PDB file, or only a sequence?
• If sequence-only: route to `by-research` to find a structure first.

2. **Target identity:** Which chain is the antigen vs the binder? (We need both labels — `pdb_get_chains` returns chain composition.) 3. **Resolution check:** Is the structure < 3.0 A? Cryo-EM acceptable above 3.0 A only if the interface region is well-resolved. See `references/interface-classification.md`. 4. **Design modality:** PXDesign (de novo binder) vs BoltzGen (antibody/nanobody)? This affects how many hotspots to recommend and whether to prefer concave epitopes. 5. **Constraints:** Any residues to exclude (e.g., known glycosylation sites, essential function residues, prior mutational dead spots)? 6. **Interface scope:** Strict contacts only (4.0 A) or extended packing (6.0 A)? Default 5.0 A balances both. See Decision Points. 7. **P