Drug Binding Site Definition

drug-binding-site-definition

Goal

To produce a standardized docking / simulation box definition (center coordinates + box dimensions in Angstroms) that downstream skills such as drug-docking-vina and drug-complex-system-builder can consume directly.

Choosing the Right Mode

Use this decision tree to pick the appropriate approach:

Do you have a reference ligand positioned in the binding site?
  |-- YES --> Mode A (co-crystal ligand)
  |-- NO
       Do you know the key binding-site residues (from literature, mutagenesis, etc.)?
         |-- YES --> Mode B (residue list)
         |-- NO
              Do you have a closely related protein with a known binding site?
                |-- YES --> Superimpose structures, transfer the ligand,
                |           then use Mode A on the transferred ligand.
                |           (See "When You Have No Binding-Site Information" below.)
                |-- NO  --> Run computational pocket prediction first
                            (see "When You Have No Binding-Site Information" below),
                            then feed results into Mode A or B.

If you already have a saved box JSON from a prior run, use Mode C to reload it.

Instructions

1. Mode A: Box from a co-crystal ligand (most common)

If you have a reference ligand already positioned in the binding site (PDB, SDF, MOL2, or PDBQT), compute the box automatically:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/define_binding_site.py \
  --mode ligand \
  --ligand_file docking/inputs/reference_ligand.sdf \
  --padding 6.0 \
  --min_size 20.0 \
  --output_json docking/inputs/binding_site.json

Key parameters:

• --padding: buffer added to the ligand bounding box on each side (default 6.0 A). Use 4-5 A for tight/buried pockets, 8-10 A for shallow or allosteric sites.
• --min_size: minimum box edge length per axis (default 20.0 A).

The ligand must be in the same coordinate frame as the receptor. If it comes from a different crystal structure, superimpose first.

2. Mode B: Box from binding-site residues

When no co-crystal ligand is available but you know the key binding-site residues (e.g., from literature or mutagenesis data):

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/define_binding_site.py \
  --mode residues \
  --protein_file protein_prepared.pdb \
  --residues "A:ASP25,A:THR26,A:GLY27,A:ILE50,A:ASP124,A:THR125,A:GLY126" \
  --padding 8.0 \
  --min_size 20.0 \
  --output_json docking/inputs/binding_site.json

Residue format: comma-separated chain:resname+resid (e.g., A:ASP25). You can omit the chain prefix (e.g., 25,26,27,50) only if the protein contains a single chain; for multi-chain structures always include the chain ID to avoid ambiguity.

3. Mode C: Load a saved box definition

Re-use a previously computed box:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/define_binding_site.py \
  --mode json \
  --input_json docking/inputs/binding_site.json

This validates the JSON and prints the box to stdout for inspection.

4. Interpret and validate the output

The output JSON has the following schema:

{
  "center_x": 16.0,
  "center_y": 25.0,
  "center_z": 2.0,
  "size_x": 22.0,
  "size_y": 24.0,
  "size_z": 20.0,
  "padding": 6.0,
  "min_size": 20.0,
  "mode": "ligand",
  "source": "reference_ligand.sdf"
}

All coordinates and dimensions are in Angstroms.

Always verify that the box covers the expected pocket before docking. If PyMOL is available, use the included visualization script to render the box as a wireframe overlay:

${CLAUDE_SKILL_DIR}/../../venv/run cpu+pymol python ${CLAUDE_SKILL_DIR}/scripts/visualize_box.py \
  --protein docking/inputs/protein_prepared.pdb \
  --box docking/inputs/binding_site.json \
  --ligand_resname MK1 \
  --output docking/inputs/box_visualization.png

This produces a ray-traced PNG showing the protein (cartoon), ligand (yellow sticks), and docking box (red wireframe). The --ligand_resname flag is optional; omit it if no ligand is present.

If no viewer is available, at minimum sanity-check that the box center falls near the expected pocket by comparing coordinates to known active-site residues in the PDB.

When You Have No Binding-Site Information

If you have a protein structure but no co-crystal ligand and no literature on binding-site residues, you need to identify candidate pockets before defining a docking box.

Homology-based site transfer

If a homologous protein (>30% sequence identity) has a co-crystal structure, superimpose your target onto the template and extract the ligand coordinates in your target's reference frame. Then use Mode A on the transferred ligand. This is often the most reliable approach when a good template exists.

Computational pocket prediction

Open-source tools can identify probable binding pockets from protein geometry alone:

• fpocket (recommended, lightweight): identifies pockets via Voronoi tessellation and alpha spheres. Run it, pick the top-ranked pocket, extract its residues, and feed them into Mode B.
• P2Rank: ML-based pocket predictor, often more accurate than fpocket on benchmarks.
• DoGSiteScorer: web-based alternative if local tools are not available.

Pocket prediction is a starting point, not ground truth. Always cross-reference predicted sites against any available functional data (conservation scores, mutagenesis, known mechanism) before committing to a docking box.

Blind docking (last resort)

If no structural or functional clues exist, you can define a box that covers the entire protein surface. This is computationally expensive and less reliable. To generate a whole-protein box, use Mode B with all surface residues, or manually set a large box (40-60 A per side) centered on the protein centroid. Treat blind docking results as hypothesis-generating, not definitive.

Special Considerations

• AlphaFold / predicted structures: These lack experimental ligand density and may have unreliable loop conformations near potential pockets. Use wider padding (8-10 A), cross-reference with pocket prediction tools, and check pLDDT confidence scores (regions with pLDDT < 70 near the pocket boundary are a red flag).
• Multiple binding sites: Many targets (kinases, GPCRs, allosteric enzymes) have more than one druggable pocket. Run the skill separately for each site, producing one JSON per pocket (e.g., binding_site_orthosteric.json, binding_site_allosteric.json).
• Covalent binding sites: Center the box on the reactive residue (e.g., a catalytic cysteine) using Mode B with that residue as the anchor, plus neighboring pocket residues. Use tighter padding (4-5 A).
• Oligomeric interface sites: Some binding sites span the interface between protein chains (e.g., the HIV-1 protease active site spans a homodimer interface). Make sure the input structure contains the full biological assembly, not just a single chain.
• Membrane proteins: For GPCRs, ion channels, and other membrane-embedded targets, the docking box may extend into the lipid bilayer region. Constrain the box to avoid the transmembrane region unless the binding site is intramembrane (e.g., some GPCR orthosteric sites).
• Flexible / cryptic pockets: Some pockets only form upon ligand binding or conformational change. A static docking box cannot capture these. Consider ensemble docking across multiple conformations (e.g., from MD snapshots) with separate box definitions for each conformer.