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](../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)

# Env: drugdisc-agent
python .agents/skills/drug-pocket-detection/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)

# Env: drugdisc-agent
python .agents/skills/drug-pocket-detection/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:

python .agents/skills/drug-pocket-detection/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):

| Score | Action | |---|---| | > 0.5 | Worth prioritizing; fpocket docs flag this as the threshold for "chance to find drug-like molecules" | | 0.2 - 0.5 | Gray zone: inspect manually and cross-check against biology | | 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 (/ subdirectory; the script searches recursively, but make sure prank actually completed successfully (look for *.pdbpredictions.csv somewhere under your --workdir`).
• All pockets sit on the surface, none in the active site: Likely cause: a co-crystal ligand or cofactor was removed but its space is now empty and geometrically unfavored. Either keep the cofactor in (if it is a permanent partner), or run on a holo conformation if available.

Constraints

• Environment: drugdisc-agent.
• Python deps: numpy, MDAnalysis (already in drugdisc-agent).
• External CLI tools (one of):
• fpocket 4.x via conda-forge. Add to drugdisc-agent with mamba install -n drugdisc-agent -c conda-forge fpocket.
• prank (P2Rank) from https://github.com/rdk/p2rank/releases. Current P2Rank requires Java 17+ (tested up to Java 25). Very old releases (2.3 and earlier) supported Java 11+; only relevant if you are pinning to a legacy version.
• Input: PDB (preferred) or any format MDAnalysis can read for residue extraction. fpocket itself accepts PDB and mmCIF.
• Pure geometry / ML on a single conformer: cryptic pockets are missed by design. Use trajectory ensembles to detect those.
• No conservation, no template-based detection: the description mentions templates and conservation as conceptual inputs, but those signals are not computed here; they should be layered on post-hoc by intersecting with the reported residue lists.

References

• Le Guilloux, V.; Schmidtke, P.; Tuffery, P. Fpocket: An Open Source Platform for Ligand Pocket Detection. BMC Bioinformatics 2009, 10, 168. https://doi.org/10.1186/1471-2105-10-168
• Schmidtke, P.; Barril, X. Understanding and Predicting Druggability. A High-Throughput Method for Detection of Drug Binding Sites. J. Med. Chem. 2010, 53, 5858-5867. https://doi.org/10.1021/jm100574m
• Krivak, R.; Hoksza, D. P2Rank: Machine Learning Based Tool for Rapid and Accurate Prediction of Ligand Binding Sites from Protein Structure. J. Cheminform. 2018, 10, 39. https://doi.org/10.1186/s13321-018-0285-8
• Cimermancic, P.; et al. CryptoSite: Expanding the Druggable Proteome by Characterization and Prediction of Cryptic Binding Sites. J. Mol. Biol. 2016, 428, 709-719. https://doi.org/10.1016/j.jmb.2016.01.029

---

Author: Matthew Cox Contact: GitHub @mcox3406

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: learningmatter-mit
• Source: learningmatter-mit/AtomisticSkills
• License: MIT
• Homepage: https://arxiv.org/abs/2605.24002

Install and usage instructions live in the source repository linked above.