Drug Pocket Detection

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 to produce a docking box, then run drug-docking-vina.

Choosing a Backend

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 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)

${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)

${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:

${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:

{
  "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 }
    }
  ]
}

Schema differences by backend:

• bounding_box: only fpocket reports one (computed from alpha-sphere positions). null for P2Rank.
• volume_a3: only fpocket reports volume; null for P2Rank.
• residue_source: P2Rank pockets carry this extra field, set to "p2rank" when residues come from the predictions CSV residue_ids column or "geometric_shell" when the script falls back to a distance shell around the reported center.
• druggability_score: for fpocket, the logistic-regression druggability score from Schmidtke & Barril (2010); for P2Rank, the calibrated per-pocket ligandability probability. The two are not numerically comparable across backends. fpocket's separate underlying pocket score (PLS-derived, Le Guilloux et al. 2009) is exposed as fpocket_score.

Druggability score: practical rule of thumb (fpocket logistic regression):

The broad qualitative interpretation (>0.5 promising, ~0 unlikely) is from fpocket's own documentation, building on Schmidtke & Barril (2010). The 0.2 intermediate cutoff is a workflow heuristic and not a calibrated decision boundary. The logistic-regression model has been retrained since the original publication, and performance is structure- and pocket-shape-dependent.

Sanity checks before committing to a pocket:

• The pocket center should lie inside the protein, not on the surface or in bulk solvent. Use visualize_pockets.py (next step).
• For known targets, cross-reference the lining residues against literature (catalytic residues, mutagenesis hits, conserved motifs). If none of those appear in the top pocket's residue list, you are probably looking at a decoy pocket.
• If the top fpocket pocket has a very small volume (< 200 A^3), it may be too small for typical drug-like ligands. Check the second-ranked pocket too.

5. Visualize the top pockets

${CLAUDE_SKILL_DIR}/../../venv/run cpu+pymol python ${CLAUDE_SKILL_DIR}/scripts/visualize_pockets.py \
  --protein receptor_prepared.pdb \
  --pockets pockets.json \
  --top_n 3 \
  --output pockets_vis.png

Renders the protein as a transparent cartoon, draws a colored sphere at each pocket center labeled P1, P2, P3, and shows the lining residues as sticks colored to match their pocket. Always inspect the image before moving on; the highest-ranked pocket geometrically is not always the biologically relevant one.

6. Hand off to docking

Convert the chosen pocket into a docking-box JSON consumable by the downstream skills:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/pocket_to_box.py \
  --pockets pockets.json \
  --rank 1 \
  --padding 6.0 \
  --min_size 20.0 \
  --output_json binding_site.json

The resulting binding_site.json matches the schema produced by drug-binding-site-definition and can be passed directly to drug-docking-vina. The recorded sizing_strategy field tells you which heuristic was used:

• bounding_box: per-axis min/max from fpocket alpha-sphere positions plus padding. Most faithful for elongated / clefted pockets - they keep their shape rather than being forced into a cube.
• volume_sphere: equivalent-sphere radius from volume_a3, then a cubic box. Used when no bounding box is available.
• default_size: fixed cubic edge (--default_size, default 22 A). Used for P2Rank pockets, which report neither a bounding box nor a volume.

If you instead prefer to define the box from the pocket's residue list (rather than from its center + extent), grab the residues[*].label strings from the JSON and feed them into binding-site-definition Mode B. This is often the right choice for long grooves and interface pockets.