drug-docking-vina

Files (10)

• SKILL.md
• README.md · examples/hiv1_protease/
• 1HSG_prepared.pdb · examples/hiv1_protease/inputs/
• 1HSG_prepared.pdbqt · examples/hiv1_protease/inputs/
• indinavir.pdbqt · examples/hiv1_protease/inputs/indinavir/
• docking_results.json · examples/hiv1_protease/output/
• indinavir_docked.pdbqt · examples/hiv1_protease/output/
• collect_results.py · scripts/
• compute_box_from_pdbqt.py · scripts/
• run_docking.py · scripts/

SKILL.md (first lines)

# docking-vina

## Goal
To perform molecular docking of one or more small-molecule ligands into a protein receptor using **AutoDock Vina (>= 1.2.x)** via its **Python API**, producing:
- Ranked binding poses (PDBQT)
- Docking scores (kcal/mol) and pose RMSDs
- A machine-readable JSON report with full docking parameters for reproducibility

This skill is intended for **pose generation and relative ranking**, not rigorous binding free energy prediction. Please refer to the original Vina method (Trott & Olson, https://doi.org/10.1002/jcc.21334) and the AutoDock Vina repo (https://github.com/ccsb-scripps/AutoDock-Vina) for more details.

## Instructions

### 1. Prepare receptor and ligand (recommended)
Docking accuracy is strongly affected by **structure preparation** (protonation, missing residues, cofactors, waters, tautomer states, etc.). Use:
- [protein-prep](../drug-protein-prep/SKILL.md) to generate `*_prepared.pdbqt`
- [ligand-prep](../drug-ligand-prep/SKILL.md) to generate ligand `*.pdbqt` (consider multiple protomers/tautomers)

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu+openmm python ${CLAUDE_SKILL_DIR}/../drug-protein-prep/scripts/prepare_protein.py \
  --pdb_id 1HSG \
  --heterogens none \
  --missing_residues ignore \
  --output_dir docking/inputs/

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/../drug-ligand-prep/scripts/prepare_ligand.py \
  --smiles "CC(=O)Oc1ccccc1C(=O)O" \
  --name aspirin \
  --output_dir docking/inputs/
```

**Best practice:** if you have a co-crystal ligand, keep it as a positive control for redocking validation.

### 2. Define the docking search box (center + size)

You must define the docking region. The most common approaches:

* **Redocking / known pocket:** center on the co-crystallized ligand
* **Known active site residues:** center on key catalytic residues
* **Blind docking:** large box spanning the protein (slower and less reliable, so use cautiously)

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

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/compute_box_from_pdbqt.py \
  docking/inputs/reference_ligand.pdbqt \
  --padding 6.0 \
  --min_size 20.0 \
  --output_json docking/inputs/docking_box.json
```

This writes `center_x/y/z` and `size_x/y/z` you can paste into the docking command.

### 3. Run docking (single ligand)

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu+docking python ${CLAUDE_SKILL_DIR}/scripts/run_docking.py \
  --receptor docking/inputs/1HSG_prepared.pdbqt \
  --ligand docking/inputs/aspirin.pdbqt \
  --center_x 16.0 --center_y 25.0 --center_z 2.0 \
  --size_x 20 --size_y 20 --size_z 20 \
  --scoring vina \
  --exhaustiveness 32 \
  --n_poses 10 \
  --energy_range 3.0 \
  --min_rmsd 1.0 \
  --seed 42 \
  --cpu 0 \
  --output_dir docking/results/
```

Outputs:

* `docking/results/aspirin_docked.pdbqt`
* `docking/results/docking_results.json`

### 4. Run docking (batch mode / virtual screening)

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu+docking python ${CLAUDE_SKILL_DIR}/scripts/run_docking.py \
  --receptor docking/inputs/1HSG_prepared.pdbqt \
  --ligand_dir docking/inputs/ligands_pdbqt/ \
  --center_x 16.0 --center_y 25.0 --center_z 2.0 \
  --size_x 20 --size_y 20 --size_z 20 \
  --scoring vina \
  --exhaustiveness 16 \
  --n_poses 5 \
  --seed 42 \
  --cpu 0 \
  --output_dir docking/screening_results/
```

**Tip:** for batch docking, the script will compute Vina maps once (before loading ligands) to reduce repeated setup overhead.

### 5. Collect results into a ranked CSV

`run_docking.py` writes a machine-readable JSON that is good for reproducibility but not directly consumable by downstream analysis tools (such as [drug-docking-analysis](../drug-docking-analysis/SKILL.md)). Use `collect_results.py` to produce a ranked CSV that joins the docking scores with library metadata (SMILES, labels, microstate/parent IDs).

```bash
# (stdlib only, venv/cpu project works)

# Combined JSON from run_docking.py
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/collect_results.py \
  --results docking/results/docking_results.json \
  --library_csv library/library_master.csv \
  --output_dir docking/analysis/

# Or a directory of per-ligand *_result.json files (SLURM array workflows)
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/collect_results.py \
  --results docking/results/ \
  --library_csv library/library_master.csv \
  --output_dir docking/analysis/
```

**Library CSV requirements:** must have a `compound_id` column. The `compound_id` value must match the `ligand` field in the docking JSON, which is the PDBQT filename stem set by `drug-ligand-prep` (e.g. `indinavir.pdbqt` -> `indinavir`). Any of these columns, when present, are passed through to the ranked CSV and are picked up by downstream analysis tools:
- `smiles` (used by `drug-docking-analysis` for ligand efficiency metrics)
- `label` (used for retrospective enrichment)
- `parent_compound_id` and `microstate_id` (used for microstate aggregation when protomers/tautomers were enumerated during ligand prep)
- `pchembl` (passed through for reference)

From learningmatter-mit/AtomisticSkills, MIT.

More from learningmatter-mit/AtomisticSkills