DockBot — docking¶
DockBot automates the molecular-docking workflow around AutoDock Vina: fetch a receptor, clean it, find the pocket, prepare the ligand, dock, score, and report.
Docking is the one stage of the pipeline that is genuinely expensive and genuinely network-dependent, and most of this page cannot be run as a doctest for that reason. What is offline is ligand preparation, and that is shown below.
The workflow¶
- Protein preparation — fetch from the PDB, strip waters and co-crystallised ligands, convert to PDBQT.
- Ligand preparation — SMILES → 3D conformer → MMFF94 minimisation → PDBQT.
- Binding-site detection — from a co-crystal ligand, from fpocket, or specified manually.
- Docking — AutoDock Vina, via its Python bindings or its CLI.
- Parallel screening — a multiprocessing pool over a compound library, resumable.
- Composite scoring — Vina affinity plus drug-likeness.
- Reporting — a self-contained HTML report with embedded 3D viewers.
Ligand preparation¶
This part needs nothing but RDKit and Meeko:
>>> from neorx.dockbot import prepare_ligand_pdbqt
>>> mol, pdbqt = prepare_ligand_pdbqt("CC(=O)Oc1ccccc1C(O)=O",
... name="aspirin")
>>> mol is not None
True
>>> pdbqt.splitlines()[0]
'REMARK SMILES CC(=O)Oc1ccccc1C(=O)O'
>>> "ATOM" in pdbqt
True
The five steps behind that one call: parse the SMILES to a 2D graph, add explicit hydrogens, generate a 3D conformer with ETKDG (Experimental-Torsion Knowledge Distance Geometry), relax it with the MMFF94 force field to remove steric clashes, then add partial charges and AutoDock atom types with Meeko. Explicit hydrogens are not optional — the force field needs them.
prepare_ligand stops at the RDKit Mol, and takes num_conformers
and max_iterations if you want more than one conformer or a longer
minimisation.
Protein preparation¶
Requires network
prepare_protein downloads from the RCSB PDB.
from neorx.dockbot import prepare_protein
protein = prepare_protein("1BNA")
print(protein.pdb_id, protein.resolution, protein.num_residues)
print(protein.removed_ligands)
print(protein.pdbqt_path)
Raw PDB files are crystallographic snapshots and contain artefacts that
interfere with docking. Waters (HOH) clutter the pocket and are
removed. Co-crystallised ligands occupy the pocket and must come out —
but their coordinates are the best available evidence for where the
pocket is, so they are recorded in removed_ligands on the way out
rather than discarded.
prepare_protein caches, so a repeated call for the same PDB ID does not
re-download; pass force=True to override.
Binding sites¶
>>> from neorx.dockbot import BindingSite, BindingSiteMethod
>>> [m.value for m in BindingSiteMethod]
['ligand', 'fpocket', 'manual']
>>> site = BindingSite(
... center_x=10.0, center_y=20.0, center_z=30.0,
... size_x=20.0, size_y=20.0, size_z=20.0,
... method=BindingSiteMethod.MANUAL,
... )
>>> site.method.value
'manual'
Vina needs a search box, and how you got the box matters for how much to trust the result:
ligand— a box centred on the co-crystal ligand's centre of mass, with padding. The gold standard when structural data exists.fpocket— geometric pocket detection, for an apo structure.manual— you supply the coordinates.
BindingSite.confidence and residues carry the detection's own
assessment and the lining residues.
Docking¶
Requires AutoDock Vina
Install with uv sync --extra docking, or have the vina binary on
PATH for the CLI path.
from neorx.dockbot import dock
result = dock(protein.pdbqt_path, pdbqt, site)
best = result.poses[0]
print(best.rank, best.affinity_kcal_mol, best.rmsd_lb, best.rmsd_ub)
Vina places the ligand in the box using iterated local search with a
Monte Carlo component, and scores each pose with a function
approximating binding free energy in kcal/mol — more negative is
tighter. A DockingResult carries the ranked poses, the receptor path
and the binding site that produced them, so a pose is never separated
from the box it was found in.
Each DockingPose carries its own PDBQT, so a pose can be visualised or
re-scored without re-docking.
Screening a library¶
neorx.dockbot.parallel docks a library across CPU cores with a
multiprocessing pool, with progress bars and resume capability — a
screen interrupted at compound 4,000 of 10,000 restarts at 4,000.
neorx dockbot prepare-protein 1BNA
neorx dockbot binding-site 1BNA
neorx dockbot dock-cmd 1BNA --ligand "CC(=O)Oc1ccccc1C(O)=O"
neorx dockbot screen 1BNA --library compounds.smi
DockBot's own composite score¶
DockBot has a composite scorer of its own —
neorx.dockbot.scorer.score_docking_result and rank_results, with
ScoringWeights and a CompositeScore result — which combines Vina
affinity with QED, SA and filter pass-rate.
Two different composite scorers
This is not the same scorer as
neorx.core.scoring.scorer. DockBot's knows nothing
about causal confidence; it is for ranking a docking campaign on its
own. The pipeline's scorer is the one that weights causal confidence
highest. Both export normalise_affinity and normalise_sa, and
they are separate functions — check which module you imported from
before comparing numbers across them.
Reports¶
neorx.dockbot.report writes a self-contained HTML report: binding-site
metadata, a ranked results table, composite scores, embedded py3Dmol
viewers for the top poses, and matplotlib summary charts.
neorx.dockbot.viz has the plotting and viewer helpers on their own.
In the pipeline¶
run_pipeline(..., run_docking=True) prepares the receptor from the
target's PDB IDs, detects the site, and docks each generated candidate.
If any of that fails the pipeline continues and scores without a binding
affinity — the dimension drops to its neutral default rather than
failing the run. See Ranking candidates.