Docking¶

Dock ligands to a Protein with the Deep Origin docking tool.

Prerequisites¶

• You have a prepared Protein
• You have a Ligand or LigandSet
• You have protonated your ligands
• You have found pockets in your protein using PocketFinder

Docking a single Ligand¶

Use Docking with your protein, pocket, and ligand. Here pocket is a Pocket from PocketFinder . Both Docking.run() and Docking.start() use client.executions.create: run() sets sync=True for one ligand (one blocking request until completion), and start() sets sync=False for a single persisted async job with two or more ligands. Docking.run() returns a LigandSet of poses.

from deeporigin.drug_discovery import Docking

docking = Docking(protein=protein, pocket=pocket, ligand=ligand)
poses = docking.run()

Estimating cost¶

To get a cost estimate without running the docking, call quote() on the Docking instance:

docking = Docking(protein=protein, pocket=pocket, ligand=ligand)
docking.quote()       # populates docking.estimate
docking.estimate      # estimated cost in dollars
docking.cost          # None until a billable run completes

After a completed run, the actual cost is on the same object:

docking = Docking(protein=protein, pocket=pocket, ligand=ligand)
poses = docking.run()

docking.cost  # actual cost in dollars

Viewing docked poses¶

Docked poses for that ligand can be viewed using:

protein.show(poses=poses)

You will see something similar to the following. Use the arrows to inspect individual poses.

Viewing pose scores and binding energy¶

Every pose is assigned a pose score and a binding energy. These can be viewed using:

poses

A widget similar to the following will be shown:

To work with a dataframe containing this data, use:

df = poses.to_dataframe()

Exporting poses to SDF¶

Poses can be saved to a SDF file using:

poses.to_sdf()

Docking many ligands¶

Using batch jobs¶

Using functions¶

Several ligands in a LigandSet can be docked by passing ligands to Docking, then Docking.start() (async). Poll with sync() or Jupyter helpers until the job completes, then call get_results() to retrieve a LigandSet of poses.

docking = Docking(protein=protein, pocket=pocket, ligands=ligands)
docking.start()
# … wait for completion (docking.sync() in a loop, or watch() in notebooks) …
poses = docking.get_results()

poses is a LigandSet containing the docked poses. To work with a DataFrame:

df = poses.to_dataframe()

To filter poses to keep only top poses, use:

top_poses = poses.filter_top_poses()

These poses can be visualized as before:

protein.show(poses=poses)

If you need SDF files for the poses (e.g. for export), use get_poses() instead, which downloads the SDF files from the platform:

poses = docking.get_poses()
poses.to_sdf("my_poses.sdf")

To estimate the cost of docking a full LigandSet without running it:

docking = Docking(protein=protein, pocket=pocket, ligands=ligands)
docking.quote()
docking.estimate  # total estimated cost across all ligands

Constrained docking¶

Use ConstrainedDocking to dock test ligands while preserving a reference binding mode. The platform derives harmonic constraints server-side from MCS alignment between each test ligand and a supplied reference pose. Callers provide reference_ligand (scaffold identity) and reference_pose (required 3D SDF coordinates); they do not pass constraint atom lists.

Dock-then-constrain pipeline¶

Dock a reference ligand, upload the best pose SDF, then constrained-dock analogs:

from deeporigin.drug_discovery import ConstrainedDocking, Docking

ref_poses = Docking(protein=protein, pocket=pocket, ligand=reference_ligand).run()
reference_pose = ref_poses.ligands[0]
reference_pose.sync(remote_path="testing/reference-pose.sdf")

cd = ConstrainedDocking(
    protein=protein,
    pocket=pocket,
    reference_ligand=reference_ligand,
    reference_pose=reference_pose,
    ligand=query_ligand,
)
poses = cd.run()

Each test ligand must have a structure file on the platform (load from SDF/MOL2 and call ligand.sync()). The reference pose must have 3D coordinates.

To view new poses together with the reference pose:

protein.show(poses=reference_pose + poses)

Inspect whether harmonic constraints were applied via the constrained property on each pose in poses.to_dataframe(). When MCS cannot match a test ligand, the tool free-docks that ligand and sets constrained=False.

Retrieve the reference pose echoed by the tool:

reported_reference = cd.get_reference_pose()

Multiple test ligands (async)¶

Pass ligands= and use start() / watch() for batch constrained docking:

cd = ConstrainedDocking(
    protein=protein,
    pocket=pocket,
    reference_ligand=reference_ligand,
    reference_pose=reference_pose,
    ligands=analogs,
)
cd.start()
# … wait for completion …
poses = cd.get_results()

MCS override¶

Force a common scaffold with mcs_smarts or mcs_smiles (mutually exclusive):

cd = ConstrainedDocking(
    protein=protein,
    pocket=pocket,
    reference_ligand=reference_ligand,
    reference_pose=reference_pose,
    ligand=query_ligand,
    mcs_smarts="C(=O)",
)
poses = cd.run()

Estimating cost¶

cd = ConstrainedDocking(
    protein=protein,
    pocket=pocket,
    reference_ligand=reference_ligand,
    reference_pose=reference_pose,
    ligand=query_ligand,
)
cd.run(quote=True)
cd.estimate

Filtering docking outputs¶

Filter docking results by score and related properties.

Here we assume that you have constructed a Complex object and successfully run Docking. Following convention, we assume that the Complex object is called sim.

Fetch docked poses¶

First, we get the results of Docking in a pandas DataFrame using:

poses = sim.docking.get_poses()

Plot docking results¶

The metrics of all docked poses can be plotted in a scatter plot using:

poses.plot()

Pick top results¶

We can pick the top pose for each SMILES string using:

poses.filter_top_poses()