HADDOCK3 Antibody-Antigen Protein-Protein Docking

What this workflow does

This workflow docks an antibody onto an antigen with HADDOCK3. It reproduces the official HADDOCK3 antibody-antigen tutorial. The antibody is gevokizumab (PDB: 4G6K). The antigen is Interleukin-1β (PDB: 4I1B). The known complex (PDB: 4G6M) serves as the reference for CAPRI scoring.

The preparation part cleans both antibody chains with biobb_pdb_tools. It trims the heavy chain to residues 1-120 and the light chain to residues 1-107. It then merges them into one single-chain model. The antigen goes through the same clean-up without the merge. The reference complex goes through the same chain of stages.

The restraints part converts the paratope active residues and the epitope passive residues into an ambiguous interaction restraint table. It also writes multi-body restraints that tie the two antibody chains together.

The docking part runs the staged HADDOCK3 protocol: topology generation, rigid-body sampling, flexible refinement, energy minimization, FCC clustering, and a CAPRI evaluation after each stage.

The compute problem

HADDOCK3 docking is the classic wide-then-narrow compute shape.

The preparation stages are tiny. There are more than forty of them. Each one edits a PDB file in milliseconds. The scheduling overhead exceeds the compute cost.

The rigid_body stage is the widest. It samples many models in parallel. It wants as many cores as you can give it.

The flex_ref and em_ref stages are narrower but slower per model. They run only on the selected top models. A CPU core per model is the natural unit.

The CAPRI evaluations and the clustering are cheap again.

If you run all of this on one laptop, the rigid-body stage sets your total run time. You cut the sampling count to compensate. Lower sampling means you miss the correct pose.

How Horus solves it

Horus separates the preparation graph from the docking graph. The antibody chains, the antigen, and the reference complex have no dependency on each other. Horus runs those three preparation chains at the same time.

The docking stages then declare their own executor. You keep the forty preparation stages on your laptop, where the network and the files are. You point rigid_body, flex_ref, and em_ref at a multi-core node or an HPC scheduler with one executor: field each. The runtime.command string does not change.

This is where per-stage routing pays for itself. A HADDOCK3 run spends over 90 percent of its wall time in three stages. Moving three fields raises the sampling count without touching the other forty stages.

biobb_haddock and biobb_pdb_tools both have native osx-arm64 conda builds. The whole workflow runs in the conda executor on Apple Silicon. You do not need Docker for this workflow.

Pipeline

fetch_antibody / fetch_antigen / fetch_complex   Download 4G6K, 4I1B, 4G6M from the PDBe (pdb)
   │
Antibody prep (H + L chains, run separately then merged)
   ab_H_tidy ─ab_H_selchain─ab_H_delhetatm─ab_H_fixinsert─ab_H_selaltloc─ab_H_keepcoord─ab_H_selres(1-120)─ab_H_tidy_final
   ab_L_tidy ─ab_L_selchain─ab_L_delhetatm─ab_L_fixinsert─ab_L_selaltloc─ab_L_keepcoord─ab_L_selres(1-107)─ab_L_tidy_final
      │  (biobb_pdb_tidy / selchain / delhetatm / fixinsert / selaltloc / keepcoord / selres)
   ab_zip_HL ──► ab_merge ──► ab_reres ──► ab_chain ──► ab_chainxseg ──► ab_tidy_final
      (zip, merge H+L, renumber, set chain A, chain→seg, final tidy)

Antigen prep
   ag_tidy ─ag_delhetatm─ag_selaltloc─ag_keepcoord─ag_chain(B)─ag_chainxseg─ag_tidy_final

Reference complex prep (for CAPRI scoring, same H/L/antigen pipeline applied to 4G6M)
   cx_H_* / cx_L_* ──► cx_zip_HL ──► cx_ab_merge ──► cx_ab_reres ──► cx_ab_chain ──► cx_ab_chainxseg ──► cx_ab_tidy_final
   cx_ag_* ──► cx_zip_AB ──► cx_merge ──► cx_tidy_final

Restraints
   write_ab_actpass                     Paratope active residues (static list)
   passive_from_active                  Epitope passive residues around antigen (haddock3_passive_from_active)
   actpass_to_ambig                     Ambiguous interaction restraints (AIR) table (haddock3_actpass_to_ambig)
   restrain_bodies                      Multi-body restraints tying antibody H+L chains (haddock3_restrain_bodies)

Docking (HADDOCK3 staged protocol)
   topology ──► rigid_body ──► capri_eval_1 ──► sele_top(top 8) ──► flex_ref ──► capri_eval_2
       ──► em_ref ──► capri_eval_3 ──► clust_fcc ──► sele_top_clusts(top 4/cluster) ──► capri_eval_4 ──► contact_map

Inputs and outputs

Inputs

The workflow has no file inputs. It fetches 4G6K, 4I1B, and 4G6M from the PDBe. configs/fetch_antibody.yaml, configs/fetch_antigen.yaml, and configs/fetch_complex.yaml set the three PDB codes.

Outputs land in results/:

• 4G6K_clean.pdb, 4I1B_clean.pdb: the prepared antibody and antigen.
• 4G6M_clean.pdb: the prepared reference complex, used only for CAPRI scoring.
• 4G6K_actpass.txt, 4I1B_actpass.txt: the paratope and epitope residue lists.
• ambig-paratope-NMR-epitope.tbl, antibody-unambig.tbl: the AIR table and the multi-body restraint table.
• 1_top_mol1.zip, 1_top_mol2.zip, haddock_wf_data: the HADDOCK3 topology and workspace.
• 2_docking.zip, 5_flexref.zip, 7_emref.zip: the model ensembles after rigid-body sampling, flexible refinement, and energy minimization.
• 3_caprieval.zip, 6_caprieval2.zip, 8_caprieval3.zip, 11_caprieval4.zip: the CAPRI scores after each stage.
• 4_selected.zip, 9_clustfcc.zip, 10_seletopclusts.zip: the top-scoring and clustered selections.
• 12_contact_map.zip: the contact maps for the final cluster representatives.

Run the workflow

Install the horus-runtime 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

The first run builds the conda environment with HADDOCK3 and AmberTools. This takes a few minutes.

References

• BioExcel Building Blocks (biobb)
• biobb_haddock
• biobb_pdb_tools
• HADDOCK3
• HADDOCK3 antibody-antigen tutorial
• BioExcel HADDOCK3 tutorial