Protein-Ligand Docking (PDBe REST API Binding Site)

What this workflow does

This workflow docks one ligand against one protein target with AutoDock Vina. The target is p38-α MAP kinase (PDB: 3LFA). The ligand is Dasatinib, with PDB ligand code 1N1.

The workflow finds the binding site by query, not by calculation. It asks the PDBe REST API for the annotated binding sites of 3LFA and writes them to residues.json. You pick a cavity from that file. The workflow then builds a docking box around the residues you chose.

The rest of the graph mirrors the Cluster90 variant. The workflow extracts the protein chain, downloads the ideal ligand SDF, and converts both partners to PDBQT with OpenBabel. AutoDock Vina docks the ligand. The last stages extract the best pose and merge it with the receptor into one complex PDB.

The compute problem

This variant trades compute for a network call, and that changes the hardware profile.

The Cluster90 variant downloads a homolog collection and computes a consensus site. That stage costs real CPU time and disk. Here, get_binding_sites is one HTTP request against the EBI. It costs milliseconds of CPU and a second of latency. There is nothing to parallelize.

The rest of the setup is the same shape: small structure edits and format conversions, all CPU-cheap and I/O bound.

The run_docking stage carries the cost. AutoDock Vina is CPU-parallel and scales with core count. It does not use a GPU. One pair is seconds. A library screen against the same box is hours on a workstation and minutes on a cluster queue.

The workflow also has a manual break in the middle. You must inspect residues.json before the box stage can run correctly.

How Horus solves it

Horus assigns an executor per stage. The API query, the conversions, and the assembly stay on your local CPU. The run_docking stage moves to a many-core node with one executor: field change. The runtime.command string does not change.

The two-pass break is where the Horus cache earns its keep. You run the workflow once, read residues.json, fill in the resid_list, and run again. Horus does not re-download the receptor or the ligand. It reruns only the box stage and everything downstream of it. On a hand-written script you rerun the whole thing.

Keep the receptor and the ligand near the docking node. The PDBQT files are small, so the transfer cost is negligible compared with an MD trajectory. This is why a docking screen tolerates a remote executor much better than an equilibration run does.

The biobb_vs package has no osx-arm64 conda package. On Apple Silicon, the binding site, box, and Vina stages run inside a quay.io/biocontainers/biobb_vs linux/amd64 image through the Docker executor. The OpenBabel and biobb_io stages run natively in the conda environment.

Pipeline

download_pdb                Download 3LFA structure from PDB (protein + ligand complex)
   │
   ├─ extract_protein         Extract protein chain (remove ligands, water, ions)
   │
   ├─ get_binding_sites       Query PDBe REST-API for binding sites (residues.json)
   │
   └─ generate_cavity_box     Generate docking box around selected binding site cavity
         │
download_ligand_sdf          Download Dasatinib (1N1) ideal SDF from PDBe
   │
convert_sdf_to_pdb            Convert ligand SDF to PDB format (OpenBabel)
   │
prepare_ligand_pdbqt          Convert ligand PDB to PDBQT for AutoDock Vina (OpenBabel)
   │
prepare_receptor_pdbqt        Add hydrogens and convert receptor to PDBQT
   │
run_docking                   Run AutoDock Vina protein-ligand docking
   │
extract_docking_pose          Extract best docking pose (model 1) from Vina output
   │
convert_pose_to_pdb           Convert docking pose PDBQT to PDB format (OpenBabel)
   │
assemble_complex              Merge receptor and docking pose into final complex PDB

Inputs and outputs

Inputs

This workflow has no file inputs. It fetches the 3LFA receptor and the Dasatinib (1N1) ligand, and queries the PDBe REST API for the binding-site annotations.

The file configs/generate_cavity_box.yaml ships with an empty resid_list. The residue indices are known only after get_binding_sites runs. Inspect results/residues.json, choose a cavity, and write its residues into resid_list. Then run the workflow again. This two-pass step comes from the original tutorial notebook.

Outputs land in results/:

• download.pdb, pdb_protein.pdb: the fetched receptor structure.
• residues.json: the PDBe-annotated binding sites for 3LFA.
• box.pdb: the docking box around the selected cavity.
• ideal.sdf, ligand.pdb, prep_ligand.pdbqt: the ligand, ready to dock.
• prep_receptor.pdbqt: the receptor, ready to dock.
• output_vina.pdbqt, output_vina.log: all the Vina poses and their scores.
• output_model.pdbqt, output_model.pdb: the top-ranked pose.
• output_structure.pdb: the final assembled protein-ligand complex.

Run the workflow

Install the horus-runtime and the plugins one time:

uv sync

If you do not have uv, install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh

You can also install the packages with pip:

pip install horus-runtime horus-environments

Then run the workflow:

uv run horus run workflow.yaml

On Apple Silicon, start Docker before you run the workflow. Horus pulls the biobb_vs image on the first run.

References

• BioExcel Building Blocks (biobb)
• biobb_vs
• AutoDock Vina
• PDBe REST API
• BioExcel protein-ligand docking tutorial