Creating Custom Benchmarks#

This guide explains how to define, curate, calibrate, and register a new target system in mockdock.

Step 1: Create the Benchmark TOML#

Add a new configuration file at src/mockdock/configs/<BenchmarkName>.toml:

benchmark_name = "MyTarget"
pdb_id = "1ABC"
target_id = "CHEMBL1234"
doc_id = "CHEMBL5678"
assay_id = "CHEMBL9012"
ligand_resname = "LIG"
fragment_smiles = "c1ccccc1"
fragment_smiles_with_dummies = "*c1ccccc1"
require_fragment_match = true
require_pose_rmsd = true
filter_during_optimization = true
clip_reward_upper_bound = true
low_score = -6.00     # Calibrated in Step 4
high_score = -11.50   # Calibrated in Step 4
rmsd_threshold = 2.0

Step 2: Curate Bioactivity Data#

Save the reference bioactivity dataset to src/mockdock/bioactivity_data/<BenchmarkName>.csv.

Required columns:

  • molecule_chembl_id: ChEMBL compound identifier.

  • canonical_smiles: Standardized SMILES string.

  • pchembl_value: Experimental affinity measurement (\(-\log_{10} \text{IC}_{50}\) / \(K_i\)).

Step 3: Prepare Docking Grids & Crystal Ligand#

Place pre-computed AutoGrid files in src/mockdock/grids/<PDB_ID>/:

  • <PDB_ID>.maps.fld: Grid definition field file.

  • Associated atom map files (.C.map, .A.map, .OA.map, .e.map, .d.map, etc.).

  • <PDB_ID>_ligand_corrected.sdf: Cleaned crystal ligand SDF with correct bond orders.

Alternatively, if receptor tools are installed (pip install -e ".[receptor]"), mockdock can fetch and prepare the receptor PDB from the RCSB PDB using ReceptorPreparer.

Step 4: 5-Fold Variance Calibration#

Run the variance calibration script across 5 independent seeds to calibrate docking energy distributions and correlation with experimental bioactivity:

python scripts/variance/run_variance.py \
  --config src/mockdock/configs/MyTarget.toml \
  --run-dir variance_runs/MyTarget \
  --output-dir variance_analysis/MyTarget \
  --n-iters 5

This generates:

  • docking_vs_activity.png: Pearson, Spearman, and \(R^2\) correlation between docking scores and experimental \(\text{pChEMBL}\) values.

  • rmsd_distribution.png: Distribution of fragment overlay RMSDs.

  • Baseline energy statistics (\(\text{low\_score}\) and \(\text{high\_score}\)).

Step 5: Set Calibration Bounds#

Update low_score and high_score in src/mockdock/configs/<BenchmarkName>.toml using the 5x variance calibration results. Once saved, the new target benchmark is immediately available via MDOracle("MyTarget").