This skill predicts protein-ligand binding affinity from docked poses — converting structural information into estimated ΔG (kcal/mol), pKd, and Kd (nM). It complements the molecular-docking skill's interaction analysis (score.py) which counts contacts but does NOT predict binding strength in energy units.
Key capabilities:
Empirical scoring: descriptor + contact-based affinity prediction using RDKit and BioPython
MM/GBSA rescoring: physics-based energy decomposition with OpenMM (or RDKit fallback)
Consensus scoring: combine multiple scoring methods with rank-based normalization
Batch virtual screening: efficiently score large compound libraries
Validation Warning
All predictions from this skill are computational estimates, NOT experimentally validated measurements.
Empirical scoring (predict.py): typical error is 1-2 log units pKd (~10-100x in Kd)
MM/GBSA rescoring: useful for relative ranking, not absolute binding energies
Use for prioritizing compounds for experimental testing, not for making clinical claims
The scripts include uncertainty ranges and confidence flags to help calibrate expectations.
Output Integrity
Script outputs are RAW computational estimates. The agent MUST NOT:
Apply "calibration" or scaling to raw pKd/Kd values
Adjust values to match known experimental data
Add fields like "calibrated_pKd" not produced by the script
Present approximate methods (simplified MM/GBSA) as full implementations
The raw output IS the prediction. Report it exactly as produced.
All script invocations are automatically logged to _script_manifest.jsonl. The critique
agent uses this manifest to verify that every number in the final report traces to a real
script output.
When to Use This Skill
Use the binding-affinity skill when you need to:
Predict how tightly a ligand binds to a protein (after docking)
Rank docked poses by estimated binding affinity
Rescore poses using physics-based MM/GBSA energy decomposition
Screen compound libraries for binding potential
Combine multiple scoring methods into a consensus ranking
Trigger phrases: "predict binding affinity", "estimate Kd", "score binding strength", "rescore with MM/GBSA", "rank compounds by affinity", "virtual screening"
Free energy perturbation (requires specialized MD simulations)
Related Skills
molecular-docking: Generate docked poses first. This skill scores them.
pocket-detection: Find binding pockets before docking.
admet-prediction: Filter affinity hits by drug-likeness and safety.
Installation
Required Dependencies
# Core (required for all modes)
pip install rdkit-pypi biopython numpy scipy
Optional Dependencies
# MM/GBSA rescoring (full physics-based path)
pip install openmm openmmforcefields openff-toolkit
# If OpenMM is not available, rescore.py falls back to RDKit MMFF
{"protein":"protein.pdb","method":"descriptor","n_poses":5,"note":"Empirical estimate. Typical error: 1-2 log units pKd (~10-100x in Kd). Use for relative ranking only.","predictions":[{"pose_id":1,"pose_name":"ligand_pose_1","predicted_pKd":7.2,"pKd_uncertainty":1.5,"pKd_range":[5.7,8.7],"predicted_dG_kcal":-9.8,"predicted_Kd_nM":60,"confidence":"moderate","features":{"mw":342.4,"logp":2.1,"n_hbonds":4,"n_hydrophobic":12,"burial_fraction":0.65}}]}
Critical: These are computational estimates with ~1-2 log unit uncertainty. A predicted pKd of 7.2 means the true value is likely somewhere between 5.7 and 8.7 (Kd between ~2 nM and 2 uM).
Confidence Levels
Level
Criteria
Meaning
High
MW 200-600, LogP -1 to 5, >30 contacts
Within training domain, estimate more reliable
Moderate
Partially within domain
Use with caution
Low
MW <200 or >600, extreme LogP, few contacts
Outside training domain, estimate unreliable
MM/GBSA Energies
More negative = stronger predicted binding
Useful for relative ranking within a series, not absolute binding energies
ΔG_MMGBSA does NOT equal experimental ΔG_binding (missing entropy, sampling)
Troubleshooting
All poses get similar scores: The ligands may be too similar, or the scoring function may not discriminate well for this target class.
Negative confidence: Check if molecules are drug-like (MW 200-600, LogP -1 to 5). Non-drug-like molecules get unreliable scores.
OpenMM not available: rescore.py falls back to RDKit MMFF energies. Install OpenMM for better physics-based scoring.
Very large library (>10K molecules): Use batch.py with --threshold to filter early.
References
Wang, R. et al. "The PDBbind database." J. Med. Chem. 47, 2977-2980 (2004).
Ballester, P.J. & Mitchell, J.B.O. "A machine learning approach to predicting protein-ligand binding affinity." Bioinformatics 26, 1169-1175 (2010).
Hou, T. et al. "Assessing the performance of the MM/PBSA and MM/GBSA methods." J. Chem. Inf. Model. 51, 69-82 (2011).
Li, H. et al. "Improving AutoDock Vina Using Random Forest." J. Chem. Inf. Model. 55, 1291-1299 (2015).
