drug-pocket-detection

Files (9)

• SKILL.md
• 1HSG_protein.pdb · examples/hiv1-protease/
• README.md · examples/hiv1-protease/
• binding_site_from_pocket.json · examples/hiv1-protease/
• pockets_fpocket.json · examples/hiv1-protease/
• pockets_visualization.png · examples/hiv1-protease/
• detect_pockets.py · scripts/
• pocket_to_box.py · scripts/
• visualize_pockets.py · scripts/

SKILL.md (first lines)

# drug-pocket-detection

## Goal

Take a protein structure (experimental or predicted) and produce a ranked list
of candidate ligandable pockets, each described by:

- A unique pocket id and rank
- A geometric center (x, y, z in Angstroms)
- An estimated volume (A^3)
- A druggability score (fpocket: logistic-regression model from Schmidtke & Barril 2010, layered on top of fpocket's own PLS-derived pocket score from Le Guilloux et al. 2009; P2Rank: a calibrated per-pocket ligandability probability)
- The lining residues (chain, resnum, resname, one-letter)
- Backend-specific raw metrics (hydrophobicity, polarity, alpha-sphere counts,
  etc.) preserved for provenance

This skill **does not** perform docking. Once you have selected a pocket, feed its center into [drug-binding-site-definition](../drug-binding-site-definition/SKILL.md) to produce a docking box, then run [drug-docking-vina](../drug-docking-vina/SKILL.md).

## Choosing a Backend

| Backend | When to use | Strengths | Weaknesses |
|---|---|---|---|
| **fpocket** (default) | First pass on any structure; lightweight (no Java, no large model file) | Fast; well-cited logistic-regression druggability score (Schmidtke & Barril 2010) layered on the underlying PLS pocket score (Le Guilloux et al. 2009); deterministic given the same parameters but slightly sensitive to floating-point details across builds | Pure geometry; misses cryptic pockets that lack a clear cavity in the input conformation |
| **P2Rank** | Independent ML pocket prediction, especially when geometry alone is ambiguous (shallow / surface pockets) or for predicted structures via the `alphafold` profile | Often higher Top-1 accuracy on benchmarks (Krivak & Hoksza 2018); residue-aware ML; reports adjacent residues directly | Heavier install (separate Java runtime + downloaded model); does not report pocket volume |

Run **both** if a decision is load-bearing (e.g., you only get one shot at MD). Compare the top-3 of each; consensus picks are stronger.

## Instructions

### 1. Prepare the protein

Prepare inputs explicitly: strip unwanted waters, buffer ions, and ligands; keep cofactors / metals only when biologically required. The
[drug-protein-prep](../drug-protein-prep/SKILL.md) skill produces a suitable input. Do not rely on backend HETATM handling as a substitute for careful preparation becuase fpocket strips many non-cofactor HETATMs but keeps a fixed cofactor set, and P2Rank's HETATM behavior should be re-validated for the installed version. Crystallographic waters / buffer ions left in the input will bias the geometry and produce decoy pockets.

### 2. Detect pockets with fpocket (default)

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/detect_pockets.py \
  --protein receptor_prepared.pdb \
  --backend fpocket \
  --top_n 10 \
  --output_json pockets.json
```

Optional fpocket knobs (passed through to the underlying CLI; unset means fpocket's compiled-in default applies):

- `--fp_min_radius`, `--fp_max_radius`: bounds on alpha-sphere radii. Lower
  the minimum (e.g., 2.8) to detect tighter pockets; raise the maximum
  (e.g., 7.0) for shallow / surface pockets.
- `--fp_min_clust_radius`: clustering distance for alpha spheres. Lowering
  it splits one large pocket into several smaller ones.
- `--residue_cutoff` (default 5.0 A): radius around alpha-sphere centers
  used to define lining residues.

The defaults have drifted across releases and you should not assume they match what you read anywhere. Concretely, three sources can disagree at once:

- The **published 2009 paper** (Le Guilloux et al.) lists `-m 3.0`, `-M 6.0`, `-i 35`.
- The **current master-branch source** (`headers/fparams.h`) defines `M_MIN_ASHAPE_SIZE_DEFAULT 3.4`, `M_MAX_ASHAPE_SIZE_DEFAULT 6.2`, `M_MIN_POCK_NB_ASPH 15`.
- The **`fpocket -h` text** in fpocket 4.x typically shows yet another set (e.g., `(3.0)`, `(6.0)`, `(30)` for `-i`).

`-D 2.4` for the clustering distance is the consistent value in modern
4.x source and help. Because of this drift, the script never assumes a
default and always records the exact command line in the output JSON
(`backend_command`); reproducing a result requires keeping that line.

### 3. Detect pockets with P2Rank (optional ML backend)

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/detect_pockets.py \
  --protein receptor_prepared.pdb \
  --backend p2rank \
  --top_n 10 \
  --output_json pockets_p2rank.json
```

For predicted structures (AlphaFold, NMR, cryo-EM) use the dedicated profile, which avoids relying on B-factor as a feature:

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/detect_pockets.py \
  --protein af_model.pdb \
  --backend p2rank \
  --p2rank_config alphafold \
  --output_json pockets_p2rank.json
```

P2Rank is not a Python package: install the `prank` CLI separately (see **Constraints**) and ensure it is on `PATH`. Visualization files are disabled by default (`-visualizations 0`) to keep runs fast; pass `--p2rank_visualizations` if you want them written.

### 4. Inspect and pick a pocket

The output JSON has this schema:

```json
{
  "protein": "/abs/path/receptor_prepared.pdb",
  "backend": "fpocket",
  "backend_version": "4.0",
  "backend_command": ["/abs/path/fpocket", "-f", "..."],
  "n_pockets": 5,
  "residue_cutoff_a": 5.0,
  "pockets": [
    {
      "rank": 1,
      "id": "pocket_1",
      "fpocket_index": 1,
      "druggability_score": 0.93,
      "fpocket_score": 38.2,
      "volume_a3": 612.3,
      "n_alpha_spheres": 78,
      "hydrophobicity_score": 32.4,
      "polarity_score": 13,
      "center": {"x": 14.2, "y": 24.3, "z": 5.9},
      "bounding_box": {"min": [4.0, 16.0, -3.0], "max": [24.0, 32.0, 15.0]},
      "residues": [
        {"chain": "A", "resnum": 25, "resname": "ASP", "icode": "",
         "one_letter": "D", "label": "A:ASP25"},
        "..."
      ],
      "n_residues": 24,
      "raw_metrics": { "...all fpocket info fields...": null }
    }

From learningmatter-mit/AtomisticSkills, MIT.

More from learningmatter-mit/AtomisticSkills