drug-binding-site-definition

Files (10)

• SKILL.md
• 1HSG_protein.pdb · examples/hiv1-protease/
• 1HSG_raw.pdb · examples/hiv1-protease/
• MK1_ligand.pdb · examples/hiv1-protease/
• README.md · examples/hiv1-protease/
• binding_site_ligand.json · examples/hiv1-protease/
• binding_site_residues.json · examples/hiv1-protease/
• box_visualization.png · examples/hiv1-protease/
• define_binding_site.py · scripts/
• visualize_box.py · scripts/

SKILL.md (first lines)

# 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](../drug-docking-vina/SKILL.md) and [drug-complex-system-builder](../drug-complex-system-builder/SKILL.md) 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:

```bash
${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):

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

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

```json
{
  "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:

```bash
${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.

From learningmatter-mit/AtomisticSkills, MIT.

More from learningmatter-mit/AtomisticSkills