diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/CDRs.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/CDRs.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/CDRs.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/CDRs.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/HADDOCK2-stages.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/HADDOCK2-stages.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/HADDOCK2-stages.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/HADDOCK2-stages.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/HADDOCK3-workflow-scheme.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/HADDOCK3-workflow-scheme.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/HADDOCK3-workflow-scheme.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/HADDOCK3-workflow-scheme.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/Table5-Blech.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/Table5-Blech.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/Table5-Blech.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/Table5-Blech.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/ab-ag-af2-4G6M.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/ab-ag-af2-4G6M.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/ab-ag-af2-4G6M.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/ab-ag-af2-4G6M.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/ab-ag-af2.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/ab-ag-af2.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/ab-ag-af2.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/ab-ag-af2.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/ab-ag-af3-4G6M.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/ab-ag-af3-4G6M.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/ab-ag-af3-4G6M.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/ab-ag-af3-4G6M.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/ab-ag-af3-epitope.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/ab-ag-af3-epitope.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/ab-ag-af3-epitope.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/ab-ag-af3-epitope.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/abagtest_2d03e_pae.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/abagtest_2d03e_pae.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/abagtest_2d03e_pae.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/abagtest_2d03e_pae.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/antibody-paratope.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/antibody-paratope.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/antibody-paratope.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/antibody-paratope.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/antibody_described.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/antibody_described.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/antibody_described.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/antibody_described.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/antigen-active-passive.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/antigen-active-passive.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/antigen-active-passive.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/antigen-active-passive.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/antigen-epitope.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/antigen-epitope.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/antigen-epitope.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/antigen-epitope.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/asp58_contacts.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/asp58_contacts.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/asp58_contacts.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/asp58_contacts.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/caprieval_analysis-distributions.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/caprieval_analysis-distributions.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/caprieval_analysis-distributions.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/caprieval_analysis-distributions.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/caprieval_analysis-plots.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/caprieval_analysis-plots.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/caprieval_analysis-plots.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/caprieval_analysis-plots.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/caprieval_analysis-table.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/caprieval_analysis-table.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/caprieval_analysis-table.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/caprieval_analysis-table.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/dendrogram_average_P01584.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/dendrogram_average_P01584.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/dendrogram_average_P01584.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/dendrogram_average_P01584.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/haddock3-webapp-manage-run-access.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/haddock3-webapp-manage-run-access.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/haddock3-webapp-manage-run-access.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/haddock3-webapp-manage-run-access.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/haddock3-webapp-workflow-builder.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/haddock3-webapp-workflow-builder.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/haddock3-webapp-workflow-builder.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/haddock3-webapp-workflow-builder.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/mutant-ref-overlay-alascan.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/mutant-ref-overlay-alascan.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/mutant-ref-overlay-alascan.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/mutant-ref-overlay-alascan.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/mutant-stacking.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/mutant-stacking.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/mutant-stacking.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/mutant-stacking.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/results-best-model.png b/education/HADDOCK3/HADDOCK3-antibody-antigen/images/results-best-model.png
similarity index 100%
rename from education/HADDOCK3/HADDOCK3-antibody-antigen/results-best-model.png
rename to education/HADDOCK3/HADDOCK3-antibody-antigen/images/results-best-model.png
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/index.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/index.md
index 4401dc070..3d25f91e8 100644
--- a/education/HADDOCK3/HADDOCK3-antibody-antigen/index.md
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/index.md
@@ -11,3160 +11,87 @@ This tutorial consists of the following sections:
* table of contents
{:toc}
-
+{% include_relative sections/intro.md %}
-## Introduction
+{% include_relative sections/prompt-legend.md %}
-This tutorial demonstrates the use of the new modular HADDOCK3 version for predicting
-the structure of an antibody-antigen complex using knowledge of the hypervariable loops
-on the antibody (i.e., the most basic knowledge) and epitope information identified from NMR experiments for the antigen to guide the docking.
+{% include_relative sections/haddock-concepts.md %}
-This tutorial was recorded at the BioExcel Sofia Workshop in May 2025:
-
+{% include_relative sections/haddock3-intro.md %}
-
-An antibody is a large protein that generally works by attaching itself to an antigen,
-which is a unique site of the pathogen. The binding harnesses the immune system to directly
-attack and destroy the pathogen. Antibodies can be highly specific while showing low immunogenicity (i.e. the ability to provoke an immune response),
-which is achieved by their unique structure. **The fragment crystallizable region (Fc region)**
-activates the immune response and is species-specific, i.e. the human Fc region should not
-induce an immune response in humans. **The fragment antigen-binding region (Fab region**)
-needs to be highly variable to be able to bind to antigens of various nature (high specificity).
-In this tutorial, we will concentrate on the terminal **variable domain (Fv)** of the Fab region.
+{% include_relative sections/setup-intro.md %}
-
-
-
+{% include_relative sections/setup-ljubljana-2026.md %}
-The small part of the Fab region that binds the antigen is called **paratope**. The part of the antigen
-that binds to an antibody is called **epitope**. The paratope consists of six highly flexible loops,
-known as **complementarity-determining regions (CDRs)** or hypervariable loops whose sequence
-and conformation are altered to bind to different antigens. CDRs are shown in red in the figure below:
+{% include_relative sections/setup-kobe-2026.md %}
-
-
-
+{% include_relative sections/setup-pula-2025.md %}
-In this tutorial we will be working with Interleukin-1β (IL-1β)
-(PDB code [4I1B](https://www.ebi.ac.uk/pdbe/entry/pdb/4i1b){:target="_blank"}) as an antigen
-and its highly specific monoclonal antibody gevokizumab
-(PDB code [4G6K](https://www.ebi.ac.uk/pdbe/entry/pdb/4g6k){:target="_blank"})
-(PDB code of the complex [4G6M](https://www.ebi.ac.uk/pdbe/entry/pdb/4g6m){:target="_blank"}).
+{% include_relative sections/setup-local.md %}
+{% include_relative sections/preparing-pdb-intro.md %}
-Throughout the tutorial, colored text will be used to refer to questions or
-instructions, and/or PyMOL commands.
+{% include_relative sections/preparing-antibody.md %}
-This is a question prompt: try answering it!
-This an instruction prompt: follow it!
-This is a PyMOL prompt: write this in the PyMOL command line prompt!
-This is a Linux prompt: insert the commands in the terminal!
+{% include_relative sections/preparing-antigen.md %}
+{% include_relative sections/restraints-intro.md %}
-
-
+{% include_relative sections/restraints-paratope.md %}
-## HADDOCK general concepts
+{% include_relative sections/restraints-epitope.md %}
-HADDOCK (see [https://www.bonvinlab.org/software/haddock2.4](https://www.bonvinlab.org/software/haddock2.4){:target="_blank"})
-is a collection of python scripts derived from ARIA ([https://aria.pasteur.fr](https://aria.pasteur.fr){:target="_blank"})
-that harness the power of CNS (Crystallography and NMR System – [https://cns-online.org](https://cns-online.org){:target="_blank"})
-for structure calculation of molecular complexes. What distinguishes HADDOCK from other docking software is its ability,
-inherited from CNS, to incorporate experimental data as restraints and use these to guide the docking process alongside
-traditional energetics and shape complementarity. Moreover, the intimate coupling with CNS endows HADDOCK with the
-ability to actually produce models of sufficient quality to be archived in the Protein Data Bank.
+{% include_relative sections/restraints-ambiguous.md %}
-A central aspect of HADDOCK is the definition of Ambiguous Interaction Restraints or AIRs. These allow the
-translation of raw data such as NMR chemical shift perturbation or mutagenesis experiments into distance
-restraints that are incorporated into the energy function used in the calculations. AIRs are defined through
-a list of residues that fall under two categories: active and passive. Generally, active residues are those
-of central importance for the interaction, such as residues whose knockouts abolish the interaction or those
-where the chemical shift perturbation is higher. Throughout the simulation, these active residues are
-restrained to be part of the interface, if possible, otherwise incurring a scoring penalty. Passive residues
-are those that contribute to the interaction but are deemed of less importance. If such a residue does
-not belong in the interface there is no scoring penalty. Hence, a careful selection of which residues are
-active and which are passive is critical for the success of the docking.
+{% include_relative sections/restraints-validation.md %}
+{% include_relative sections/restraints-multichain.md %}
-
-
+{% include_relative sections/docking-intro.md %}
-## A brief introduction to HADDOCK3
+{% include_relative sections/docking-workflow.md %}
-HADDOCK3 is the next generation integrative modelling software in the
-long-lasting HADDOCK project. It represents a complete rethinking and rewriting
-of the HADDOCK2.X series, implementing a new way to interact with HADDOCK and
-offering new features to users who can now define custom workflows.
+{% include_relative sections/run-haddock3-intro.md %}
-In the previous HADDOCK2.x versions, users had access to a highly
-parameterisable yet rigid simulation pipeline composed of three steps:
-`rigid-body docking (it0)`, `semi-flexible refinement (it1)`, and `final refinement (itw)`.
+{% include_relative sections/run-bioexcel2025.md %}
-
-
-
+{% include_relative sections/run-discoverer.md %}
-In HADDOCK3, users have the freedom to configure docking workflows into
-functional pipelines by combining the different HADDOCK3 modules, thus
-adapting the workflows to their projects. HADDOCK3 has therefore developed to
-truthfully work like a puzzle of many pieces (simulation modules) that users can
-combine freely. To this end, the “old” HADDOCK machinery has been modularized,
-and several new modules added, including third-party software additions. As a
-result, the modularization achieved in HADDOCK3 allows users to duplicate steps
-within one workflow (e.g., to repeat twice the `it1` stage of the HADDOCK2.x
-rigid workflow).
+{% include_relative sections/run-truba.md %}
-Note that, for simplification purposes, at this time, not all functionalities of
-HADDOCK2.x have been ported to HADDOCK3, which does not (yet) support NMR RDC,
-PCS and diffusion anisotropy restraints, cryo-EM restraints and coarse-graining.
-Any type of information that can be converted into ambiguous interaction
-restraints can, however, be used in HADDOCK3, which also supports the
-*ab initio* docking modes of HADDOCK.
+{% include_relative sections/run-fugaku.md %}
-
-
-
+{% include_relative sections/run-ljubljana-2026.md %}
-To keep HADDOCK3 modules organized, we catalogued them into several
-categories. However, there are no constraints on piping modules of different
-categories.
+{% include_relative sections/haddock3-execution-modes.md %}
-The main module categories are "topology", "sampling", "refinement",
-"scoring", and "analysis". There is no limit to how many modules can belong to a
-category. Modules are added as developed, and new categories will be created
-if/when needed. You can access the HADDOCK3 documentation page for the list of
-all categories and modules. Below is a summary of the available modules:
+{% include_relative sections/analysis-intro.md %}
-* **Topology modules**
- * `topoaa`: *generates the all-atom topologies for the CNS engine.*
-* **Sampling modules**
- * `rigidbody`: *Rigid body energy minimization with CNS (`it0` in haddock2.x).*
- * `lightdock`: *Third-party glow-worm swam optimization docking software.*
-* **Model refinement modules**
- * `flexref`: *Semi-flexible refinement using a simulated annealing protocol through molecular dynamics simulations in torsion angle space (`it1` in haddock2.x).*
- * `emref`: *Refinement by energy minimisation (`itw` EM only in haddock2.4).*
- * `mdref`: *Refinement by a short molecular dynamics simulation in explicit solvent (`itw` in haddock2.X).*
-* **Scoring modules**
- * `emscoring`: *scoring of a complex performing a short EM (builds the topology and all missing atoms).*
- * `mdscoring`: *scoring of a complex performing a short MD in explicit solvent + EM (builds the topology and all missing atoms).*
-* **Analysis modules**
- * `alascan`: *Performs a systematic (or user-define) alanine scanning mutagenesis of interface residues.*
- * `caprieval`: *Calculates CAPRI metrics (i-RMSD, l-RMSD, Fnat, DockQ) with respect to the top-scoring model or reference structure if provided.*
- * `clustfcc`: *Clusters models based on the fraction of common contacts (FCC)*
- * `clustrmsd`: *Clusters models based on pairwise RMSD matrix calculated with the `rmsdmatrix` module.*
- * `contactmap`: *Generate contact matrices of both intra- and intermolecular contacts and a chordchart of intermolecular contacts.*
- * `rmsdmatrix`: *Calculates the pairwise RMSD matrix between all the models generated in the previous step.*
- * `ilrmsdmatrix`: *Calculates the pairwise interface-ligand-RMSD (il-RMSD) matrix between all the models generated in the previous step.*
- * `seletop`: *Selects the top N models from the previous step.*
- * `seletopclusts`: *Selects the top N clusters from the previous step.*
+{% include_relative sections/analysis-clusters.md %}
-The HADDOCK3 workflows are defined in simple configuration text files, similar to the TOML format but with extra features.
-Contrary to HADDOCK2.X which follows a rigid (yet highly parameterisable)
-procedure, in HADDOCK3, you can create your own simulation workflows by
-combining a multitude of independent modules that perform specialized tasks.
+{% include_relative sections/analysis-scores.md %}
+{% include_relative sections/analysis-single-structure.md %}
-
-
+{% include_relative sections/analysis-contacts.md %}
-## Software and data setup
+{% include_relative sections/analysis-visualization.md %}
-In order to follow this tutorial you will need to work on a Linux or MacOSX
-system. We will also make use of [**PyMOL**](https://www.pymol.org/){:target="_blank"} (freely available for
-most operating systems) in order to visualize the input and output data. We will
-provide you links to download the various required software and data.
+{% include_relative sections/conclusions.md %}
-Further, we are providing pre-processed PDB files for docking and analysis (but the
-preprocessing of those files will also be explained in this tutorial). The files have been processed
-to facilitate their use in HADDOCK and to allow comparison with the known reference
-structure of the complex.
+{% include_relative sections/bonus1-mutations.md %}
-If you are running this tutorial on your own resources _download and unzip the following_
-[zip archive](https://surfdrive.surf.nl/public.php/dav/files/R7VHGQM9nx8QuQn){:target="_blank"}
-_and note the location of the extracted PDB files in your system_.
+{% include_relative sections/bonus2-arctic3d.md %}
-_If running as part of the ASM HPC/AI school or a BioExcel workshop or summerschool see the instructions in the respective next sections._
+{% include_relative sections/bonus3-ai-models.md %}
-_Note_ that you can also download and unzip this archive directly from the Linux command line:
+{% include_relative sections/bonus4-ensemble.md %}
-
-wget https://surfdrive.surf.nl/public.php/dav/files/R7VHGQM9nx8QuQn -O HADDOCK3-antibody-antigen.zip
-unzip HADDOCK3-antibody-antigen.zip
-
+{% include_relative sections/bonus5-alphafold2.md %}
+{% include_relative sections/bonus6-scoring.md %}
-Unziping the file will create the `HADDOCK3-antibody-antigen` directory which should contain the following directories and files:
-
-* `pdbs`: a directory containing the pre-processed PDB files
-* `restraints`: a directory containing the interface information and the corresponding restraint files for HADDOCK3
-* `runs`: a directory containing pre-calculated results
-* `scripts`: a directory containing various scripts used in this tutorial
-* `workflows`: a directory containing configuration file examples for HADDOCK3
-
-In case of a workshop of course, HADDOCK3 will usually have been installed on the system you will be using.
-
-In case HADDOCK3 is not pre-installed in your system, you will have to install it.
-To obtain HADDOCK3, fill the [registration form](https://docs.google.com/forms/d/e/1FAIpQLScDcd0rWtuzJ_4nftkDAHoLVwr1IAVwNJGhbaZdTYZ4vWu25w/viewform?){:target="_blank"}, and then follow the [installation instructions](https://www.bonvinlab.org/haddock3-user-manual/install.html){:target="_blank"}.
-
-In this tutorial we will use the PyMOL molecular visualisation system. If not already installed, download and install PyMOL from [here](https://pymol.org/){:target="_blank"}. You can use your favourite visualisation software instead, but be aware that instructions in this tutorial are provided only for PyMOL.
-
-This tutorial was last tested using HADDOCK3 version 2024.10.0b7. The provided pre-calculated runs were obtained on a Macbook Pro M2 processors with as OS Sequoia 15.3.1.
-
-
-
-
-
-### BioExcel Adriatic edition 2026, Ljubljana, Slovenia
-
-You can either:
-
- * make use of the ADD HPC system for this tutorial, working at the command line,
- * or [start a Colab notebook](https://colab.research.google.com/github/haddocking/haddock3/blob/main/notebooks/HADDOCK3-antibody-antigen.ipynb){:target="_blank"} (provided you have Google credentials) and follow the instructions in that notebook (simpler).
-
-
-If running on HPC system, the software and data required for this tutorial have been pre-installed.
-Please connect to the HPC system using your credentials either via ssh connection.
-
-In order to run the tutorial, go into you data directory, then copy and unzip the required data:
-
-
-unzip /home/vreys/HADDOCK3-antibody-antigen.zip
-
-
-This will create the `HADDOCK3-antibody-antigen` directory with all necessary data and scripts and job examples ready for submission to the batch system.
-
-HADDOCK3 has been pre-installed on the compute nodes.
-To test the installation, first create an interactive session on a node with:
-
-
-
-salloc --job-name=interactive_haddock3 --partition=amd --nodes=1 --cpus-per-task=8 --time-min=120
-
-
-Once the session is active, activate HADDOCK3 with:
-
-
-source /home/vreys/haddock3/.haddock3-env/bin/activate
-
-
-
-You can then test that `haddock3` is indeed accessible with:
-
-
-haddock3 -h
-
-
-You should see a small help message explaining how to use the software.
-
-
-
- View outputexpand_more
-
-
-(haddock3)$ haddock3 -h
-usage: haddock3 [-h] [--restart RESTART] [--extend-run EXTEND_RUN] [--setup]
- [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-v]
- recipe
-
-positional arguments:
- recipe The input recipe file path
-
-optional arguments:
- -h, --help show this help message and exit
- --restart RESTART Restart the run from a given step. Previous folders from the
- selected step onward will be deleted.
- --extend-run EXTEND_RUN
- Start a run from a run directory previously prepared with the
- `haddock3-copy` CLI. Provide the run directory created with
- `haddock3-copy` CLI.
- --setup Only setup the run, do not execute
- --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
- -v, --version show version
-
-(haddock3)$ haddock3 -h
-usage: haddock3 [-h] [--restart RESTART] [--extend-run EXTEND_RUN] [--setup]
- [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-v]
- recipe
-
-positional arguments:
- recipe The input recipe file path
-
-optional arguments:
- -h, --help show this help message and exit
- --restart RESTART Restart the run from a given step. Previous folders from the
- selected step onward will be deleted.
- --extend-run EXTEND_RUN
- Start a run from a run directory previously prepared with the
- `haddock3-copy` CLI. Provide the run directory created with
- `haddock3-copy` CLI.
- --setup Only setup the run, do not execute
- --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
- -v, --version show version
-
- which is an alias for:
- source ~/BioExcel_SS_2025/HADDOCK/haddock3/.venv/bin/activate
-
-
-
- You can then test that haddock3 is accessible with:
-
-
- haddock3 -h
- You should see a small help message explaining how to use the software.
-
-
-
- View outputexpand_more
-
-
- (haddock3)$ haddock3 -h
- usage: haddock3 [-h] [--restart RESTART] [--extend-run EXTEND_RUN] [--setup]
- [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-v]
- recipe
-
- positional arguments:
- recipe The input recipe file path
-
- optional arguments:
- -h, --help show this help message and exit
- --restart RESTART Restart the run from a given step. Previous folders from the
- selected step onward will be deleted.
- --extend-run EXTEND_RUN
- Start a run from a run directory previously prepared with the
- `haddock3-copy` CLI. Provide the run directory created with
- `haddock3-copy` CLI.
- --setup Only setup the run, do not execute
- --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
- -v, --version show version
-
-
-
-
-
-
-
-
-### Local setup (on your own)
-
-
-
- click to expand
-
-
- If you are installing HADDOCK3 on your own system, check the instructions and requirements below.
-
-
- Note that depending on the system you are installing HADDOCK3 on,
- you might have to recompile CNS if the provided executable is not working.
- See the
-
- CNS troubleshooting section
-
- on the HADDOCK3 GitHub repository for instructions.
-
-
-
-
Auxiliary software
-
-
- PyMOL:
- In this tutorial we will make use of PyMOL for visualization.
- If not already installed on your system, download and install
- PyMOL.
- Note that you can use your favorite visualization software,
- but instructions are only provided here for PyMOL.
-
-
-
-
-
-
-
-
-## Preparing PDB files for docking
-
-In this section we will prepare the PDB files of the antibody and antigen for docking.
-Crystal structures of both the antibody and the antigen in their free forms are available from the
-[PDBe database](https://www.pdbe.org){:target="_blank"}.
-
-__Important:__ For a docking run with HADDOCK, each molecule should consist of a single chain with non-overlapping residue numbering within the same chain.
-
-As an antibody consists of two chains (L+H), we will have to prepare it for use in HADDOCK. For this we will be making use of `pdb-tools` from the command line.
-
-_**Note**_ that `pdb-tools` is also available as a [web service](https://wenmr.science.uu.nl/pdbtools/){:target="_blank"}.
-
-
-
-
-### Preparing the antibody structure
-
-Using PDB-tools we will download the unbound structure of the antibody from the PDB database (the PDB ID is [4G6K](https://www.ebi.ac.uk/pdbe/entry/pdb/4g6k){:target="_blank"})
-and then process it to have a unique chain ID (A) and non-overlapping residue numbering by renumbering the merged pdb (starting from 1). For this we will concatenate the following PDB-tools commands:
-
-1. fetch the PDB entry from the PDB database (`pdb_fetch`)
-2. clean the PDB file (`pdb_tidy`)
-3. select the chain (`pdb_selchain`),
-4. remove any hetero atoms from the structure (e.g. crystal waters, small molecules from the crystallisation buffer and such) (`pdb_delhetatm`),
-5. fix residue numbering insertion in the HV loops (often occuring in antibodies - see note below) (`pdb_fixinsert`)
-6. remove any possible side-chain duplication (can be present in high-resolution crystal structures in case of multiple conformations of some side chains) (`pdb_selaltloc`)
-7. keep only the coordinates lines (`pdb_keepcoord`),
-8. select only the variable domain (FV) of the antibody (to reduce computing time) (`pdb_selres`)
-9. clean the PDB file (`pdb_tidy`)
-
-**_Note_** that the `pdb_tidy -strict` commands cleans the PDB file, add TER statements only between different chains).
-Without the -strict option TER statements would be added between each chain break (e.g. missing residues), which should be avoided.
-
-**_Note_**: An important part for antibodies is the `pdb_fixinsert` command that fixes the residue numbering of the HV loops:
-Antibodies often follow the [Chothia numbering scheme](https://pubmed.ncbi.nlm.nih.gov/9367782/?otool=inluulib){:target="_blank"}
-and insertions created by this numbering scheme (e.g. 82A, 82B, 82C) cannot be processed by HADDOCK directly
-(if not done those residues will not be considered resulting effectively in a break in the loop).
-As such, renumbering is necessary before starting the docking.
-
-
-This can be done from the command line with:
-
-
-pdb_fetch 4G6K | pdb_tidy \-strict | pdb_selchain \-H | pdb_delhetatm | pdb_fixinsert | pdb_selaltloc | pdb_keepcoord | pdb_selres \-1:120 | pdb_tidy -strict > 4G6K_H.pdb
-
-
-pdb_fetch 4G6K | pdb_tidy \-strict | pdb_selchain -L | pdb_delhetatm | pdb_fixinsert | pdb_selaltloc | pdb_keepcoord | pdb_selres \-1:107 | pdb_tidy \-strict > 4G6K_L.pdb
-
-
-We then combined the heavy and light chain into one, renumbering the residues starting at 1 to avoid overlap in residue numbering between the chains and assigning a unique chainID/segID:
-
-
-pdb_merge 4G6K_H.pdb 4G6K_L.pdb | pdb_reres \-1 | pdb_chain \-A | pdb_chainxseg | pdb_tidy \-strict > 4G6K_clean.pdb
-
-
-_**Note**_ The ready-to-use file can be found in the `pdbs` directory of the provided tutorial data.
-
-
-
-
-### Preparing the antigen structure
-
-Using PDB-tools, we will now download the unbound structure of Interleukin-1β from the PDB database (the PDB ID is [4I1B](https://www.ebi.ac.uk/pdbe/entry/pdb/4i1b){:target="_blank"}),
-remove the hetero atoms and then process it to assign it chainID B.
-
-*__Important__: Each molecule given to HADDOCK in a docking scenario must have a unique chainID/segID.*
-
-
-pdb_fetch 4I1B | pdb_tidy \-strict | pdb_delhetatm | pdb_selaltloc | pdb_keepcoord | pdb_chain \-B | pdb_chainxseg | pdb_tidy \-strict > 4I1B_clean.pdb
-
-
-
-
-
-
-## Defining restraints for docking
-
-Before setting up the docking, we first need to generate distance restraint files in a format suitable for HADDOCK.
-HADDOCK uses [CNS][link-cns]{:target="_blank"} as computational engine.
-A description of the format for the various restraint types supported by HADDOCK can be found in our [Nature Protocol 2024][nat-pro]{:target="_blank"} paper, Box 1.
-
-Distance restraints are defined as follows:
-
-
-
-The lower limit for the distance is calculated as: distance minus lower-bound correction
-and the upper limit as: distance plus upper-bound correction.
-
-The syntax for the selections can combine information about:
-
-* chainID - `segid` keyword
-* residue number - `resid` keyword
-* atom name - `name` keyword.
-
-Other keywords can be used in various combinations of OR and AND statements. Please refer for that to the [online CNS manual][link-cns]{:target="_blank"}.
-
-E.g.: a distance restraint between the CB carbons of residues 10 and 200 in chains A and B with an
-allowed distance range between 10Å and 20Å would be defined as follows:
-
-
-assign (segid A and resid 10 and name CB) (segid B and resid 200 and name CB) 20.0 10.0 0.0
-
-
-
-Can you think of a different way of defining the distance and lower and upper corrections while maintaining the same
-allowed range?
-
-
-
-
-
-### Identifying the paratope of the antibody
-
-Nowadays several computational tools can identify the paratope (the residues of the hypervariable loops involved in binding) from the provided antibody sequence.
-In this tutorial, we are providing you with the corresponding list of residue obtained using [ProABC-2](https://github.com/haddocking/proabc-2){:target="_blank"}.
-ProABC-2 uses a convolutional neural network to identify not only residues which are located in the paratope region
-but also the nature of interactions they are most likely involved in (hydrophobic or hydrophilic).
-The work is described in [Ambrosetti, *et al* Bioinformatics, 2020](https://academic.oup.com/bioinformatics/article/36/20/5107/5873593){:target="_blank"}.
-
-The corresponding paratope residues (those with either an overall probability >= 0.4 or a probability for hydrophobic or hydrophilic > 0.3) are:
-
-
-
-We will now visualize the epitope on Interleukin-1β.
-To do this, start PyMOL and open the provided PDB file of the antigen from the PyMOL File menu.
-
-
-File menu -> Open -> select 4I1B_clean.pdb
-
-
-
-color white, all
-show surface
-select epitope, (resi 72+73+74+75+81+83+84+89+90+92+94+96+97+98+115+116+117)
-color red, epitope
-
-
-Inspect the surface.
-
-
-Do the identified residues form a well-defined patch on the surface?
-
-
-The answer to that question should be yes, but we can see some residues not colored that might also be involved in the binding - there are some white spots around/in the red surface.
-
-
-
- See surface view of the epitope identified by NMRexpand_more
-
-
-
-
-
-
-
-
-
-In HADDOCK, we are dealing with potentially incomplete binding sites by defining surface neighbors as `passive` residues.
-These passive residues are added in the definition of the interface but do not incur any energetic penalty if they are not part of the binding site in the final models.
-In contrast, residues defined as active (typically the identified or predicted binding site residues) will incur an energetic penalty.
-When using the HADDOCK2.x webserver, `passive` residues will be automatically defined.
-Here, since we are using a local version, we need to define those manually.
-
-This can easily be done using a haddock3 command line tool in the following way:
-
-
-haddock3-restraints passive_from_active 4I1B_clean.pdb 72,73,74,75,81,83,84,89,90,92,94,96,97,98,115,116,117
-
-
-The command prints a list of solvent accessible passive residues, which you should save to a file for further use.
-
-We can visualize the epitope and its surface neighbors using PyMOL:
-
-
-File menu -> Open -> select 4I1B_clean.pdb
-
-
-
-color white, all
-show surface
-select epitope, (resi 72+73+74+75+81+83+84+89+90+92+94+96+97+98+115+116+117)
-color red, epitope
-select passive, (resi 3+24+46+47+48+50+66+76+77+79+80+82+86+87+88+91+93+95+118+119+120)
-color green, passive
-
-
-
-
-
- See the epitope and passive residuesexpand_more
-
-
-
-
-
-
-
-
-The NMR-identified residues and their surface neighbors generated with the above command can be used to define ambiguous interactions restraints,
-either using the NMR identified residues as active in HADDOCK, or combining those with the surface neighbors.
-
-The difference between `active` and `passive` residues in HADDOCK is as follows:
-
-*__Active residues__*: These residues are "forced" to be at the interface. If they are not part of the interface in the final models, an energetic penalty will be applied. The interface in this context is defined by the union of active and passive residues on the partner molecules.
-
-*__Passive residues__*: These residues are expected to be at the interface. However, if they are not, no energetic penalty is applied.
-
-
-In general, it is better to be too generous rather than too strict in the definition of passive residues.
-An important aspect is to filter both the active (the residues identified from your mapping experiment) and passive residues by their solvent accessibility.
-This is done automatically when using the `haddock3-restraints passive_from_active` command: residues with less that 15% relative solvent accessibility (same cutoff as the default in the HADDOCK server) are discared.
-This is, however, not a hard limit, and you might consider including even more buried residues if some important chemical group seems solvent accessible from a visual inspection.
-
-
-
-
-### Defining ambiguous restraints
-
-Once you have identified your active and passive residues for both molecules, you can proceed with the generation of the ambiguous interaction restraints (AIR) file for HADDOCK.
-For this you can either make use of our online `Generate Restraints` [haddock-restraints][haddock-restraints] web service, entering the list of active and passive residues for each molecule,
-the chainIDs of each molecule and saving the resulting restraint list to a text file, or use another `haddock3-restraints` sub-command.
-
-To use our `haddock3-restraints active_passive_to_ambig` script, you need to
-create for each molecule a file containing two lines:
-
-* The first line corresponds to the list of active residues (numbers separated by spaces)
-* The second line corresponds to the list of passive residues (numbers separated by spaces).
-
-*__Important__*: The file must consist of two lines, but a line can be empty (e.g., if you do not want to define active residues for one molecule).
-However, there must be at least one set of active residue defined for one of the molecules.
-
-
-* For the antibody we will use the predicted paratope as active and no passive residues defined.
-The corresponding file can be found in the `restraints` directory as `antibody-paratope.act-pass`:
-
-
-
-* For the antigen we will use the NMR-identified epitope as active and the surface neighbors as passive.
-The corresponding file can be found in the `restraints` directory as `antigen-NMR-epitope.act-pass`:
-
-
-assign (resi 31 and segid A)
-(
- (resi 72 and segid B)
- or
- (resi 73 and segid B)
- or
- (resi 74 and segid B)
- or
- (resi 75 and segid B)
- or
- (resi 81 and segid B)
- or
- (resi 83 and segid B)
- or
- (resi 84 and segid B)
- or
- (resi 89 and segid B)
- or
- (resi 90 and segid B)
- or
- (resi 92 and segid B)
- or
- (resi 94 and segid B)
- or
- (resi 96 and segid B)
- or
- (resi 97 and segid B)
- or
- (resi 98 and segid B)
- or
- (resi 115 and segid B)
- or
- (resi 116 and segid B)
- or
- (resi 117 and segid B)
- or
- (resi 3 and segid B)
- or
- (resi 24 and segid B)
- or
- (resi 46 and segid B)
- or
- (resi 47 and segid B)
- or
- (resi 48 and segid B)
- or
- (resi 50 and segid B)
- or
- (resi 66 and segid B)
- or
- (resi 76 and segid B)
- or
- (resi 77 and segid B)
- or
- (resi 79 and segid B)
- or
- (resi 80 and segid B)
- or
- (resi 82 and segid B)
- or
- (resi 86 and segid B)
- or
- (resi 87 and segid B)
- or
- (resi 88 and segid B)
- or
- (resi 91 and segid B)
- or
- (resi 93 and segid B)
- or
- (resi 95 and segid B)
- or
- (resi 118 and segid B)
- or
- (resi 119 and segid B)
- or
- (resi 120 and segid B)
-) 2.0 2.0 0.0
-...
-
-
-
-
-
-
-Refering to the way the distance restraints are defined (see above), what is the distance range for the ambiguous distance restraints?
-
-
-
-
- See answerexpand_more
-
-The default distance range for those is between 0 and 2Å, which
-might seem short but makes senses because of the 1/r^6 summation in the AIR
-energy function that makes the effective distance to be significantly shorter than
-the shortest distance entering the sum.
-
-
-The effective distance is calculated as the SUM over all pairwise atom-atom
-distance combinations between an active residue and all the active+passive on
-the other molecule: SUM[1/r^6]^(-1/6).
-
-
-
-
-
-
-### Restraints validation
-
-If you modify manually this generated restraint files or create your own, it is possible to quickly check if the format is valid using the following `haddock3-restraints` sub-command:
-
-
-haddock3-restraints validate_tbl ambig-paratope-NMR-epitope.tbl \-\-silent
-
-
-No output means that your TBL file is valid.
-
-*__Note__* that this only validates the syntax of the restraint file, but does not check if the selections defined in the restraints are actually existing in your input PDB files.
-
-
-
-
-### Additional restraints for multi-chain proteins
-
-As an antibody consists of two separate chains, it is important to define a few distance restraints
-to keep them together during the high temperature flexible refinement stage of HADDOCK otherwise they might slightly drift appart.
-This can easily be done using the `haddock3-restraints restrain_bodies` sub-command.
-
-
-haddock3-restraints restrain_bodies 4G6K_clean.pdb > antibody-unambig.tbl
-
-
-The result file contains two CA-CA distance restraints with the exact distance measured between two randomly picked CA atoms pairs:
-
-
- assign (segid A and resi 110 and name CA) (segid A and resi 132 and name CA) 26.326 0.0 0.0
- assign (segid A and resi 97 and name CA) (segid A and resi 204 and name CA) 19.352 0.0 0.0
-
-
-This file is also provided in the `restraints` directory.
-
-
-
-
-
-## Setting up and running the docking with HADDOCK3
-
-Now that we have all required files at hand (PDB and restraints files), it is time to setup our docking protocol.
-In this tutorial, considering we have rather good information about the paratope and epitope, we will execute a fast HADDOCK3 docking workflow,
-reducing the non-negligible computational cost of HADDOCK by decreasing the sampling, without impacting too much the accuracy of the resulting models.
-
-
-
-
-
-### HADDOCK3 workflow definition
-
-The first step is to create a HADDOCK3 configuration file that will define the docking workflow.
-We will follow a classic HADDOCK workflow consisting of rigid body docking, semi-flexible refinement and final energy minimisation followed by clustering.
-
-We will also integrate two analysis modules in our workflow:
-
-- `caprieval` will be used at various stages to compare models to either the best scoring model (if no reference is given) or a reference structure, which in our case we have at hand (`pdbs/4G6M_matched.pdb`). This will directly allow us to assess the performance of the protocol. In the absence of a reference, `caprieval` is still usefull to assess the convergence of a run and analyse the results.
-- `contactmap` added as last module will generate contact matrices of both intra- and intermolecular contacts and a chordchart of intermolecular contacts for each cluster.
-
-
-Our workflow consists of the following modules:
-
-1. **`topoaa`**: *Generates the topologies for the CNS engine and builds missing atoms*
-2. **`rigidbody`**: *Performs rigid body energy minimisation (`it0` in haddock2.x)*
-3. **`caprieval`**: *Calculates CAPRI metrics (i-RMSD, l-RMSD, Fnat, DockQ) with respect to the top scoring model or reference structure if provided*
-4. **`seletop`** : *Selects the top X models from the previous module*
-5. **`flexref`**: *Preforms semi-flexible refinement of the interface (`it1` in haddock2.4)*
-6. **`caprieval`**
-7. **`emref`**: *Final refinement by energy minimisation (`itw` EM only in haddock2.4)*
-8. **`caprieval`**
-9. **`clustfcc`**: *Clustering of models based on the fraction of common contacts (FCC)*
-10. **`seletopclusts`**: *Selects the top models of all clusters*
-11. **`caprieval`**
-12. **`contactmap`**: *Contacts matrix and a chordchart of intermolecular contacts*
-
-
-The corresponding toml configuration file (provided in `workflows/docking-antibody-antigen.cfg`) looks like:
-
-{% highlight toml %}
-# ====================================================================
-# Antibody-antigen docking example with restraints from the antibody
-# paratope to the NMR-identified epitope on the antigen
-# ====================================================================
-
-# Directory in which the scoring will be done
-run_dir = "run1"
-
-# Compute mode
-mode = "local"
-ncores = 50
-
-# Self contained rundir (to avoid problems with long filename paths)
-self_contained = true
-
-# Post-processing to generate statistics and plots
-postprocess = true
-clean = true
-
-molecules = [
- "pdbs/4G6K_clean.pdb",
- "pdbs/4I1B_clean.pdb"
- ]
-
-# ====================================================================
-# Parameters for each stage are defined below, prefer full paths
-# ====================================================================
-[topoaa]
-
-[rigidbody]
-# CDR to NMR epitope ambig restraints
-ambig_fname = "restraints/ambig-paratope-NMR-epitope.tbl"
-# Restraints to keep the antibody chains together
-unambig_fname = "restraints/antibody-unambig.tbl"
-# Reduced sampling (100 instead of the default of 1000)
-sampling = 100
-
-[caprieval]
-reference_fname = "pdbs/4G6M_matched.pdb"
-
-[seletop]
-# Selection of the top 50 best scoring complexes (instead of the default of 200)
-select = 50
-
-[flexref]
-tolerance = 5
-# CDR to NMR epitope ambig restraints
-ambig_fname = "restraints/ambig-paratope-NMR-epitope.tbl"
-# Restraints to keep the antibody chains together
-unambig_fname = "restraints/antibody-unambig.tbl"
-
-[caprieval]
-reference_fname = "pdbs/4G6M_matched.pdb"
-
-[emref]
-tolerance = 5
-# CDR to NMR epitope ambig restraints
-ambig_fname = "restraints/ambig-paratope-NMR-epitope.tbl"
-# Restraints to keep the antibody chains together
-unambig_fname = "restraints/antibody-unambig.tbl"
-
-[caprieval]
-reference_fname = "pdbs/4G6M_matched.pdb"
-
-[clustfcc]
-plot_matrix = true
-
-[seletopclusts]
-# Selection of the top 4 best scoring complexes from each cluster
-top_models = 4
-
-[caprieval]
-reference_fname = "pdbs/4G6M_matched.pdb"
-
-[contactmap]
-
-# ====================================================================
-
-{% endhighlight %}
-
-
-In this case, since we have information for both interfaces we use a low-sampling configuration file, which takes only a small amount of computational resources to run.
-The initial `sampling` parameter at the rigid-body energy minimization (`rigidbody`) module is set to 100 models, of which only best the 40 are passed to the flexible refinement (`flexref`) module with the `seletop` module.
-The subsequence flexible refinement (`flexref` module) and energy minimisation (*emref*) modules will use all models passed by the *seletop* module.
-FCC clustering (`clustfcc`) is then applied to group together models sharing a consistent fraction of the interface contacts.
-The top 4 models of each cluster are saved to disk (`seletopclusts`).
-
-Multiple `caprieval` modules are executed at different stages of the workflow to check how the quality (and rankings) of the models change throughout the protocol.
-In this case we are providing the known crystal structure of the complex as reference.
-
-
-**_Note_**: For making best use of the available CPU resources it is recommended to adapt the sampling parameter to be a multiple of the number of available cores when running in local mode. For this reason, for the ASM HPC/AI school the sampling is set to be a multiple of 48.
-
-**_Note_**: In case no reference is available (the usual scenario), the best ranked model is used as reference for each stage.
-Including `caprieval` at the various stages even when no reference is provided is useful to get the rankings and scores and visualise the results (see Analysis section below).
-
-**_Note_**: The default sampling would be 1000 models for `rigidbody` of which 200 are passed to the flexible refinement in `seletop`.
-As an indication of the computational requirements, the default sampling worflow for this tutorial completes in about 37min using 12 cores on a MaxOSX M2 processor.
-In comparison, the reduced sampling run (100/40) takes about 7-8min.
-
-
-
-**_Note_**: To get a list of all possible parameters that can be defined in a specific module (and their default values) you can use the following command:
-
-
-haddock3-cfg -m \
-
-
-Add the `-d` option to get a more detailed description of parameters and use the `-h` option to see a list of arguments and options.
-
-Alternatively, you can consult the [developer's guide](https://www.bonvinlab.org/haddock3/){:target="_blank"}, where each parameter of each module is listed along with their default values, short and long descriptions, etc. Navigate to the [Modules](https://www.bonvinlab.org/haddock3/modules/index.html#){:target="_blank"} and select a module which parameters you want to display.
-
-
-In the above workflow we see in three modules a *tolerance* parameter defined. Using the *haddock3-cfg* command try to figure out what this parameter does.
-
-
-
-*__Note__* that, in contrast to HADDOCK2.X, we have much more flexibility in defining our workflow.
-As an example, we could use this flexibility by introducing a clustering step after the initial rigid-body docking stage, selecting a given number of models per cluster and refining all of those.
-For an example of this strategy see the 4 section about ensemble docking.
-
-
-
-
-### Running HADDOCK3
-
-In in the first section of the workflow above we have a parameter `mode` defining the execution mode. HADDOCK3 currently supports three difference execution modes:
-
-- **local** : In this mode, HADDOCK3 will run on the current system, using the defined number of cores (`ncores`) in the config file to a maximum of the total number of available cores on the system.
-- **batch**: In this mode, HADDOCK3 will typically be started on your local server (e.g. the login node) and will dispatch jobs to the batch system of your cluster (slurm and torque are currently supported).
-- **mpi**: HADDOCK3 also supports a pseudo parallel MPI implementation, which allows to harvest the power of multiple nodes to distribute the computations (functional but still very experimental at this stage).
-
-
-
-
-#### Execution of HADDOCK3 on the computers of the BioExcel 2025 summerschool
-
-To execute the HADDOCK3 workflow on the computational resources provided for this workshop,
-we will simply run in local mode, calling haddock3 with as argument the workflow you want to execute.
-
-{% highlight shell %}
-haddock3
-{% endhighlight %}
-
-Alternatively redirect the output to a log file and send haddock3 to the background.
-
-As an indication, running locally on an Apple M2 laptop using 10 cores, this workflow completed in 7 minutes.
-
-
-
-
-
-#### Execution of HADDOCK3 on DISCOVERER (BioExcel Sofia May 2025 workshop)
-
-
-
- View execution instructions for running HADDOCK3 on DISCOVERERexpand_more
-
-
-To execute the HADDOCK3 workflow on the computational resources provided for this workshop,
-you should create an execution script contain specific requirements for the queueing system and the HADDOCK3 configuration and execution.
-An example slurm script is provided with the data you unzipped:
-
-{% highlight shell %}
-run-haddock3-discoverer.sh
-{% endhighlight %}
-
-
-Here is an example of such an execution script (also provided in the `HADDOCK3-antibody-antigen` directory as `run-haddock3-discoverer.sh`):
-
-{% highlight shell %}
-#!/bin/bash
-#SBATCH --nodes=1
-#SBATCH --account=school-01
-#SBATCH --qos=school-01
-#SBATCH --job-name "haddock3"
-#SBATCH --tasks-per-node=50
-#SBATCH --mem-per-cpu 1500
-#SBATCH --time 04:00:00
-
-module load python/3/3.12
-module load haddock3/2025.5.0
-haddock3 workflows/docking-antibody-antigen.cfg
-
-{% endhighlight %}
-
-This file should be submitted to the batch system using the `sbatch` command:
-
-
-sbatch run-haddock3-discoverer.sh
-
-
-And you can check the status in the queue using the `squeue`command.
-
-This example run should take about 7 minutes to complete on a single node using 50 cores.
-
-
-
-
-
-
-#### Execution of HADDOCK3 on the TRUBA resources (EuroCC Istanbul April 2024 workshop)
-
-
-
- View execution instructions for running HADDOCK3 the TRUBA resourcesexpand_more
-
-
-To execute the HADDOCK3 workflow on the computational resources provided for this workshop,
-you should create an execution script contain specific requirements for the queueing system and the HADDOCK3 configuration and execution.
-Two scripts are provided with the data you unzipped, one for execution on the hamsri cluster and one for the barbun cluster:
-
-{% highlight shell %}
-run-haddock3-barbun.sh
-run-haddock3-hamsri.sh
-{% endhighlight %}
-
-Here is an example of such an execution script (also provided in the HADDOCK3-antibody-antigen directory as run-haddock3-hamsri.sh):
-
-{% highlight shell %}
-#!/bin/bash
-#SBATCH --nodes=1
-#SBATCH --tasks-per-node=54
-#SBATCH -C weka
-#SBATCH -p hamsi
-#SBATCH --time 00:30:00
-
-source ~egitim/HADDOCK/haddock3/.venv/bin/activate
-haddock3 workflows/docking-antibody-antigen.cfg
-{% endhighlight %}
-
-This file should be submitted to the batch system using the sbatch command:
-
-{% highlight shell %}
-sbatch run-haddock3-hamsri.sh
-{% endhighlight %}
-
-Note that batch submission is only possible from the scratch partition (/arf/scratch/my-home-directory)
-
-And you can check the status in the queue using the squeuecommand.
-
-This example run should take about 7 minutes to complete on a single node using 50 cores.
-
-
-
-
-
-
-#### Execution of HADDOCK3 on Fugaku (ASM 2026 HPC/AI school, Kobe Japan)
-
-
-
- View execution instructions for running HADDOCK3 on Fugakuexpand_more
-
-
-To execute the workflow on Fugaku, you can either start an interactive session or create a job file that will execute HADDOCK3 on a node,
-with HADDOCK3 running in local mode (the setup in the above configuration file with mode="local") and harvesting all core of that node (ncores=48).
-
-
-Interactive session on a node:
-
-{% highlight shell %}
-pjsub -x PJM_LLIO_GFSCACHE=/vol0003:/vol0004 -g "hp250477" --interact -L "node=1" - -L "rscgrp=int" -L "elapse=2:00:00" --sparam "wait-time=600"
-{% endhighlight %}
-
-Once the session is active, activate HADDOCK3 with:
-
-{% highlight shell %}
-source /vol0300/data/hp250477/Materials/Life_Science/20250202_Bonvin/haddock3/.venv/bin/activate
-{% endhighlight %}
-
-You can then run the workflow with:
-
-{% highlight shell %}
-haddock3 ./workflows/docking-antibody-antigen.cfg
-{% endhighlight %}
-Job submission to the batch system:
-
-
-For this execution mode you should create an execution script contain specific requirements for the queueing system and the HADDOCK3 configuration and execution.
-Here is an example of such an execution script (also provided in the HADDOCK3-antibody-antigen directory as run-haddock3-fugaku.sh):
-
-{% highlight shell %}
-#!/bin/sh -x
-#PJM -L "node=1" # Assign node 1 node
-#PJM -L "rscgrp=small" # Specify resource group
-#PJM -L "elapse=02:00:00" # Elapsed time limit 1 hour
-#PJM -g hp250477 # group name
-#PJM -x PJM_LLIO_GFSCACHE=/vol0003:/vol0004 # volume names that job uses
-#PJM -s # Statistical information output
-
-source /vol0300/data/hp250477/Materials/Life_Science/20260202-HADDOCK/haddock3/.venv/bin/activate
-haddock3 ./workflows/docking-antibody-antigen.cfg
-
-{% endhighlight %}
-
-This file should be submitted to the batch system using the pjsub command:
-
-{% highlight shell %}
-pjsub run-haddock3-fugaku.sh
-{% endhighlight %}
-
-
-
-And you can check the status in the queue using pjstat.
-
-This run should take about 25 minutes to complete on a single node using 48 arm cores.
-
-
-
-
-
-#### Execution of HADDOCK3 on ADD Ljubljana (BioExcel Adriatic edition 2026, Ljubljana, Slovenia)
-
-To execute the workflow, you can either start an interactive session or create a job file that will execute HADDOCK3 on a node,
-with HADDOCK3 running in local mode (the setup in the above configuration file with mode="local") and harvesting all core of that node (ncores=16).
-
-
-Start an interactive session on a node:
-
-{% highlight shell %}
-salloc --job-name=interactive_haddock3 --partition=amd --nodes=1 --cpus-per-task=16 --time-min=120
-{% endhighlight %}
-
-Once the session is active, activate HADDOCK3 with:
-
-{% highlight shell %}
-source /home/vreys/haddock3/.haddock3-env/bin/activate
-{% endhighlight %}
-
-You can then follow the tutorial and run all the commands present in it, such as starting a haddock3 docking workflow with:
-
-{% highlight shell %}
-haddock3 ./workflows/docking-antibody-antigen.cfg
-{% endhighlight %}
-Job submission to the batch system:
-
-
-For this execution mode you should create an execution script contain specific requirements for the queueing system and the HADDOCK3 configuration and execution.
-Here is an example of such an execution script (that can be saved under the name run-haddock3-slurm.sh):
-
-{% highlight shell %}
-#!/bin/bash
-#SBATCH --partition=amd
-#SBATCH --job-name=haddock3_run
-#SBATCH --nodes=1
-#SBATCH --cpus-per-task=16
-#SBATCH --time-min=120
-#SBATCH --output="haddock3_run_log.txt"
-
-# Source the environement
-source /home/vreys/haddock3/.haddock3-env/bin/activate
-
-# Go to the appropriate directory
-cd ~/HADDOCK3-antibody-antigen
-
-# Launch haddock3
-haddock3 workflows/docking-antibody-antigen.cfg
-
-
-{% endhighlight %}
-
-This file should be submitted to the batch system using the sbatch command:
-
-{% highlight shell %}
-sbatch run-haddock3-slurm.sh
-{% endhighlight %}
-
-
-
-And you can check the status in the queue using squeue -u Username.
-
-Also, you can follow the state of your run by looking a the content of either the log file or the slurm output using:
-
-{% highlight shell %}
-tail -f haddock3_run_log.txt
-{% endhighlight %}
-
-This run should take around 20 minutes to complete on a single node using 16 arm cores.
-
-
-
-
-#### Learn more about the various execution modes of haddock3
-
-
-
-
-
- Local executionexpand_more
-
-
-In this mode HADDOCK3 will run on the current system, using the defined number of cores (ncores)
-in the config file to a maximum of the total number of available cores on the system minus one.
-An example of the relevant parameters to be defined in the first section of the config file is:
-
-{% highlight toml %}
-# compute mode
-mode = "local"
-# 1 nodes x 50 ncores
-ncores = 50
-{% endhighlight %}
-
-In this mode HADDOCK3 can be started from the command line with as argument the configuration file of the defined workflow.
-
-{% highlight shell %}
-haddock3
-{% endhighlight %}
-
-Alternatively redirect the output to a log file and send haddock3 to the background.
-
-
-As an indication, running locally on an Apple M2 laptop using 10 cores, this workflow completed in 7 minutes.
-
-
-{% highlight shell %}
-haddock3 > haddock3.log &
-{% endhighlight %}
-
-Note: This is also the execution mode that should be used for example when submitting the HADDOCK3 job to a node of a cluster, requesting X number of cores.
-
-
-
-
-
-
-
- Exection in batch mode using slurmexpand_more
-
-
- Here is an example script for submitting via the slurm batch system:
-
-{% highlight shell %}
-#!/bin/bash
-#SBATCH --nodes=1
-#SBATCH --tasks-per-node=50
-#SBATCH -J haddock3
-#SBATCH --partition=medium
-
-# activate the haddock3 conda environment
-source $HOME/miniconda3/etc/profile.d/conda.sh
-conda activate haddock3
-
-# go to the run directory
-cd $HOME/HADDOCK3-antibody-antigen
-
-# execute
-haddock3
-{% endhighlight %}
-
-
-
- In this mode HADDOCK3 will typically be started on your local server (e.g. the login node) and will dispatch jobs to the batch system of your cluster.
- Two batch systems are currently supported: slurm and torque (defined by the batch_type parameter).
- In the configuration file you will have to define the queue name and the maximum number of concurrent jobs sent to the queue (queue_limit).
-
- Since HADDOCK3 single model calculations are quite fast, it is recommended to calculate multiple models within one job submitted to the batch system.
- he number of model per job is defined by the concat parameter in the configuration file.
- You want to avoid sending thousands of very short jobs to the batch system if you want to remain friend with your system administrators...
-
- An example of the relevant parameters to be defined in the first section of the config file is:
-
- {% highlight toml %}
- # compute mode
- mode = "batch"
- # batch system
- batch_type = "slurm"
- # queue name
- queue = "short"
- # number of concurrent jobs to submit to the batch system
- queue_limit = 100
- # number of models to produce per submitted job
- concat = 10
- {% endhighlight %}
-
- In this mode HADDOCK3 can be started from the command line as for the local mode.
-
-
-
-
-
-
- Exection in MPI modeexpand_more
-
-
-
-HADDOCK3 supports a parallel pseudo-MPI implementation. For this to work, the mpi4py library must have been installed at installation time.
-Refer to the (MPI-related instructions).
-
-The execution mode should be set to `mpi` and the total number of cores should match the requested resources when submitting to the batch system.
-
-An example of the relevant parameters to be defined in the first section of the config file is:
-
-{% highlight toml %}
-# compute mode
-mode = "mpi"
-# 5 nodes x 50 tasks = ncores = 250
-ncores = 250
-{% endhighlight %}
-
-In this execution mode the HADDOCK3 job should be submitted to the batch system requesting the corresponding number of nodes and cores per node.
-
-
- {% highlight shell %}
- #!/bin/bash
- #SBATCH --nodes=5
- #SBATCH --tasks-per-node=50
- #SBATCH -J haddock3mpi
-
- # Make sure haddock3 is activated
- source $HOME/miniconda3/etc/profile.d/conda.sh
- conda activate haddock3
-
- # go to the run directory
- # edit if needed to specify the correct location
- cd $HOME/HADDOCK3-antibody-antigen
-
- # execute
- haddock3 \
- {% endhighlight %}
-
-
-
-
-
-
-
-
-
-## Analysis of docking results
-
-In case something went wrong with the docking (or simply if you do not want to wait for the results) you can find the following precalculated runs in the `runs` directory:
-- `run1`: docking run created using the unbound antibody.
-- `run1-af2`: docking run created using the Alphafold-multimer antibody (see 3).
-- `run1-abb`: docking run created using the Immunebuilder antibody (see 3).
-- `run1-ens`: docking run created using an ensemble of antibody models (see 4).
-- `run-scoring`: scoring run created using various models obtained at the previous stages (see 6).
-
-
-Once your run has completed - inspect the content of the resulting directory.
-You will find the various steps (modules) of the defined workflow numbered sequentially starting at 0, e.g.:
-
-{% highlight shell %}
-> ls run1/
- 00_topoaa/
- 01_rigidbody/
- 02_caprieval/
- 03_seletop/
- 04_flexref/
- 05_caprieval/
- 06_emref/
- 07_caprieval/
- 08_clustfcc/
- 09_seletopclusts/
- 10_caprieval/
- 11_contactmap/
- analysis/
- data/
- log
- toppar/
- traceback/
-{% endhighlight %}
-
-In addition, there is a log file (text file) and four additional directories:
-
-- the `analysis` directory contains various plots to visualize the results for each caprieval step and a general report (`report.html`) that provides all statistics with various plots. You can open this file in your preferred web browser
-- the `data` directory contains the input data (PDB and restraint files) for the various modules, as well as an input workflow (in `configurations` directory)
-- the `toppar` directory contains the force field topology and parameter files (only present when running in self-contained mode)
-- the `traceback` directory contains `traceback.tsv`, which links all models to see which model originates from which throughout all steps of the workflow.
-
-You can find information about the duration of the run at the bottom of the log file.
-
-Each sampling/refinement/selection module will contain PDB files.
-For example, the `09_seletopclusts` directory contains the selected models from each cluster. The clusters in that directory are numbered based
-on their rank, i.e. `cluster_1` refers to the top-ranked cluster. Information about the origin of these files can be found in that directory in the `seletopclusts.txt` file.
-
-The simplest way to extract ranking information and the corresponding HADDOCK scores is to look at the `XX_caprieval` directories (which is why it is a good idea to have it as the final module, and possibly as intermediate steps). This directory will always contain a `capri_ss.tsv` single model statistics file, which contains the model names, rankings and statistics (score, iRMSD, Fnat, lRMSD, ilRMSD and dockq score). E.g. for `10_caprieval`:
-
-
-
-If clustering was performed prior to calling the `caprieval` module, the `capri_ss.tsv` file will also contain information about to which cluster the model belongs to and its ranking within the cluster.
-
-The relevant statistics are:
-
-* **score**: *the HADDOCK score (arbitrary units)*
-* **irmsd**: *the interface RMSD, calculated over the interfaces the molecules*
-* **fnat**: *the fraction of native contacts*
-* **lrmsd**: *the ligand RMSD, calculated on the ligand after fitting on the receptor (1st component)*
-* **ilrmsd**: *the interface-ligand RMSD, calculated over the interface of the ligand after fitting on the interface of the receptor (more relevant for small ligands for example)*
-* **dockq**: *the DockQ score, which is a combination of irmsd, lrmsd and fnat and provides a continuous scale between 1 (exactly equal to reference) and 0*
-
-Various other terms are also reported including:
-
-* **bsa**: *the buried surface area (in squared angstroms)*
-* **elec**: *the intermolecular electrostatic energy*
-* **vdw**: *the intermolecular van der Waals energy*
-* **desolv**: *the desolvation energy*
-
-
-The iRMSD, lRMSD and Fnat metrics are the ones used in the blind protein-protein prediction experiment [CAPRI](https://capri.ebi.ac.uk/){:target="_blank"} (Critical PRediction of Interactions).
-
-In CAPRI the quality of a model is defined as (for protein-protein complexes):
-
-* **acceptable model**: i-RMSD < 4Å or l-RMSD < 10Å and Fnat > 0.1 (0.23 < DOCKQ < 0.49)
-* **medium quality model**: i-RMSD < 2Å or l-RMSD < 5Å and Fnat > 0.3 (0.49 < DOCKQ < 0.8)
-* **high quality model**: i-RMSD < 1Å or l-RMSD < 1Å and Fnat > 0.5 (DOCKQ > 0.8)
-
-
-Based on these CAPRI criteria, what is the quality of the best model listed above (_cluster_1_model_1.pdb_)?
-
-
-In case where the `caprieval` module is called after a clustering step, an additional `capri_clt.tsv` file will be present in the directory.
-This file contains the cluster ranking and score statistics, averaged over the minimum number of models defined for clustering
-(4 by default), with their corresponding standard deviations. E.g.:
-
-
-
-
-In this file you find the cluster rank (which corresponds to the naming of the clusters in the previous `seletop` directory), the cluster ID (which is related to the size of the cluster, 1 being always the largest cluster), the number of models (n) in the cluster and the corresponding statistics (averages + standard deviations). The corresponding cluster PDB files will be found in the preceeding `09_seletopclusts` directory.
-
-While these simple text files can be easily checked from the command line already, they might be cumbersome to read.
-For that reason, we have developed a post-processing analysis that automatically generates html reports for all `caprieval` steps in the workflow.
-These are located in the respective `analysis/XX_caprieval` directories and can be viewed using your favorite web browser.
-
-
-
-
-### Cluster statistics
-
-Let us now analyse the docking results. Use for that either your own run or a pre-calculated run provided in the `runs` directory.
-Go into the `analysis/10_caprieval_analysis` directory of the respective run directory (if needed copy the run or that directory to your local computer) and open in a web browser the `report.html` file. Be patient as this page contains interactive plots that may take some time to generate.
-
-On the top of the page, you will see a table that summarises the cluster statistics (taken from the `capri_clt.tsv` file).
-The columns (corresponding to the various clusters) are sorted by default on the cluster rank, which is based on the HADDOCK score (found on the 4th row of the table).
-As this is an interactive table, you can sort it as you wish by using the arrows present in the first column.
-Simply click on the arrows of the term you want to use to sort the table (and you can sort it in ascending or descending order).
-A snapshot of this table is shown below:
-
-
-
-
-
-You can also view this report online [here](plots/report.html){:target="_blank"}
-
-*__Note__* that in case the PDB files are still compressed (gzipped) the download links will not work. Also online visualisation is not enabled. To overcome this disk space storge solution, consider adding the global parameter `clean = true` at the begining of your configuration file.
-
-
-Inspect the final cluster statistics
-
-How many clusters have been generated?
-
-Look at the score of the first few clusters: Are they significantly different if you consider their average scores and standard deviations?
-
-Since for this tutorial we have at hand the crystal structure of the complex, we provided it as reference to the `caprieval` modules.
-This means that the iRMSD, lRMSD, Fnat and DockQ statistics report on the quality of the docked model compared to the reference crystal structure.
-
-How many clusters of acceptable or better quality have been generate according to CAPRI criteria?
-
-What is the rank of the best cluster generated?
-
-What is the rank of the first acceptable of better cluster generated?
-
-
-
-
-### Visualizing the scores and their components
-
-
-Next to the cluster statistic table shown above, the `report.html` file also contains a variety of plots displaying the HADDOCK score
-and its components against various CAPRI metrics (i-RMSD, l-RMSD, Fnat, Dock-Q) with a color-coded representation of the clusters.
-These are interactive plots. A menu on the top right of the first row (you might have to scroll to the rigth to see it)
-allows you to zoom in and out in the plots and turn on and off clusters.
-
-
-
-
-
-As a reminder, you can also view this report online [here](plots/report.html){:target="_blank"}
-
-
-Examine the plots (remember here that higher DockQ values and lower i-RMSD values correspond to better models)
-
-
-
-Finally, the report also shows plots of the cluster statistics (distributions of values per cluster ordered according to their HADDOCK rank):
-
-
-
-
-
-For this antibody-antigen case, which of the score components correlates best with the quality of the models?
-
-
-
-
-### Some single structure analysis
-
-
-Going back to command line analysis, we are providing in the `scripts` directory a simple script that extracts some model statistics for acceptable or better models from the `caprieval` steps.
-To use it, simply call the script with as argument the run directory you want to analyze, e.g.:
-
-
-./scripts/extract-capri-stats.sh ./runs/run1
-
-
-
-
-View the output of the scriptexpand_more
-
-
-==============================================
-== runs/run1/02_caprieval/capri_ss.tsv
-==============================================
-Total number of acceptable or better models: 25 out of 100
-Total number of medium or better models: 15 out of 100
-Total number of high quality models: 1 out of 100
-
-First acceptable model - rank: 1 i-RMSD: 1.196 Fnat: 0.672 DockQ: 0.741
-First medium model - rank: 1 i-RMSD: 1.196 Fnat: 0.672 DockQ: 0.741
-Best model - rank: 17 i-RMSD: 0.982 Fnat: 0.759 DockQ: 0.774
-==============================================
-== runs/run1/05_caprieval/capri_ss.tsv
-==============================================
-Total number of acceptable or better models: 14 out of 40
-Total number of medium or better models: 14 out of 40
-Total number of high quality models: 5 out of 40
-
-First acceptable model - rank: 1 i-RMSD: 0.992 Fnat: 0.897 DockQ: 0.834
-First medium model - rank: 1 i-RMSD: 0.992 Fnat: 0.897 DockQ: 0.834
-Best model - rank: 11 i-RMSD: 0.789 Fnat: 0.776 DockQ: 0.842
-==============================================
-== runs/run1/07_caprieval/capri_ss.tsv
-==============================================
-Total number of acceptable or better models: 14 out of 40
-Total number of medium or better models: 14 out of 40
-Total number of high quality models: 3 out of 40
-
-First acceptable model - rank: 1 i-RMSD: 1.037 Fnat: 0.931 DockQ: 0.841
-First medium model - rank: 1 i-RMSD: 1.037 Fnat: 0.931 DockQ: 0.841
-Best model - rank: 11 i-RMSD: 0.841 Fnat: 0.897 DockQ: 0.875
-==============================================
-== runs/run1/10_caprieval/capri_ss.tsv
-==============================================
-Total number of acceptable or better models: 4 out of 12
-Total number of medium or better models: 4 out of 12
-Total number of high quality models: 1 out of 12
-
-First acceptable model - rank: 1 i-RMSD: 1.037 Fnat: 0.931 DockQ: 0.841
-First medium model - rank: 1 i-RMSD: 1.037 Fnat: 0.931 DockQ: 0.841
-Best model - rank: 3 i-RMSD: 0.908 Fnat: 0.897 DockQ: 0.855
-
- In terms of iRMSD values, we only observe very small differences in the best model.
- The fraction of native contacts and the DockQ scores are however improving much more after flexible refinement but increases again slightly after final minimisation.
- All this will of course depend on how different are the bound and unbound conformations and the amount of data used to drive the docking process.
- In general, from our experience, the more and better data at hand, the larger the conformational changes that can be induced.
-
- This is not the case. The scoring function is not perfect, but does a reasonable job at ranking models of acceptable or better quality on top in this case.
-
Top-ranked model of the top cluster (cluster1_model_1) superimposed onto the reference crystal structure (in yellow)
-
-
-
-
-
-
-
-
-
-
-
-## Conclusions
-
-We have demonstrated the usage of HADDOCK3 in an antibody-antigen docking scenario making use of the paratope information on the antibody side (i.e. no prior experimental information, but computational predictions) and an NMR-mapped epitope for the antigen.
-Compared to the static HADDOCK2.X workflow, the modularity and flexibility of HADDOCK3 allow to customise the docking protocols and to run a deeper analysis of the results.
-HADDOCK3's intrinsic flexibility can be used to improve the performance of antibody-antigen modelling compared to the results we presented in our
-[Structure 2020](https://doi.org/10.1016/j.str.2019.10.011){:target="_blank"} article and in the [related HADDOCK2.4 tutorial](/education/HADDOCK24/HADDOCK24-antibody-antigen){:target="_blank"}.
-
-
-
-
-
-## BONUS 1: Dissecting the interface energetics: what is the impact of a single mutation?
-
-Mutations at the binding interfaces can have widely varying effects on binding affinity - some may be negligible, while others can significantly strengthen or weaken the interaction. Exploring these mutations helps identify critical amino acids for redesigning structurally characterized protein-protein interfaces, which paves the way for developing protein-based therapeutics to deal with a diverse range of diseases.
-To pinpoint such amino acids positions, the residues across the protein interaction surfaces are either randomly or strategically mutated. Scanning mutations in this manner is experimentally costly. Therefore, computational methods have been developed to estimate the impact of an interfacial mutation on protein-protein interactions.
-These computational methods come in two main flavours. One involves rigorous free energy calculations, and, while highly accurate, these methods are computationally expensive. The other category includes faster, approximate approaches that predict changes in binding energy using statistical potentials, machine learning, empirical scoring functions etc. Though less precise, these faster methods are practical for large-scale screening and early-stage analysis. In this bonus exercise, we will take a look at two quick ways of estimating the effect of a single mutation in the interface.
-
-
-### PROT-ON and haddock3-scoring to inspect a single mutation
-
-PROT-ON (Structure-based detection of designer mutations in PROTein-protein interface mutatiONs) is a tool and [online server](http://proton.tools.ibg.edu.tr:8001/about){:target="_blank"} that scans all possible interfacial mutations and **predicts ΔΔG score** by using EvoEF1 (active in both on the web server and stand-alone versions) or FoldX (active only in the stand-alone version) with the aim of finding the most mutable positions. The original publication describing PROT-ON can be found [here](https://www.frontiersin.org/journals/molecular-biosciences/articles/10.3389/fmolb.2023.1063971/full){:target="_blank"}.
-
-Here we will use PROT-ON to analyse the interface of our antibody-antigen complex. For that, we will use the provided matched reference structure (`4G6M-matched.pdb`) in which both chains of the antibody have the same chainID (A), which allows us to analyse all interface residues of the antibody at once.
-
-__Note:__ Pre-calculated PROT-ON results for this system can be accessed [here](http://proton.tools.ibg.edu.tr:8001/result/4G6M_matched_chain_A_EvoEF1){:target="_blank"}.
-
-
-Connect to the PROT-ON server page (link above) and fill in the following fields:
-
-
-
-Specify your run name* --> 4G6M_matched
-
-
-
-Choose / Upload your protein complex* --> Select the provided _4G6M-matched.pdb_ file
-
-
-
-Which dimer chains should be analyzed* --> Select chain A for the 1st molecule and B for the 2nd
-
-
-Pick the monomer for mutational scanning* --> Select the first molecule - the antibody (toggle the switch ON under the chain A)
-
-
-
-Click on the Submit button
-
-
-Your run should complete in 5-10 minutes. Once finished, you will be presented with a result page summarising the most depleting (ones that decrease the binding affinity) and most enriching (ones that increase the binding affinity) mutations.
-
-
-Which possible mutation would you propose to improve the binding affinity of the antibody?
-
-
-
-
- See answerexpand_more
-
-The most enriching mutation is S150W with a -3.69 ΔΔG score.
-
-
-
-
-Inspect the proposed amino acid in PyMol. Can you rationalise why it might increase the affinity?
-
-
-With HADDOCK3, it is possible to take a step further. To perform the mutation, simply rename the desired residue and score such model - HADDOCK will take care of the topology regardless of the side chain differences and energy minimisation of the model. To do so, first either edit _4G6M-matched.pdb_ in your favourite text editor and save this new file as _4G6M_matched_S150W.pdb_, or use the command line:
-
-sed 's/SER\ A\ 150/TRP\ A\ 150/g' 4G6M_matched.pdb > 4G6M_matched_S150W.pdb
-
-
-Next, score the mutant using the command-line tool `haddock3-score`.
-This tool performs a short workflow composed of the `topoaa` and `emscoring` modules. Use flag `--outputpdb` to save energy-minimized model:
-
-haddock3-score 4G6M_matched_S150W.pdb \-\-outputpdb
-
-
-
-Use _haddock3-score_ to calculate the score of the 4G6M-matched.pdb. Do you see a difference between wild-type and mutant scores?
-Might such single-residue mutation affect the binding affinity?
-
-
-
-Inspect the energy-minimized mutant model (4G6M_matched_S150W_hs.pdb) visually.
-Can you rationalise why such a mutation might increase the affinity?
-
-
-
-
-
- Zoom in on the mutated residueexpand_more
-
-
-
-
- TRP150 is stacking with TYR24
-
-
-
-
-
-
-
-### Alanine Scanning module
-
-Another way of exploring interface energetics is by using the `alascan` module of HADDOCK3. `alascan` stands for "Alanine Scanning module".
-
-This module is capable of mutating interface residues to Alanine and calculating the **Δ HADDOCK score** between the wild-type and mutant, thus providing a measure of the impact of each individual mutation. It is possible to scan all interface residues one by one or limit this scanning to a selected by user set of residues. By default, the mutation to Alanine is performed, as its side chain is just a methyl group, so side chain perturbations are minimal, as well as possible secondary structure changes. It is possible to perform the mutation to any other amino acid type - at your own risk, as such mutations may introduce structural uncertainty.
-
-**Important**: 1/ `alascan` calculates the difference between wild-type score vs mutant score, i.e. positive `Δscore` indicative of the enriched (stronger) binding and negative `Δscore` is indicative of the depleted (weaker) binding; 2/ Inside `alascan`, a short energy minimization of an input structure is performed, i.e. there's no need to include an additional refinement module prior to `alascan`.
-
-Here is an example of the workflow to scan interface energetics:
-{% highlight toml %}
-# ====================================================================
-# Scanning interface residues with haddock3
-# ====================================================================
-
-# directory in which the scoring will be done
-run_dir = "run-energetics-alascan"
-
-# compute mode
-mode = "local"
-ncores = 50
-
-# Post-processing to generate statistics and plots
-postprocess = true
-clean = true
-
-molecules = [
- "pdbs/4G6M_matched.pdb",
- ]
-
-# ====================================================================
-# Parameters for each stage are defined below
-# ====================================================================
-[topoaa]
-
-[alascan]
-# mutate each interface residue to Alanine
-scan_residue = 'ALA'
-# generate plot of delta score and its components per each mutation
-plot = true
-
-# ====================================================================
-{% endhighlight %}
-
-A scoring scenario configuration file is provided in the `workflows/` directory as `interaction-energetics.cfg`, and precomputed results are in `runs/run-energetics-alascan`.
-The output folder contains, among others, a directory titled `1_alascan` with a file `scan_4G6M_matched_haddock.tsv` that lists each mutation, corresponding score and individual terms:
-
-##########################################################
-# `alascan` results for 4G6M_matched_haddock.pdb
-#
-# native score = -145.5891
-#
-# z_score is calculated with respect to the other residues
-##########################################################
-chain res ori_resname end_resname score vdw elec desolv bsa delta_score delta_vdw delta_elec delta_desolv delta_bsa z_score
-A 212 LYS ALA -136.33 -66.16 -367.66 3.37 1660.53 -9.26 2.52 -75.12 3.24 37.57 -0.48
-A 103 ASP ALA -129.64 -59.93 -365.23 3.34 1677.97 -15.95 -3.71 -77.56 3.27 20.13 -1.41
-A 54 TRP ALA -138.18 -58.34 -435.53 7.27 1690.80 -7.41 -5.30 -7.26 -0.66 7.30 -0.22
-A 32 SER ALA -143.66 -60.55 -447.37 6.36 1691.72 -1.93 -3.09 4.59 0.24 6.38 0.55
-A 58 ASP ALA -121.65 -63.49 -306.77 3.20 1639.20 -23.94 -0.15 -136.01 3.41 58.90 -2.52
-A 33 GLY ALA -148.50 -61.56 -473.22 7.71 1693.18 2.91 -2.08 30.43 -1.10 4.92 1.22
-...
-
- ASP58 makes h-bonds with two neighbouring residues
-
-
-
-We can see one hydrogen bond between ASP58 and LYS98, and two hydrogen bonds ASP58 and LYS94.
-Mutating ASP58 to ALA should result in the disappearance of those h-bonds, and the overall depletion of the binding.
-This is reflected by the high negative value (-136.01) of `delta_elec` in either of .tsv files.
-
-Let us test several mutations to confirm our hypothesis.
-Here is an example of the workflow to perform such mutations and save generated models:
-
-{% highlight ini %}
-# ====================================================================
-# Mutating selected interface residue with haddock3
-# ====================================================================
-
-# directory in which the scoring will be done
-run_dir = "run-energetics-mutations"
-
-# compute mode
-mode = "local"
-ncores = 50
-
-# Post-processing to generate statistics and plots
-postprocess = true
-clean = true
-
-molecules = ["pdbs/4G6M_matched.pdb"]
-
-# ====================================================================
-# Parameters for each stage are defined below
-# ====================================================================
-[topoaa]
-
-[alascan]
-# mutate residue 58 of chain A to Arginine
-scan_residue = "ARG"
-resdic_A = [58]
-# save energy-minimised mutant model
-output_mutants= true
-
-[alascan]
-scan_residue = "GLY"
-resdic_A = [58]
-output_mutants= true
-
-[alascan]
-scan_residue = "TRP"
-resdic_A = [58]
-output_mutants= true
-
-{% endhighlight %}
-
-Configuration file for this scenario can be found in `workflows/single-residue-mutations.cfg`, precomputed results are in `run-residue-mutations`. The output folder contains, among others, an energy-minimised mutant model `1_alascan/4G6M_matched_haddock-A_D58R.pdb.gz`, and tables `.tsv` with energetics.
-
-
-Take a look at the scores of the mutants. Which mutation depletes binding the most?
-
-
-
-Inspect the mutant vs wild-type complex. Can you see the difference at the interface level?
-
-
-
-
- See the overlay of the mutant onto the wild-type structure expand_more
-
-
-
-
- wild-type residue ASP58 is displayed in pink, and mutant residue AGR58 is displayed in orange
-
-
-
-
-
-
-
-
-Compare values obtained with [alascan] to the corresponding values obtained with PROT-ON. Are they different? If yes, can you think of a reason why?
-
-
-
-
- See answerexpand_more
-
-The values themselves are expected to differ, because [alascan] calculates ΔHADDOCK score, while PROT-ON predicts ΔΔG.
-Moreover, both tools are making predictions using different methods, so it is normal to have different results.
-However, if both tools consistently identify the same mutations as binding enriching or depleting - this may signal that selected residues indeed play a key role in binding affinity.
-
-
-
-Now let us consider how sensitive this kind of analysis is to the quality of the docking model.
-Instead of using the crystal structure, repeat this analysis using the best model of the top-ranked cluster or the best model with the lowest LRMSD value.
-
-
-Consider the most binding-enrishing/-depleting mutations predicted based on your favourite docking model.
-How different are those compared to the mutations, predicted based on the crystal structure?
-
-
-
-
-
-
-## BONUS 2: Does the antibody bind to a known interface of interleukin? ARCTIC-3D analysis
-
-Gevokizumab is a highly specific antibody that targets an allosteric site of Interleukin-1β (IL-1β) in PDB file *4G6M*, thus reducing its binding affinity for its substrate, interleukin-1 receptor type I (IL-1RI). Canakinumab, another antibody binding to IL-1β, has a different mode of action, as it competes directly with the binding site of IL-1RI (in PDB file *4G6J*). For more details please check [this article](https://www.sciencedirect.com/science/article/abs/pii/S0022283612007863?via%3Dihub){:target="_blank"}.
-
-We will now use our new software, [ARCTIC-3D](https://www.nature.com/articles/s42003-023-05718-w){:target="_blank"}, to visualize the binding interfaces formed by IL-1β. First, the program retrieves all the existing binding surfaces formed by IL-1β from the [PDBe website](https://www.ebi.ac.uk/pdbe/){:target="_blank"}. Then, these binding surfaces are compared and clustered together if they span a similar region of the selected protein (IL-1β in our case).
-
-We will run an ARCTIC-3D job targeting the uniprot ID of human Interleukin-1 beta, namely [P01584](https://www.uniprot.org/uniprotkb/P01584/entry){:target="_blank"}.
-
-For this first open the ARCTIC-3D web-server page [here](https://wenmr.science.uu.nl/arctic3d/){:target="_blank"}.
-
-
-Insert the selected UniProt ID in the **UniprotID** field.
-
-
-
-Leave the other parameters as they are and click on **Submit**.
-
-
-Wait a few seconds for the job to complete or access a precalculated run [here](https://wenmr.science.uu.nl/arctic3d/example-P01584){:target="_blank"}.
-
-
-How many interface clusters were found for this protein?
-
-
-Once you download the output archive, you can find the clustering information presented in the dendrogram:
-
-
-
-
-
-We can see how the two *4G6M* antibody chains are recognized as a unique cluster, clearly separated from the other binding surfaces and, in particular, from those proper to IL-1RI (uniprot ID P14778).
-
-
-Re-run ARCTIC-3D with a clustering threshold equal to 0.95
-
-
-This means that the clustering will be looser, therefore lumping more dissimilar surfaces into the same object.
-
-You can inspect a precalculated run [here](https://wenmr.science.uu.nl/arctic3d/example-P01584-095){:target="_blank"}.
-
-
-How do the results change? Are gevokizumab or canakinumab PDB files being clustered with any IL-1RI-related interface?
-
-
-
-
-
-
-
-## BONUS 3: How good are AI-based models of antibody for docking?
-
-The release of [AlphaFold2 in late 2020](https://www.nature.com/articles/s41586-021-03819-2) has brought structure prediction methods to a new frontier, providing accurate models for the majority of known proteins. This revolution did not spare antibodies, with [Alphafold2-multimer](https://github.com/sokrypton/ColabFold){:target="_blank"} and other prediction methods (most notably [ABodyBuilder2](https://opig.stats.ox.ac.uk/webapps/sabdab-sabpred/sabpred/abodybuilder2/){:target="_blank"}, from the ImmuneBuilder suite) performing nicely on the variable regions.
-
-For a short introduction to AI and AlphaFold2 refer to this other tutorial [introduction](/education/molmod_online/alphafold/#introduction){:target="_blank"}.
-
-For antibody modelings, CDR loops are clearly the most challenging region to be predicted given their high sequence variability and flexibility.
-Multiple Sequence Alignment (MSA)-derived information is also less useful in this context.
-
-Here we will see whether the antibody models given by Alphafold2-multimer and ABodyBuilder2 can be used for generating reliable models of the antibody-antigen complex by docking, instead of the unbound form used in this tutorial, which, in many cases, will not be available.
-
-
-### Analysing the AI models
-
-We already ran the prediction with these two tools, and you can find the resulting models in the `pdbs` directory as:
-
-- `4g6k_Abodybuilder2.pdb`
-- `4g6k_AF2_multimer.pdb`
-
-
-As was demonstrated in the tutorial, those files must be preprocessed for their use in HADDOCK. Docking-ready files are also provided in the `pdbs` directory:
-
-
-- `4G6K_abb_clean.pdb`
-- `4G6K_af2_clean.pdb`
-
-
-Load the experimental unbound structure (`4G6K_clean.pdb`) and the two AI models in PyMOL to see whether they resemble the experimental unbound structure.
-
-
-File menu -> Open -> select 4G6K_clean.pdb
-
-
-File menu -> Open -> select 4G6K_abb_clean.pdb
-
-
-File menu -> Open -> select 4G6K_af2_clean.pdb
-
-
-Align the models to the experimental unbound structure
-
-
-alignto 4G6K_clean
-
-
-
-Which model is the closest to the unbound conformation?
-
-
-
-
- See the RMSD valuesexpand_more
-
-
- 4G6K_abb_clean RMSD = 0.428 Å
- 4G6K_af2_clean RMSD = 0.765 Å
-
- 4G6K_abb_clean RMSD = 0.330 Å
- 4G6K_af2_clean RMSD = 0.675 Å
- 4G6K_clean RMSD = 0.393 Å
-
-
-
-
-
-
-
-
-### Docking performance using AI-based antibody models
-
-We can repeat the docking as described above in our tutorial, but using this time either the ABodyBuilder2 or AlphaFold2 models as input.
-For this, modify your haddock3 configuration file, changing the input PDB file of the first molecule (the antibody) using the respective HADDOCK-ready models provided in the `pdbs` directory.
-You will also need to change the restraint filename used to keep the two parts of the antibody together (those files are present in the `restraints` directory.
-
-Further, run haddock3 as described above.
-
-Pre-calculated runs are provided in the `runs` directory. Analyse your run (or the pre-calculated ones) as described previously.
-
-
-Which starting structure of the antibody gives the best results in terms of cluster quality and ranking?
-
-
-
-
- See the cluster statistics expand_more
-
-
-==============================================
-== run1/10_caprieval/capri_clt.tsv
-==============================================
-Total number of acceptable or better clusters: 1 out of 3
-Total number of medium or better clusters: 1 out of 3
-Total number of high quality clusters: 0 out of 3
-
-First acceptable cluster - rank: 1 i-RMSD: 1.049 Fnat: 0.879 DockQ: 0.815
-First medium cluster - rank: 1 i-RMSD: 1.049 Fnat: 0.879 DockQ: 0.815
-Best cluster - rank: 1 i-RMSD: 1.049 Fnat: 0.879 DockQ: 0.815
-
-==============================================
-== run1-abb/10_caprieval/capri_clt.tsv
-==============================================
-Total number of acceptable or better clusters: 1 out of 5
-Total number of medium or better clusters: 1 out of 5
-Total number of high quality clusters: 0 out of 5
-
-First acceptable cluster - rank: 1 i-RMSD: 1.134 Fnat: 0.841 DockQ: 0.796
-First medium cluster - rank: 1 i-RMSD: 1.134 Fnat: 0.841 DockQ: 0.796
-Best cluster - rank: 1 i-RMSD: 1.134 Fnat: 0.841 DockQ: 0.796
-
-==============================================
-== run1-af2/10_caprieval/capri_clt.tsv
-==============================================
-Total number of acceptable or better clusters: 2 out of 3
-Total number of medium or better clusters: 0 out of 3
-Total number of high quality clusters: 0 out of 3
-
-First acceptable cluster - rank: 1 i-RMSD: 3.974 Fnat: 0.289 DockQ: 0.239
-First medium cluster - rank: i-RMSD: Fnat: DockQ:
-Best cluster - rank: 3 i-RMSD: 3.305 Fnat: 0.302 DockQ: 0.290
-
-==============================================
-== run1/07_caprieval/capri_ss.tsv
-==============================================
-...
-First acceptable model - rank: 1 i-RMSD: 1.037 Fnat: 0.931 DockQ: 0.841
-First medium model - rank: 1 i-RMSD: 1.037 Fnat: 0.931 DockQ: 0.841
-Best model - rank: 11 i-RMSD: 0.841 Fnat: 0.897 DockQ: 0.875
-
-==============================================
-== run1-abb/07_caprieval/capri_ss.tsv
-==============================================
-...
-First acceptable model - rank: 1 i-RMSD: 0.990 Fnat: 0.931 DockQ: 0.860
-First medium model - rank: 1 i-RMSD: 0.990 Fnat: 0.931 DockQ: 0.860
-Best model - rank: 1 i-RMSD: 0.990 Fnat: 0.931 DockQ: 0.860
-
-==============================================
-== run1-af2/07_caprieval/capri_ss.tsv
-==============================================
-...
-First acceptable model - rank: 1 i-RMSD: 3.246 Fnat: 0.362 DockQ: 0.389
-First medium model - rank: i-RMSD: Fnat: DockQ:
-Best model - rank: 21 i-RMSD: 2.474 Fnat: 0.362 DockQ: 0.468
-
-
-
-
-
-
-
-
-### Conclusions - AI-based docking
-
-All three antibody structures used in input give good to reasonable results.
-The unbound and the ABodyBuilder2 antibodies provided better results, with the best cluster showing models within 1 angstrom of interface-RMSD with respect to the unbound structure.
-Using the Alphafold2 structure in this case is not the best option, as the input antibody is not perfectly modelled in its H3 loop.
-
-
-
-
-
-## BONUS 4: Ensemble docking using a combination of exprimental and AI-predicted antibody structures
-
-
-Instead of running haddock3 using a specific input structure of the antibody, we can also use an ensemble of all available models.
-Such an ensemble can be created from the individual models using `pdb_mkensemble` from PDB-tools:
-
-
-pdb_mkensemble 4G6K_clean.pdb 4G6K_abb_clean.pdb 4G6K_af2_clean.pdb > 4G6K-ensemble.pdb
-
-
-This ensemble file is provided in the `pdbs` directory.
-
-Now we can make use of the flexibility of haddock3 in defining workflows to add a clustering step after the rigid body docking step in order to make sure that models originating from all models will ideally be selected for the refinement steps (provided they do cluster). This modified workflow looks like:
-
-
-{% highlight toml %}
-# ====================================================================
-# Antibody-antigen docking example with restraints from the antibody
-# paratope to the NMR-identified epitope on the antigen
-# ====================================================================
-
-# directory in which the scoring will be done
-run_dir = "run-ens-CDR-NMR-CSP"
-
-# compute mode
-mode = "local"
-ncores = 50
-
-# Post-processing to generate statistics and plots
-postprocess = true
-clean = true
-
-molecules = [
- "pdbs/4G6K-ensemble.pdb",
- "pdbs/4I1B_clean.pdb"
- ]
-
-# ====================================================================
-# Parameters for each stage are defined below, prefer full paths
-# ====================================================================
-[topoaa]
-
-[rigidbody]
-# CDR to NMR epitope ambig restraints
-ambig_fname = "restraints/ambig-paratope-NMR-epitope.tbl"
-# Restraints to keep the antibody chains together
-unambig_fname = "restraints/antibody-unambig.tbl"
-# Reduced sampling (150 instead of the default of 1000)
-# Increased to 150 so that each conformation is sampled 50 times
-sampling = 150
-
-[caprieval]
-reference_fname = "pdbs/4G6M_matched.pdb"
-
-[clustfcc]
-plot_matrix = true
-
-[seletopclusts]
-top_models = 10
-
-[caprieval]
-reference_fname = "pdbs/4G6M_matched.pdb"
-
-[flexref]
-tolerance = 5
-# CDR to NMR epitope ambig restraints
-ambig_fname = "restraints/ambig-paratope-NMR-epitope.tbl"
-# Restraints to keep the antibody chains together
-unambig_fname = "restraints/antibody-unambig.tbl"
-
-[caprieval]
-reference_fname = "pdbs/4G6M_matched.pdb"
-
-[emref]
-tolerance = 5
-# CDR to NMR epitope ambig restraints
-ambig_fname = "restraints/ambig-paratope-NMR-epitope.tbl"
-# Restraints to keep the antibody chains together
-unambig_fname = "restraints/antibody-unambig.tbl"
-
-[caprieval]
-reference_fname = "pdbs/4G6M_matched.pdb"
-
-[clustfcc]
-plot_matrix = true
-
-[seletopclusts]
-top_models = 4
-
-[caprieval]
-reference_fname = "pdbs/4G6M_matched.pdb"
-
-[contactmap]
-
-# ====================================================================
-
-{% endhighlight %}
-
-
-Our workflow consists of the following 14 modules:
-
-0. **`topoaa`**: *Generates the topologies for the CNS engine and builds missing atoms*
-1. **`rigidbody`**: *Performs Rigid body energy minimisation* - with increased sampling (150 models - 50 per input model)
-2. **`caprieval`**: *Calculates CAPRI metrics*
-3. **`clustfcc`**: *Clustering of models based on the fraction of common contacts (FCC)*
-4. **`seletopclusts`**: *Selects the top models of all clusters* - In this case, we select max 10 models per cluster.
-5. **`caprieval`**: *Calculates CAPRI metrics* of the selected clusters
-6. **`flexref`**: *Performs Semi-flexible refinement of the interface (`it1` in haddock2.4)*
-7. **`caprieval`**
-8. **`emref`**: *Performs a final refinement by energy minimisation (`itw` EM only in haddock2.4)*
-9. **`caprieval`**
-10. **`clustfcc`**: *Clustering of models based on the fraction of common contacts (FCC)*
-11. **`seletopclusts`**: *Selects the top models of all clusters*
-12. **`caprieval`**
-13. **`contactmap`**: *Contacts matrix and a chordchart of intermolecular contacts*
-
-Compared to the original workflow described in this tutorial we have added clustering and cluster selections steps after the rigid body docking.
-
-Run haddock3 with this configuration file as described above.
-
-A pre-calculated run is provided in the `runs` directory as `run1-ens`.
-Analyse your run (or the pre-calculated ones) as described previously.
-
-
-
-
- See the cluster statistics expand_more
-
-
-==============================================
-== run1-ens//12_caprieval/capri_clt.tsv
-==============================================
-Total number of acceptable or better clusters: 3 out of 11
-Total number of medium or better clusters: 1 out of 11
-Total number of high quality clusters: 1 out of 11
-
-First acceptable cluster - rank: 1 i-RMSD: 0.981 Fnat: 0.918 DockQ: 0.850
-First medium cluster - rank: 1 i-RMSD: 0.981 Fnat: 0.918 DockQ: 0.850
-Best cluster - rank: 1 i-RMSD: 0.981 Fnat: 0.918 DockQ: 0.850
-
-
-
-
-
-
-
-
- See single structure statistics expand_more
-
-
-==============================================
-== run1-ens//02_caprieval/capri_ss.tsv
-==============================================
-Total number of acceptable or better models: 27 out of 150
-Total number of medium or better models: 11 out of 150
-Total number of high quality models: 1 out of 150
-
-First acceptable model - rank: 2 i-RMSD: 1.422 Fnat: 0.586 DockQ: 0.631
-First medium model - rank: 2 i-RMSD: 1.422 Fnat: 0.586 DockQ: 0.631
-Best model - rank: 26 i-RMSD: 0.982 Fnat: 0.759 DockQ: 0.774
-==============================================
-== run1-ens//05_caprieval/capri_ss.tsv
-==============================================
-Total number of acceptable or better models: 16 out of 83
-Total number of medium or better models: 10 out of 83
-Total number of high quality models: 1 out of 83
-
-First acceptable model - rank: 2 i-RMSD: 1.422 Fnat: 0.586 DockQ: 0.631
-First medium model - rank: 2 i-RMSD: 1.422 Fnat: 0.586 DockQ: 0.631
-Best model - rank: 24 i-RMSD: 0.982 Fnat: 0.759 DockQ: 0.774
-==============================================
-== run1-ens//07_caprieval/capri_ss.tsv
-==============================================
-Total number of acceptable or better models: 17 out of 83
-Total number of medium or better models: 9 out of 83
-Total number of high quality models: 4 out of 83
-
-First acceptable model - rank: 1 i-RMSD: 0.836 Fnat: 0.931 DockQ: 0.878
-First medium model - rank: 1 i-RMSD: 0.836 Fnat: 0.931 DockQ: 0.878
-Best model - rank: 7 i-RMSD: 0.829 Fnat: 0.845 DockQ: 0.854
-==============================================
-== run1-ens//09_caprieval/capri_ss.tsv
-==============================================
-Total number of acceptable or better models: 16 out of 83
-Total number of medium or better models: 9 out of 83
-Total number of high quality models: 3 out of 83
-
-First acceptable model - rank: 1 i-RMSD: 0.908 Fnat: 0.897 DockQ: 0.855
-First medium model - rank: 1 i-RMSD: 0.908 Fnat: 0.897 DockQ: 0.855
-Best model - rank: 12 i-RMSD: 0.851 Fnat: 0.845 DockQ: 0.851
-==============================================
-== run1-ens//12_caprieval/capri_ss.tsv
-==============================================
-Total number of acceptable or better models: 10 out of 44
-Total number of medium or better models: 4 out of 44
-Total number of high quality models: 2 out of 44
-
-First acceptable model - rank: 1 i-RMSD: 0.908 Fnat: 0.897 DockQ: 0.855
-First medium model - rank: 1 i-RMSD: 0.908 Fnat: 0.897 DockQ: 0.855
-Best model - rank: 2 i-RMSD: 0.879 Fnat: 0.948 DockQ: 0.881
-
-
-
-
-
-
-We started from three different conformations of the antibody: 1) the unbound crystal structure, 2) the ABodyBuilder2 model and 3) the AlphaFold2 model.
-
-
-Using the information in the _traceback_ directory, try to figure out which of the three starting antibody models makes it into the best cluster at the end of the workflow.
-
-
-
-
-
-
-
-## BONUS 5: Antibody-antigen complex structure prediction from sequence using AlphaFold2
-
-
-With the advent of Artificial Intelligence (AI) and AlphaFold2, we can also try to predict directly the full antibody-antigen complex using AlphaFold2.
-For this we are going to use the _AlphaFold2_mmseq2_ Jupyter notebook which can be found with other interesting notebooks in Sergey Ovchinnikov
-[ColabFold GitHub repository](https://github.com/sokrypton/ColabFold){:target="_blank"}, making use of the Google Colab CLOUD resources.
-
-Start the AlphaFold2 notebook on Colab by clicking [here](https://colab.research.google.com/github/sokrypton/ColabFold/blob/main/AlphaFold2.ipynb){:target="_blank"}.
-
-**Note**: The bottom part of the notebook contains instructions on how to use it.
-
-
-
-### Setting up the antibody-antigen complex prediction with AlphaFold2
-
-To setup the prediction we need to provide the sequence of the heavy and light chains of the antibody and the sequence of the antigen.
-These are respectively
-
-* Antibody heavy chain:
-
-
-
-
-Define the _jobname_, e.g. Ab-Ag
-
-
-
-In the _Advanced settings_ block you can check the option to save the results to your Google Drive (if you have an account)
-
-
-
-In the top section of the Colab, click: _Runtime > Run All_
-
-
-(It may give a warning that this is not authored by Google because it is pulling code from GitHub - you can ignore it).
-
-This will automatically install, configure and run AlphaFold2 for you - leave this window open.
-After the prediction completed, you will be asked to download a zip archive with the results (if you configured it to use Google Drive, a result archive will be automatically saved to your Google Drive).
-
-
-_Time to grab a cup of tea or a coffee!
-And while waiting try to answer the following questions:_
-
-
- How do you interpret AlphaFold2 predictions? What are the predicted LDDT (pLDDT), PAE, iptm?
-
-
-_Tip_: Try to find information about the prediction confidence at [https://alphafold.ebi.ac.uk/faq](https://alphafold.ebi.ac.uk/faq){:target="\_blank"}. A nice summary can also be found [here](https://www.rbvi.ucsf.edu/chimerax/data/pae-apr2022/pae.html){:target="\_blank"}.
-
-
-Pre-calculated AlphFold2 predictions are provided [here](abagtest_2d03e.result.zip){:target="\_blank"}. This archive contains the five predicted models (the naming indicates the rank), figures (png) files (PAE, pLDDT, coverage) and json files containing the corresponding values (the last part of the json files report the ptm and iptm values).
-
-
-
-
-### Analysis of the generated AF2 models
-
-While the notebook is running, models will appear first under the `Run Prediction` section, colored both by chain and by pLDDT.
-
-The best model will then be displayed under the `Display 3D structure` section. This is an interactive 3D viewer that allows you to rotate the molecule and zoom in or out.
-
-**Note** that you can change the model displayed with the _rank_num_ option. After changing, it execute the cell by clicking on the run cell icon on the left of it.
-
-
- How similar are the five models generated by AF2?
-
-
-Consider the pLDDT of the various models (the higher the pLDDT the more reliable the model).
-
-
- What is the confidence of those predictions? (check again the FAQ page of the Alphafold database provided above for pLDDT values)
-
-
-While the pLDDT score is an overall measure, you can also focus on the interface score reported in the `iptm` score (value between 0 and 1).
-
-
-
-
-
- See the confidence statistics for the five generated models
-
-
-
-
-Note that if you performed a fresh run your results might well differ from those shown here.
-
-
-
-
-
- Based on the iptm scores, would you qualify those models as reliable?
-
-
-**Note** that in this case the iptm score reports on all interfaces, i.e. both the interface between the two chains of the antibody, and the antibody-antigen interface
-
-Another useful way of looking at the model accuracy is to check the Predicted Alignment Error plots (PAE) (also referred to as Domain position confidence).
-The PAE gives a distance error for every pair of residues: It gives the estimate of the position error at residue x when the predicted and true structures are aligned on residue y.
-Values range from 0 to 35 Angstroms.
-It is usually shown as a heatmap image with residue numbers running along vertical and horizontal axes and each pixel colored according to the PAE value for the corresponding pair of residues.
-If the relative position of two domains is confidently predicted then the PAE values will be low (less than 5A - dark blue) for pairs of residues with one residue in each domain.
-When analysing your complex, the diagonal block will indicate the PAE within each molecule/domain, while the off-diagonal blocks report the accuracy of the domain-domain placement.
-
-
-Our antibody-antigen complex consists of three interfaces:
-
-* The interface between the heavy and light chains of the antibody
-* The interface between the heavy chain of the antibody and the antigen
-* The interface between the light chain of the antibody and the antigen
-
-
-
-
- See the PAE plots for the five generated models
-
-
-
-
-
-
-
-
-
- Based on the PAE plots, which interfaces can be considered reliable/unreliable?
-
-
-
-
-
-### Visualization of the generated AF2 models
-
-In order to visualize the models in PyMOL save your predictions to disk or download the precalculated AlphaFold2 models from [here](abagtest_2d03e.result.zip){:target="\_blank"}.
-
-Start PyMOL and load via the File menu all five AF2 models.
-
-File menu -> Open -> select abagtest_2d03e_unrelaxed_rank_001_alphafold2_multimer_v3_model_3_seed_000.pdb
-
-Repeat this for each model (`abagtest_2d03e_unrelaxed_rank_X_alphafold2_multimer_v3_model_X_seed_000.pdb` or whatever the naming of your model is).
-
-Let us superimpose all models on the antibody (the antibody in the provided AF2 models correspond to chains A and B):
-
-
-util.cbc
-select abagtest_2d03e_unrelaxed_rank_001_alphafold2_multimer_v3_model_3_seed_000 and chain A+B
-alignto sele
-
-
-This will align all clusters on the antibody, maximizing the differences in the orientation of the antigen.
-
-
-Examine the various models. How does the orientation of the antigen differ between them?
-
-
-**Note:** You can turn on and off a model by clicking on its name in the right panel of the PyMOL window.
-
-
-
-
- See tips on how to visualize the prediction confidence in PyMOL
-
-
- When looking at the structures generated by AlphaFold2 in PyMOL, the pLDDT is encoded as the B-factor.
- To color the model according to the pLDDT type in PyMOL:
-
-
- spectrum b
-
-
- **Note** that the scale in the B-factor field is the inverse of the color coding in the PAE plots: i.e. red mean reliable (high pLDDT) and blue unreliable (low pLDDT))
-
-
-
-Since we do have NMR chemical shift perturbation data for the antigen, we can check if the perturbed residues are at the interface in the AF2 models.
-Note that there is a shift in the numbering of 2 residues between the AF2 and the HADDOCK models.
-
-
-util.cbc
-select epitope, (resi 70,71,72,73,81,82,87,88,90,92,94,95,96,113,114,115) and chain C
-color orange, epitope
-
-
-
-Does any model have the NMR-identified epitope at the interface with the antibody?
-
-
-
-
-
-
- See the AlphaFold2 models with the NMR-mapped epitope
-
-
-
-
-
-
-
-
-
-It should be clear from the visualization of the NMR-mapped epitope on the AF2 models that none satisfies the NMR data.
-To further make that clear we can compare the models to the crystal structure of the complex (4G6M).
-
-For this download and superimpose the models onto the crystal structure in PyMOL with the following commands:
-
-
-fetch 4G6M
-remove resn HOH
-color yellow, 4G6M
-select 4G6M and chain H+L
-alignto sele
-
-
-
-
-
- See the AlphaFold2 models superimposed onto the crystal structure of the complex (4G6M)
-
-
-
-
-
-
-
-
-
-
-More recently, the third version of AlphaFold (AlphaFold3) has been [published](https://www.nature.com/articles/s41586-024-07487-w){:target="\_blank"}.
-While the code is not yet released, a dedicated online tool [AlphaFoldServer](https://golgi.sandbox.google.com/){:target="\_blank"} is made available for the academic community to allow us to make upto 20 predictions per day with this new version.
-Pre-calculated AlphFold3 predictions are provided [here](af3server_abag_15052024.zip){:target="\_blank"}.
-
-
-Try to reproduce the previous steps and examine the quality of the various generated models. Do AlphaFold3 provide better predictions?
-
-
-
-
-
- See the AlphaFold3 models with mapped epitope residues in orange
-
-
-
-
-
-
-
-
-
-
-
-
- See the AlphaFold3 models onto the crystal structure of the complex (4G6M) in red
-
-
-
-
-
-
-
-
-
-
-
-
-
-## BONUS 6: Running a scoring scenario
-
-This section demonstrates the use of HADDOCK3 to score the various models obtained at the previous stages (ensemble docking and AlphaFold predictions)
-and observe if the HADDOCK scoring function is able to detect the quality of the models.
-
-To this end the following workflow is defined:
-
-1. Generate the topologies for the various models.
-2. Energy Minimise all complexes.
-3. Cluster the models using Fraction of Common Contacts:
- - set the parameter `min_population` to 1 so that all models, including singletons (models that do not cluster with any others), will be forwarded to the next steps.
- - set the parameter `plot_matrix` to true to generate a matrix of the clusters for a visual representation.
-4. Comparison of the models with the reference complex `4G6M_matched.pdb` using CAPRI criteria.
-
-For this, two ensembles must be scored and one structure will be used as a reference. You can find them in the `pdbs/` directory:
-- `07_emref_and_top5af2_ensemble.pdb`: An ensemble of models obtained from the ensemble run, combined with top5 AlphaFold2 predictions.
-- `af3server_15052024_top5ens.pdb`: An ensemble of top5 AlphaFold3 predictions.
-- `4G6M_matched.pdb`: The reference structure for quality assessments.
-
-
-{% highlight toml %}
-# ====================================================================
-# Antibody-antigen docking example with restraints from the antibody
-# paratope to the NMR-identified epitope on the antigen
-# ====================================================================
-run_dir = "scoring-haddock3-alphafold2and3-ensemble"
-
-molecules = [
- "pdbs/haddock3-ens-emref-ensemble.pdb",
- "pdbs/af2-models.pdb",
- "pdbs/af3-models.pdb",
- ]
-
-# ====================================================================
-# Parameters for each stage are defined below
-# ====================================================================
-
-[topoaa]
-
-[emscoring]
-
-[clustfcc]
-# Reduce the min_population to define a cluster to 1 so that models
-# that do not cluster with any other will define singlotons
-min_population = 1
-# Generate a matrix of the clusters
-plot_matrix = true
-
-[caprieval]
-reference_fname = "4G6M_matched.pdb"
-
-# ====================================================================
-
-{% endhighlight %}
-
-
-A scoring scenario configuration file is provided in the `workflows/` directory as `scoring-antibody-antigen.cfg, precomputed results in `runs/run-scoring`.
-
-You can again look at the `capri_ss.tsv` file in the `4_caprieval` directory. It contains the energy minimised statistics:
-
-
The bottom eight models (the worst ranking ones) are all AlphaFold3/2 models. Looking at the componenents of the score
- (some were left out in the table below for simplicity) one can see that it is mainly the van der Waals energy that causes the high scores,
- which is indicative of clashes in the models.
-
-
-
-
-Inspect more closely the reported scores above? Can you discover something peculiar with the buried surface area?
-
-
-
-How can you explain that?
-
-
-**_Hint 1_**: The HADDOCK score is calculated over all existing interfaces defined by different chainIDs.
-
-**_Hint 2_**: Visualise two of the models with very different BSA values, color-coding the chains.
-
-
-
-
-## Congratulations! 🎉
-
-You have completed this tutorial. If you have any questions or suggestions, feel free to contact us via email or asking a question through our [support center](https://ask.bioexcel.eu){:target="_blank"}.
-
-And check also our [education](/education){:target="_blank"} web page where you will find more tutorials!
-
-
-
+{% include_relative sections/congratulations.md %}
[air-help]: https://www.bonvinlab.org/software/haddock2.4/airs/ "AIRs help"
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/index.md-BioExcel2024 b/education/HADDOCK3/HADDOCK3-antibody-antigen/index.md-BioExcel2024
index 6b93af096..2556fa1e3 100644
--- a/education/HADDOCK3/HADDOCK3-antibody-antigen/index.md-BioExcel2024
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/index.md-BioExcel2024
@@ -30,7 +30,7 @@ needs to be highly variable to be able to bind to antigens of various nature (hi
In this tutorial, we will concentrate on the terminal **variable domain (Fv)** of the Fab region.
-
+
The small part of the Fab region that binds the antigen is called **paratope**. The part of the antigen
@@ -39,7 +39,7 @@ known as **complementarity-determining regions (CDRs)** or hypervariable loops w
and conformation are altered to bind to different antigens. CDRs are shown in red in the figure below:
-
+
In this tutorial we will be working with Interleukin-1β (IL-1β)
@@ -98,7 +98,7 @@ parameterisable yet rigid simulation pipeline composed of three steps:
`rigid-body docking (it0)`, `semi-flexible refinement (it1)`, and `final refinement (itw)`.
-
+
In HADDOCK3, users have the freedom to configure docking workflows into
@@ -119,7 +119,7 @@ restraints can, however, be used in HADDOCK3, which also supports the
*ab initio* docking modes of HADDOCK.
-
+
To keep HADDOCK3 modules organized, we catalogued them into several
@@ -519,7 +519,7 @@ Do the identified paratope residues form a well-defined patch on the surface?
See surface view of the paratopeexpand_more
-
+
@@ -533,7 +533,7 @@ to map the binding site of the antibody (gevokizumab) on Interleukin-1β.
The residues affected by binding are listed in Table 5 of [Blech et al. JMB 2013](https://dx.doi.org/10.1016/j.jmb.2012.09.021){:target="_blank"}:
-
+
The list of binding site (epitope) residues identified by NMR is:
@@ -569,7 +569,7 @@ The answer to that question should be yes, but we can see some residues not colo
See surface view of the epitope identified by NMRexpand_more
-
+
@@ -611,7 +611,7 @@ color green, passive See the epitope and passive residuesexpand_more
-
+
@@ -1298,7 +1298,7 @@ Simply click on the arrows of the term you want to use to sort the table (and yo
A snapshot of this table is shown below:
-
+
You can also view this report online [here](plots/report.html){:target="_blank"}
@@ -1333,7 +1333,7 @@ These are interactive plots. A menu on the top right of the first row (you might
allows you to zoom in and out in the plots and turn on and off clusters.
-
+
As a reminder, you can also view this report online [here](plots/report.html){:target="_blank"}
@@ -1346,7 +1346,7 @@ Examine the plots (remember here that higher DockQ values and lower i-RMSD value
Finally, the report also shows plots of the cluster statistics (distributions of values per cluster ordered according to their HADDOCK rank):
-
+ For this antibody-antigen case, which of the score components correlates best with the quality of the models?
@@ -1520,7 +1520,7 @@ Are the residues of the paratope and NMR epitope at the interface?
Top-ranked model of the top cluster (cluster1_model_1) superimposed onto the reference crystal structure (in yellow)
-
+
@@ -1568,7 +1568,7 @@ How many interface clusters were found for this protein?
Once you download the output archive, you can find the clustering information presented in the dendrogram:
-
+
We can see how the two *4G6M* antibody chains are recognized as a unique cluster, clearly separated from the other binding surfaces and, in particular, from those proper to IL-1RI (uniprot ID P14778).
@@ -2164,7 +2164,7 @@ Our antibody-antigen complex consists of three interfaces:
-
+
@@ -2240,7 +2240,7 @@ Does any model have the NMR-identified epitope at the interface with the antibod
-
+
@@ -2266,7 +2266,7 @@ alignto sele
-
+
@@ -2288,7 +2288,7 @@ Try to reproduce the previous steps and examine the quality of the various gener
-
+
@@ -2301,7 +2301,7 @@ Try to reproduce the previous steps and examine the quality of the various gener
-
+
@@ -2369,7 +2369,7 @@ You will land on the workflow-builder page, where you can interactively build yo
This page is subdivided into three areas described below.
-
+
On the left is presented the list of modules.
@@ -2424,7 +2424,7 @@ On the right side of the table, actions can be performed.
The current implementation allows to rename a run or to delete it.
-
+
To access the content of a run, click on its name to be directed to the haddock3 webapp results page.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-clusters.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-clusters.md
new file mode 100644
index 000000000..61c5c0880
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-clusters.md
@@ -0,0 +1,34 @@
+### Cluster statistics
+
+Let us now analyse the docking results. Use for that either your own run or a pre-calculated run provided in the `runs` directory.
+Go into the `analysis/10_caprieval_analysis` directory of the respective run directory (if needed copy the run or that directory to your local computer) and open in a web browser the `report.html` file. Be patient as this page contains interactive plots that may take some time to generate.
+
+On the top of the page, you will see a table that summarises the cluster statistics (taken from the `capri_clt.tsv` file).
+The columns (corresponding to the various clusters) are sorted by default on the cluster rank, which is based on the HADDOCK score (found on the 4th row of the table).
+As this is an interactive table, you can sort it as you wish by using the arrows present in the first column.
+Simply click on the arrows of the term you want to use to sort the table (and you can sort it in ascending or descending order).
+A snapshot of this table is shown below:
+
+
+
+
+
+You can also view this report online [here](plots/report.html){:target="_blank"}
+
+*__Note__* that in case the PDB files are still compressed (gzipped) the download links will not work. Also online visualisation is not enabled. To overcome this disk space storge solution, consider adding the global parameter `clean = true` at the begining of your configuration file.
+
+
+Inspect the final cluster statistics
+
+How many clusters have been generated?
+
+Look at the score of the first few clusters: Are they significantly different if you consider their average scores and standard deviations?
+
+Since for this tutorial we have at hand the crystal structure of the complex, we provided it as reference to the `caprieval` modules.
+This means that the iRMSD, lRMSD, Fnat and DockQ statistics report on the quality of the docked model compared to the reference crystal structure.
+
+How many clusters of acceptable or better quality have been generate according to CAPRI criteria?
+
+What is the rank of the best cluster generated?
+
+What is the rank of the first acceptable of better cluster generated?
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-contacts.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-contacts.md
new file mode 100644
index 000000000..5ca5b591e
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-contacts.md
@@ -0,0 +1,16 @@
+### Contacts analysis
+
+We have recently added a new contact analysis module to HADDOCK3 that generates for each cluster both a contact matrix of the entire system showing all contacts within a 4.5Å cutoff and a chord chart representation of intermolecular contacts.
+
+In the current workflow we run, those files can be found in the `11_contactmap` directory.
+These are again html files with interactive plots (hover with your mouse over the plots).
+
+
+Open in your favorite web browser the _cluster1_contmap_chordchart.html_ file to analyse the intermolecular contacts of the best-ranked cluster.
+
+
+This file taken from the pre-computed run can also directly be visualized [here](cluster1_contmap_chordchart.html){:target="_blank"}
+
+
+Can you identify which residue(s) make(s) the most intermolecular contacts?
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-intro.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-intro.md
new file mode 100644
index 000000000..717c2db46
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-intro.md
@@ -0,0 +1,108 @@
+## Analysis of docking results
+
+In case something went wrong with the docking (or simply if you do not want to wait for the results) you can find the following precalculated runs in the `runs` directory:
+- `run1`: docking run created using the unbound antibody.
+- `run1-af2`: docking run created using the Alphafold-multimer antibody (see 3).
+- `run1-abb`: docking run created using the Immunebuilder antibody (see 3).
+- `run1-ens`: docking run created using an ensemble of antibody models (see 4).
+- `run-scoring`: scoring run created using various models obtained at the previous stages (see 6).
+
+
+Once your run has completed - inspect the content of the resulting directory.
+You will find the various steps (modules) of the defined workflow numbered sequentially starting at 0, e.g.:
+
+{% highlight shell %}
+> ls run1/
+ 00_topoaa/
+ 01_rigidbody/
+ 02_caprieval/
+ 03_seletop/
+ 04_flexref/
+ 05_caprieval/
+ 06_emref/
+ 07_caprieval/
+ 08_clustfcc/
+ 09_seletopclusts/
+ 10_caprieval/
+ 11_contactmap/
+ analysis/
+ data/
+ log
+ toppar/
+ traceback/
+{% endhighlight %}
+
+In addition, there is a log file (text file) and four additional directories:
+
+- the `analysis` directory contains various plots to visualize the results for each caprieval step and a general report (`report.html`) that provides all statistics with various plots. You can open this file in your preferred web browser
+- the `data` directory contains the input data (PDB and restraint files) for the various modules, as well as an input workflow (in `configurations` directory)
+- the `toppar` directory contains the force field topology and parameter files (only present when running in self-contained mode)
+- the `traceback` directory contains `traceback.tsv`, which links all models to see which model originates from which throughout all steps of the workflow.
+
+You can find information about the duration of the run at the bottom of the log file.
+
+Each sampling/refinement/selection module will contain PDB files.
+For example, the `09_seletopclusts` directory contains the selected models from each cluster. The clusters in that directory are numbered based
+on their rank, i.e. `cluster_1` refers to the top-ranked cluster. Information about the origin of these files can be found in that directory in the `seletopclusts.txt` file.
+
+The simplest way to extract ranking information and the corresponding HADDOCK scores is to look at the `XX_caprieval` directories (which is why it is a good idea to have it as the final module, and possibly as intermediate steps). This directory will always contain a `capri_ss.tsv` single model statistics file, which contains the model names, rankings and statistics (score, iRMSD, Fnat, lRMSD, ilRMSD and dockq score). E.g. for `10_caprieval`:
+
+
+
+If clustering was performed prior to calling the `caprieval` module, the `capri_ss.tsv` file will also contain information about to which cluster the model belongs to and its ranking within the cluster.
+
+The relevant statistics are:
+
+* **score**: *the HADDOCK score (arbitrary units)*
+* **irmsd**: *the interface RMSD, calculated over the interfaces the molecules*
+* **fnat**: *the fraction of native contacts*
+* **lrmsd**: *the ligand RMSD, calculated on the ligand after fitting on the receptor (1st component)*
+* **ilrmsd**: *the interface-ligand RMSD, calculated over the interface of the ligand after fitting on the interface of the receptor (more relevant for small ligands for example)*
+* **dockq**: *the DockQ score, which is a combination of irmsd, lrmsd and fnat and provides a continuous scale between 1 (exactly equal to reference) and 0*
+
+Various other terms are also reported including:
+
+* **bsa**: *the buried surface area (in squared angstroms)*
+* **elec**: *the intermolecular electrostatic energy*
+* **vdw**: *the intermolecular van der Waals energy*
+* **desolv**: *the desolvation energy*
+
+
+The iRMSD, lRMSD and Fnat metrics are the ones used in the blind protein-protein prediction experiment [CAPRI](https://capri.ebi.ac.uk/){:target="_blank"} (Critical PRediction of Interactions).
+
+In CAPRI the quality of a model is defined as (for protein-protein complexes):
+
+* **acceptable model**: i-RMSD < 4Å or l-RMSD < 10Å and Fnat > 0.1 (0.23 < DOCKQ < 0.49)
+* **medium quality model**: i-RMSD < 2Å or l-RMSD < 5Å and Fnat > 0.3 (0.49 < DOCKQ < 0.8)
+* **high quality model**: i-RMSD < 1Å or l-RMSD < 1Å and Fnat > 0.5 (DOCKQ > 0.8)
+
+
+Based on these CAPRI criteria, what is the quality of the best model listed above (_cluster_1_model_1.pdb_)?
+
+
+In case where the `caprieval` module is called after a clustering step, an additional `capri_clt.tsv` file will be present in the directory.
+This file contains the cluster ranking and score statistics, averaged over the minimum number of models defined for clustering
+(4 by default), with their corresponding standard deviations. E.g.:
+
+
+
+
+In this file you find the cluster rank (which corresponds to the naming of the clusters in the previous `seletop` directory), the cluster ID (which is related to the size of the cluster, 1 being always the largest cluster), the number of models (n) in the cluster and the corresponding statistics (averages + standard deviations). The corresponding cluster PDB files will be found in the preceeding `09_seletopclusts` directory.
+
+While these simple text files can be easily checked from the command line already, they might be cumbersome to read.
+For that reason, we have developed a post-processing analysis that automatically generates html reports for all `caprieval` steps in the workflow.
+These are located in the respective `analysis/XX_caprieval` directories and can be viewed using your favorite web browser.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-scores.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-scores.md
new file mode 100644
index 000000000..f0b4b93fd
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-scores.md
@@ -0,0 +1,26 @@
+### Visualizing the scores and their components
+
+
+Next to the cluster statistic table shown above, the `report.html` file also contains a variety of plots displaying the HADDOCK score
+and its components against various CAPRI metrics (i-RMSD, l-RMSD, Fnat, Dock-Q) with a color-coded representation of the clusters.
+These are interactive plots. A menu on the top right of the first row (you might have to scroll to the rigth to see it)
+allows you to zoom in and out in the plots and turn on and off clusters.
+
+
+
+
+
+As a reminder, you can also view this report online [here](plots/report.html){:target="_blank"}
+
+
+Examine the plots (remember here that higher DockQ values and lower i-RMSD values correspond to better models)
+
+
+
+Finally, the report also shows plots of the cluster statistics (distributions of values per cluster ordered according to their HADDOCK rank):
+
+
+
+
+
+For this antibody-antigen case, which of the score components correlates best with the quality of the models?
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-single-structure.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-single-structure.md
new file mode 100644
index 000000000..da9e805d2
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/analysis-single-structure.md
@@ -0,0 +1,91 @@
+### Some single structure analysis
+
+
+Going back to command line analysis, we are providing in the `scripts` directory a simple script that extracts some model statistics for acceptable or better models from the `caprieval` steps.
+To use it, simply call the script with as argument the run directory you want to analyze, e.g.:
+
+
+./scripts/extract-capri-stats.sh ./runs/run1
+
+
+
+
+View the output of the scriptexpand_more
+
+
+==============================================
+== runs/run1/02_caprieval/capri_ss.tsv
+==============================================
+Total number of acceptable or better models: 25 out of 100
+Total number of medium or better models: 15 out of 100
+Total number of high quality models: 1 out of 100
+
+First acceptable model - rank: 1 i-RMSD: 1.196 Fnat: 0.672 DockQ: 0.741
+First medium model - rank: 1 i-RMSD: 1.196 Fnat: 0.672 DockQ: 0.741
+Best model - rank: 17 i-RMSD: 0.982 Fnat: 0.759 DockQ: 0.774
+==============================================
+== runs/run1/05_caprieval/capri_ss.tsv
+==============================================
+Total number of acceptable or better models: 14 out of 40
+Total number of medium or better models: 14 out of 40
+Total number of high quality models: 5 out of 40
+
+First acceptable model - rank: 1 i-RMSD: 0.992 Fnat: 0.897 DockQ: 0.834
+First medium model - rank: 1 i-RMSD: 0.992 Fnat: 0.897 DockQ: 0.834
+Best model - rank: 11 i-RMSD: 0.789 Fnat: 0.776 DockQ: 0.842
+==============================================
+== runs/run1/07_caprieval/capri_ss.tsv
+==============================================
+Total number of acceptable or better models: 14 out of 40
+Total number of medium or better models: 14 out of 40
+Total number of high quality models: 3 out of 40
+
+First acceptable model - rank: 1 i-RMSD: 1.037 Fnat: 0.931 DockQ: 0.841
+First medium model - rank: 1 i-RMSD: 1.037 Fnat: 0.931 DockQ: 0.841
+Best model - rank: 11 i-RMSD: 0.841 Fnat: 0.897 DockQ: 0.875
+==============================================
+== runs/run1/10_caprieval/capri_ss.tsv
+==============================================
+Total number of acceptable or better models: 4 out of 12
+Total number of medium or better models: 4 out of 12
+Total number of high quality models: 1 out of 12
+
+First acceptable model - rank: 1 i-RMSD: 1.037 Fnat: 0.931 DockQ: 0.841
+First medium model - rank: 1 i-RMSD: 1.037 Fnat: 0.931 DockQ: 0.841
+Best model - rank: 3 i-RMSD: 0.908 Fnat: 0.897 DockQ: 0.855
+
+ In terms of iRMSD values, we only observe very small differences in the best model.
+ The fraction of native contacts and the DockQ scores are however improving much more after flexible refinement but increases again slightly after final minimisation.
+ All this will of course depend on how different are the bound and unbound conformations and the amount of data used to drive the docking process.
+ In general, from our experience, the more and better data at hand, the larger the conformational changes that can be induced.
+
+ This is not the case. The scoring function is not perfect, but does a reasonable job at ranking models of acceptable or better quality on top in this case.
+
Top-ranked model of the top cluster (cluster1_model_1) superimposed onto the reference crystal structure (in yellow)
+
+
+
+
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus1-mutations.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus1-mutations.md
new file mode 100644
index 000000000..afd1b6c72
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus1-mutations.md
@@ -0,0 +1,292 @@
+## BONUS 1: Dissecting the interface energetics: what is the impact of a single mutation?
+
+Mutations at the binding interfaces can have widely varying effects on binding affinity - some may be negligible, while others can significantly strengthen or weaken the interaction. Exploring these mutations helps identify critical amino acids for redesigning structurally characterized protein-protein interfaces, which paves the way for developing protein-based therapeutics to deal with a diverse range of diseases.
+To pinpoint such amino acids positions, the residues across the protein interaction surfaces are either randomly or strategically mutated. Scanning mutations in this manner is experimentally costly. Therefore, computational methods have been developed to estimate the impact of an interfacial mutation on protein-protein interactions.
+These computational methods come in two main flavours. One involves rigorous free energy calculations, and, while highly accurate, these methods are computationally expensive. The other category includes faster, approximate approaches that predict changes in binding energy using statistical potentials, machine learning, empirical scoring functions etc. Though less precise, these faster methods are practical for large-scale screening and early-stage analysis. In this bonus exercise, we will take a look at two quick ways of estimating the effect of a single mutation in the interface.
+
+
+### PROT-ON and haddock3-scoring to inspect a single mutation
+
+PROT-ON (Structure-based detection of designer mutations in PROTein-protein interface mutatiONs) is a tool and [online server](http://proton.tools.ibg.edu.tr:8001/about){:target="_blank"} that scans all possible interfacial mutations and **predicts ΔΔG score** by using EvoEF1 (active in both on the web server and stand-alone versions) or FoldX (active only in the stand-alone version) with the aim of finding the most mutable positions. The original publication describing PROT-ON can be found [here](https://www.frontiersin.org/journals/molecular-biosciences/articles/10.3389/fmolb.2023.1063971/full){:target="_blank"}.
+
+Here we will use PROT-ON to analyse the interface of our antibody-antigen complex. For that, we will use the provided matched reference structure (`4G6M-matched.pdb`) in which both chains of the antibody have the same chainID (A), which allows us to analyse all interface residues of the antibody at once.
+
+__Note:__ Pre-calculated PROT-ON results for this system can be accessed [here](http://proton.tools.ibg.edu.tr:8001/result/4G6M_matched_chain_A_EvoEF1){:target="_blank"}.
+
+
+Connect to the PROT-ON server page (link above) and fill in the following fields:
+
+
+
+Specify your run name* --> 4G6M_matched
+
+
+
+Choose / Upload your protein complex* --> Select the provided _4G6M-matched.pdb_ file
+
+
+
+Which dimer chains should be analyzed* --> Select chain A for the 1st molecule and B for the 2nd
+
+
+Pick the monomer for mutational scanning* --> Select the first molecule - the antibody (toggle the switch ON under the chain A)
+
+
+
+Click on the Submit button
+
+
+Your run should complete in 5-10 minutes. Once finished, you will be presented with a result page summarising the most depleting (ones that decrease the binding affinity) and most enriching (ones that increase the binding affinity) mutations.
+
+
+Which possible mutation would you propose to improve the binding affinity of the antibody?
+
+
+
+
+ See answerexpand_more
+
+The most enriching mutation is S150W with a -3.69 ΔΔG score.
+
+
+
+
+Inspect the proposed amino acid in PyMol. Can you rationalise why it might increase the affinity?
+
+
+With HADDOCK3, it is possible to take a step further. To perform the mutation, simply rename the desired residue and score such model - HADDOCK will take care of the topology regardless of the side chain differences and energy minimisation of the model. To do so, first either edit _4G6M-matched.pdb_ in your favourite text editor and save this new file as _4G6M_matched_S150W.pdb_, or use the command line:
+
+sed 's/SER\ A\ 150/TRP\ A\ 150/g' 4G6M_matched.pdb > 4G6M_matched_S150W.pdb
+
+
+Next, score the mutant using the command-line tool `haddock3-score`.
+This tool performs a short workflow composed of the `topoaa` and `emscoring` modules. Use flag `--outputpdb` to save energy-minimized model:
+
+haddock3-score 4G6M_matched_S150W.pdb \-\-outputpdb
+
+
+
+Use _haddock3-score_ to calculate the score of the 4G6M-matched.pdb. Do you see a difference between wild-type and mutant scores?
+Might such single-residue mutation affect the binding affinity?
+
+
+
+Inspect the energy-minimized mutant model (4G6M_matched_S150W_hs.pdb) visually.
+Can you rationalise why such a mutation might increase the affinity?
+
+
+
+
+
+ Zoom in on the mutated residueexpand_more
+
+
+
+
+ TRP150 is stacking with TYR24
+
+
+
+
+
+
+
+### Alanine Scanning module
+
+Another way of exploring interface energetics is by using the `alascan` module of HADDOCK3. `alascan` stands for "Alanine Scanning module".
+
+This module is capable of mutating interface residues to Alanine and calculating the **Δ HADDOCK score** between the wild-type and mutant, thus providing a measure of the impact of each individual mutation. It is possible to scan all interface residues one by one or limit this scanning to a selected by user set of residues. By default, the mutation to Alanine is performed, as its side chain is just a methyl group, so side chain perturbations are minimal, as well as possible secondary structure changes. It is possible to perform the mutation to any other amino acid type - at your own risk, as such mutations may introduce structural uncertainty.
+
+**Important**: 1/ `alascan` calculates the difference between wild-type score vs mutant score, i.e. positive `Δscore` indicative of the enriched (stronger) binding and negative `Δscore` is indicative of the depleted (weaker) binding; 2/ Inside `alascan`, a short energy minimization of an input structure is performed, i.e. there's no need to include an additional refinement module prior to `alascan`.
+
+Here is an example of the workflow to scan interface energetics:
+{% highlight toml %}
+# ====================================================================
+# Scanning interface residues with haddock3
+# ====================================================================
+
+# directory in which the scoring will be done
+run_dir = "run-energetics-alascan"
+
+# compute mode
+mode = "local"
+ncores = 50
+
+# Post-processing to generate statistics and plots
+postprocess = true
+clean = true
+
+molecules = [
+ "pdbs/4G6M_matched.pdb",
+ ]
+
+# ====================================================================
+# Parameters for each stage are defined below
+# ====================================================================
+[topoaa]
+
+[alascan]
+# mutate each interface residue to Alanine
+scan_residue = 'ALA'
+# generate plot of delta score and its components per each mutation
+plot = true
+
+# ====================================================================
+{% endhighlight %}
+
+A scoring scenario configuration file is provided in the `workflows/` directory as `interaction-energetics.cfg`, and precomputed results are in `runs/run-energetics-alascan`.
+The output folder contains, among others, a directory titled `1_alascan` with a file `scan_4G6M_matched_haddock.tsv` that lists each mutation, corresponding score and individual terms:
+
+##########################################################
+# `alascan` results for 4G6M_matched_haddock.pdb
+#
+# native score = -145.5891
+#
+# z_score is calculated with respect to the other residues
+##########################################################
+chain res ori_resname end_resname score vdw elec desolv bsa delta_score delta_vdw delta_elec delta_desolv delta_bsa z_score
+A 212 LYS ALA -136.33 -66.16 -367.66 3.37 1660.53 -9.26 2.52 -75.12 3.24 37.57 -0.48
+A 103 ASP ALA -129.64 -59.93 -365.23 3.34 1677.97 -15.95 -3.71 -77.56 3.27 20.13 -1.41
+A 54 TRP ALA -138.18 -58.34 -435.53 7.27 1690.80 -7.41 -5.30 -7.26 -0.66 7.30 -0.22
+A 32 SER ALA -143.66 -60.55 -447.37 6.36 1691.72 -1.93 -3.09 4.59 0.24 6.38 0.55
+A 58 ASP ALA -121.65 -63.49 -306.77 3.20 1639.20 -23.94 -0.15 -136.01 3.41 58.90 -2.52
+A 33 GLY ALA -148.50 -61.56 -473.22 7.71 1693.18 2.91 -2.08 30.43 -1.10 4.92 1.22
+...
+
+ ASP58 makes h-bonds with two neighbouring residues
+
+
+
+We can see one hydrogen bond between ASP58 and LYS98, and two hydrogen bonds ASP58 and LYS94.
+Mutating ASP58 to ALA should result in the disappearance of those h-bonds, and the overall depletion of the binding.
+This is reflected by the high negative value (-136.01) of `delta_elec` in either of .tsv files.
+
+Let us test several mutations to confirm our hypothesis.
+Here is an example of the workflow to perform such mutations and save generated models:
+
+{% highlight ini %}
+# ====================================================================
+# Mutating selected interface residue with haddock3
+# ====================================================================
+
+# directory in which the scoring will be done
+run_dir = "run-energetics-mutations"
+
+# compute mode
+mode = "local"
+ncores = 50
+
+# Post-processing to generate statistics and plots
+postprocess = true
+clean = true
+
+molecules = ["pdbs/4G6M_matched.pdb"]
+
+# ====================================================================
+# Parameters for each stage are defined below
+# ====================================================================
+[topoaa]
+
+[alascan]
+# mutate residue 58 of chain A to Arginine
+scan_residue = "ARG"
+resdic_A = [58]
+# save energy-minimised mutant model
+output_mutants= true
+
+[alascan]
+scan_residue = "GLY"
+resdic_A = [58]
+output_mutants= true
+
+[alascan]
+scan_residue = "TRP"
+resdic_A = [58]
+output_mutants= true
+
+{% endhighlight %}
+
+Configuration file for this scenario can be found in `workflows/single-residue-mutations.cfg`, precomputed results are in `run-residue-mutations`. The output folder contains, among others, an energy-minimised mutant model `1_alascan/4G6M_matched_haddock-A_D58R.pdb.gz`, and tables `.tsv` with energetics.
+
+
+Take a look at the scores of the mutants. Which mutation depletes binding the most?
+
+
+
+Inspect the mutant vs wild-type complex. Can you see the difference at the interface level?
+
+
+
+
+ See the overlay of the mutant onto the wild-type structure expand_more
+
+
+
+
+ wild-type residue ASP58 is displayed in pink, and mutant residue AGR58 is displayed in orange
+
+
+
+
+
+
+
+
+Compare values obtained with [alascan] to the corresponding values obtained with PROT-ON. Are they different? If yes, can you think of a reason why?
+
+
+
+
+ See answerexpand_more
+
+The values themselves are expected to differ, because [alascan] calculates ΔHADDOCK score, while PROT-ON predicts ΔΔG.
+Moreover, both tools are making predictions using different methods, so it is normal to have different results.
+However, if both tools consistently identify the same mutations as binding enriching or depleting - this may signal that selected residues indeed play a key role in binding affinity.
+
+
+
+Now let us consider how sensitive this kind of analysis is to the quality of the docking model.
+Instead of using the crystal structure, repeat this analysis using the best model of the top-ranked cluster or the best model with the lowest LRMSD value.
+
+
+Consider the most binding-enrishing/-depleting mutations predicted based on your favourite docking model.
+How different are those compared to the mutations, predicted based on the crystal structure?
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus2-arctic3d.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus2-arctic3d.md
new file mode 100644
index 000000000..52baa2837
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus2-arctic3d.md
@@ -0,0 +1,43 @@
+## BONUS 2: Does the antibody bind to a known interface of interleukin? ARCTIC-3D analysis
+
+Gevokizumab is a highly specific antibody that targets an allosteric site of Interleukin-1β (IL-1β) in PDB file *4G6M*, thus reducing its binding affinity for its substrate, interleukin-1 receptor type I (IL-1RI). Canakinumab, another antibody binding to IL-1β, has a different mode of action, as it competes directly with the binding site of IL-1RI (in PDB file *4G6J*). For more details please check [this article](https://www.sciencedirect.com/science/article/abs/pii/S0022283612007863?via%3Dihub){:target="_blank"}.
+
+We will now use our new software, [ARCTIC-3D](https://www.nature.com/articles/s42003-023-05718-w){:target="_blank"}, to visualize the binding interfaces formed by IL-1β. First, the program retrieves all the existing binding surfaces formed by IL-1β from the [PDBe website](https://www.ebi.ac.uk/pdbe/){:target="_blank"}. Then, these binding surfaces are compared and clustered together if they span a similar region of the selected protein (IL-1β in our case).
+
+We will run an ARCTIC-3D job targeting the uniprot ID of human Interleukin-1 beta, namely [P01584](https://www.uniprot.org/uniprotkb/P01584/entry){:target="_blank"}.
+
+For this first open the ARCTIC-3D web-server page [here](https://wenmr.science.uu.nl/arctic3d/){:target="_blank"}.
+
+
+Insert the selected UniProt ID in the **UniprotID** field.
+
+
+
+Leave the other parameters as they are and click on **Submit**.
+
+
+Wait a few seconds for the job to complete or access a precalculated run [here](https://wenmr.science.uu.nl/arctic3d/example-P01584){:target="_blank"}.
+
+
+How many interface clusters were found for this protein?
+
+
+Once you download the output archive, you can find the clustering information presented in the dendrogram:
+
+
+
+
+
+We can see how the two *4G6M* antibody chains are recognized as a unique cluster, clearly separated from the other binding surfaces and, in particular, from those proper to IL-1RI (uniprot ID P14778).
+
+
+Re-run ARCTIC-3D with a clustering threshold equal to 0.95
+
+
+This means that the clustering will be looser, therefore lumping more dissimilar surfaces into the same object.
+
+You can inspect a precalculated run [here](https://wenmr.science.uu.nl/arctic3d/example-P01584-095){:target="_blank"}.
+
+
+How do the results change? Are gevokizumab or canakinumab PDB files being clustered with any IL-1RI-related interface?
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus3-ai-models.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus3-ai-models.md
new file mode 100644
index 000000000..54c1f3f54
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus3-ai-models.md
@@ -0,0 +1,202 @@
+## BONUS 3: How good are AI-based models of antibody for docking?
+
+The release of [AlphaFold2 in late 2020](https://www.nature.com/articles/s41586-021-03819-2) has brought structure prediction methods to a new frontier, providing accurate models for the majority of known proteins. This revolution did not spare antibodies, with [Alphafold2-multimer](https://github.com/sokrypton/ColabFold){:target="_blank"} and other prediction methods (most notably [ABodyBuilder2](https://opig.stats.ox.ac.uk/webapps/sabdab-sabpred/sabpred/abodybuilder2/){:target="_blank"}, from the ImmuneBuilder suite) performing nicely on the variable regions.
+
+For a short introduction to AI and AlphaFold2 refer to this other tutorial [introduction](/education/molmod_online/alphafold/#introduction){:target="_blank"}.
+
+For antibody modelings, CDR loops are clearly the most challenging region to be predicted given their high sequence variability and flexibility.
+Multiple Sequence Alignment (MSA)-derived information is also less useful in this context.
+
+Here we will see whether the antibody models given by Alphafold2-multimer and ABodyBuilder2 can be used for generating reliable models of the antibody-antigen complex by docking, instead of the unbound form used in this tutorial, which, in many cases, will not be available.
+
+
+### Analysing the AI models
+
+We already ran the prediction with these two tools, and you can find the resulting models in the `pdbs` directory as:
+
+- `4g6k_Abodybuilder2.pdb`
+- `4g6k_AF2_multimer.pdb`
+
+
+As was demonstrated in the tutorial, those files must be preprocessed for their use in HADDOCK. Docking-ready files are also provided in the `pdbs` directory:
+
+
+- `4G6K_abb_clean.pdb`
+- `4G6K_af2_clean.pdb`
+
+
+Load the experimental unbound structure (`4G6K_clean.pdb`) and the two AI models in PyMOL to see whether they resemble the experimental unbound structure.
+
+
+File menu -> Open -> select 4G6K_clean.pdb
+
+
+File menu -> Open -> select 4G6K_abb_clean.pdb
+
+
+File menu -> Open -> select 4G6K_af2_clean.pdb
+
+
+Align the models to the experimental unbound structure
+
+
+alignto 4G6K_clean
+
+
+
+Which model is the closest to the unbound conformation?
+
+
+
+
+ See the RMSD valuesexpand_more
+
+
+ 4G6K_abb_clean RMSD = 0.428 Å
+ 4G6K_af2_clean RMSD = 0.765 Å
+
+ 4G6K_abb_clean RMSD = 0.330 Å
+ 4G6K_af2_clean RMSD = 0.675 Å
+ 4G6K_clean RMSD = 0.393 Å
+
+
+
+
+
+
+
+
+### Docking performance using AI-based antibody models
+
+We can repeat the docking as described above in our tutorial, but using this time either the ABodyBuilder2 or AlphaFold2 models as input.
+For this, modify your haddock3 configuration file, changing the input PDB file of the first molecule (the antibody) using the respective HADDOCK-ready models provided in the `pdbs` directory.
+You will also need to change the restraint filename used to keep the two parts of the antibody together (those files are present in the `restraints` directory.
+
+Further, run haddock3 as described above.
+
+Pre-calculated runs are provided in the `runs` directory. Analyse your run (or the pre-calculated ones) as described previously.
+
+
+Which starting structure of the antibody gives the best results in terms of cluster quality and ranking?
+
+
+
+
+ See the cluster statistics expand_more
+
+
+==============================================
+== run1/10_caprieval/capri_clt.tsv
+==============================================
+Total number of acceptable or better clusters: 1 out of 3
+Total number of medium or better clusters: 1 out of 3
+Total number of high quality clusters: 0 out of 3
+
+First acceptable cluster - rank: 1 i-RMSD: 1.049 Fnat: 0.879 DockQ: 0.815
+First medium cluster - rank: 1 i-RMSD: 1.049 Fnat: 0.879 DockQ: 0.815
+Best cluster - rank: 1 i-RMSD: 1.049 Fnat: 0.879 DockQ: 0.815
+
+==============================================
+== run1-abb/10_caprieval/capri_clt.tsv
+==============================================
+Total number of acceptable or better clusters: 1 out of 5
+Total number of medium or better clusters: 1 out of 5
+Total number of high quality clusters: 0 out of 5
+
+First acceptable cluster - rank: 1 i-RMSD: 1.134 Fnat: 0.841 DockQ: 0.796
+First medium cluster - rank: 1 i-RMSD: 1.134 Fnat: 0.841 DockQ: 0.796
+Best cluster - rank: 1 i-RMSD: 1.134 Fnat: 0.841 DockQ: 0.796
+
+==============================================
+== run1-af2/10_caprieval/capri_clt.tsv
+==============================================
+Total number of acceptable or better clusters: 2 out of 3
+Total number of medium or better clusters: 0 out of 3
+Total number of high quality clusters: 0 out of 3
+
+First acceptable cluster - rank: 1 i-RMSD: 3.974 Fnat: 0.289 DockQ: 0.239
+First medium cluster - rank: i-RMSD: Fnat: DockQ:
+Best cluster - rank: 3 i-RMSD: 3.305 Fnat: 0.302 DockQ: 0.290
+
+==============================================
+== run1/07_caprieval/capri_ss.tsv
+==============================================
+...
+First acceptable model - rank: 1 i-RMSD: 1.037 Fnat: 0.931 DockQ: 0.841
+First medium model - rank: 1 i-RMSD: 1.037 Fnat: 0.931 DockQ: 0.841
+Best model - rank: 11 i-RMSD: 0.841 Fnat: 0.897 DockQ: 0.875
+
+==============================================
+== run1-abb/07_caprieval/capri_ss.tsv
+==============================================
+...
+First acceptable model - rank: 1 i-RMSD: 0.990 Fnat: 0.931 DockQ: 0.860
+First medium model - rank: 1 i-RMSD: 0.990 Fnat: 0.931 DockQ: 0.860
+Best model - rank: 1 i-RMSD: 0.990 Fnat: 0.931 DockQ: 0.860
+
+==============================================
+== run1-af2/07_caprieval/capri_ss.tsv
+==============================================
+...
+First acceptable model - rank: 1 i-RMSD: 3.246 Fnat: 0.362 DockQ: 0.389
+First medium model - rank: i-RMSD: Fnat: DockQ:
+Best model - rank: 21 i-RMSD: 2.474 Fnat: 0.362 DockQ: 0.468
+
+
+
+
+
+
+
+
+### Conclusions - AI-based docking
+
+All three antibody structures used in input give good to reasonable results.
+The unbound and the ABodyBuilder2 antibodies provided better results, with the best cluster showing models within 1 angstrom of interface-RMSD with respect to the unbound structure.
+Using the Alphafold2 structure in this case is not the best option, as the input antibody is not perfectly modelled in its H3 loop.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus4-ensemble.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus4-ensemble.md
new file mode 100644
index 000000000..848345a65
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus4-ensemble.md
@@ -0,0 +1,211 @@
+## BONUS 4: Ensemble docking using a combination of exprimental and AI-predicted antibody structures
+
+
+Instead of running haddock3 using a specific input structure of the antibody, we can also use an ensemble of all available models.
+Such an ensemble can be created from the individual models using `pdb_mkensemble` from PDB-tools:
+
+
+pdb_mkensemble 4G6K_clean.pdb 4G6K_abb_clean.pdb 4G6K_af2_clean.pdb > 4G6K-ensemble.pdb
+
+
+This ensemble file is provided in the `pdbs` directory.
+
+Now we can make use of the flexibility of haddock3 in defining workflows to add a clustering step after the rigid body docking step in order to make sure that models originating from all models will ideally be selected for the refinement steps (provided they do cluster). This modified workflow looks like:
+
+
+{% highlight toml %}
+# ====================================================================
+# Antibody-antigen docking example with restraints from the antibody
+# paratope to the NMR-identified epitope on the antigen
+# ====================================================================
+
+# directory in which the scoring will be done
+run_dir = "run-ens-CDR-NMR-CSP"
+
+# compute mode
+mode = "local"
+ncores = 50
+
+# Post-processing to generate statistics and plots
+postprocess = true
+clean = true
+
+molecules = [
+ "pdbs/4G6K-ensemble.pdb",
+ "pdbs/4I1B_clean.pdb"
+ ]
+
+# ====================================================================
+# Parameters for each stage are defined below, prefer full paths
+# ====================================================================
+[topoaa]
+
+[rigidbody]
+# CDR to NMR epitope ambig restraints
+ambig_fname = "restraints/ambig-paratope-NMR-epitope.tbl"
+# Restraints to keep the antibody chains together
+unambig_fname = "restraints/antibody-unambig.tbl"
+# Reduced sampling (150 instead of the default of 1000)
+# Increased to 150 so that each conformation is sampled 50 times
+sampling = 150
+
+[caprieval]
+reference_fname = "pdbs/4G6M_matched.pdb"
+
+[clustfcc]
+plot_matrix = true
+
+[seletopclusts]
+top_models = 10
+
+[caprieval]
+reference_fname = "pdbs/4G6M_matched.pdb"
+
+[flexref]
+tolerance = 5
+# CDR to NMR epitope ambig restraints
+ambig_fname = "restraints/ambig-paratope-NMR-epitope.tbl"
+# Restraints to keep the antibody chains together
+unambig_fname = "restraints/antibody-unambig.tbl"
+
+[caprieval]
+reference_fname = "pdbs/4G6M_matched.pdb"
+
+[emref]
+tolerance = 5
+# CDR to NMR epitope ambig restraints
+ambig_fname = "restraints/ambig-paratope-NMR-epitope.tbl"
+# Restraints to keep the antibody chains together
+unambig_fname = "restraints/antibody-unambig.tbl"
+
+[caprieval]
+reference_fname = "pdbs/4G6M_matched.pdb"
+
+[clustfcc]
+plot_matrix = true
+
+[seletopclusts]
+top_models = 4
+
+[caprieval]
+reference_fname = "pdbs/4G6M_matched.pdb"
+
+[contactmap]
+
+# ====================================================================
+
+{% endhighlight %}
+
+
+Our workflow consists of the following 14 modules:
+
+0. **`topoaa`**: *Generates the topologies for the CNS engine and builds missing atoms*
+1. **`rigidbody`**: *Performs Rigid body energy minimisation* - with increased sampling (150 models - 50 per input model)
+2. **`caprieval`**: *Calculates CAPRI metrics*
+3. **`clustfcc`**: *Clustering of models based on the fraction of common contacts (FCC)*
+4. **`seletopclusts`**: *Selects the top models of all clusters* - In this case, we select max 10 models per cluster.
+5. **`caprieval`**: *Calculates CAPRI metrics* of the selected clusters
+6. **`flexref`**: *Performs Semi-flexible refinement of the interface (`it1` in haddock2.4)*
+7. **`caprieval`**
+8. **`emref`**: *Performs a final refinement by energy minimisation (`itw` EM only in haddock2.4)*
+9. **`caprieval`**
+10. **`clustfcc`**: *Clustering of models based on the fraction of common contacts (FCC)*
+11. **`seletopclusts`**: *Selects the top models of all clusters*
+12. **`caprieval`**
+13. **`contactmap`**: *Contacts matrix and a chordchart of intermolecular contacts*
+
+Compared to the original workflow described in this tutorial we have added clustering and cluster selections steps after the rigid body docking.
+
+Run haddock3 with this configuration file as described above.
+
+A pre-calculated run is provided in the `runs` directory as `run1-ens`.
+Analyse your run (or the pre-calculated ones) as described previously.
+
+
+
+
+ See the cluster statistics expand_more
+
+
+==============================================
+== run1-ens//12_caprieval/capri_clt.tsv
+==============================================
+Total number of acceptable or better clusters: 3 out of 11
+Total number of medium or better clusters: 1 out of 11
+Total number of high quality clusters: 1 out of 11
+
+First acceptable cluster - rank: 1 i-RMSD: 0.981 Fnat: 0.918 DockQ: 0.850
+First medium cluster - rank: 1 i-RMSD: 0.981 Fnat: 0.918 DockQ: 0.850
+Best cluster - rank: 1 i-RMSD: 0.981 Fnat: 0.918 DockQ: 0.850
+
+
+
+
+
+
+
+
+ See single structure statistics expand_more
+
+
+==============================================
+== run1-ens//02_caprieval/capri_ss.tsv
+==============================================
+Total number of acceptable or better models: 27 out of 150
+Total number of medium or better models: 11 out of 150
+Total number of high quality models: 1 out of 150
+
+First acceptable model - rank: 2 i-RMSD: 1.422 Fnat: 0.586 DockQ: 0.631
+First medium model - rank: 2 i-RMSD: 1.422 Fnat: 0.586 DockQ: 0.631
+Best model - rank: 26 i-RMSD: 0.982 Fnat: 0.759 DockQ: 0.774
+==============================================
+== run1-ens//05_caprieval/capri_ss.tsv
+==============================================
+Total number of acceptable or better models: 16 out of 83
+Total number of medium or better models: 10 out of 83
+Total number of high quality models: 1 out of 83
+
+First acceptable model - rank: 2 i-RMSD: 1.422 Fnat: 0.586 DockQ: 0.631
+First medium model - rank: 2 i-RMSD: 1.422 Fnat: 0.586 DockQ: 0.631
+Best model - rank: 24 i-RMSD: 0.982 Fnat: 0.759 DockQ: 0.774
+==============================================
+== run1-ens//07_caprieval/capri_ss.tsv
+==============================================
+Total number of acceptable or better models: 17 out of 83
+Total number of medium or better models: 9 out of 83
+Total number of high quality models: 4 out of 83
+
+First acceptable model - rank: 1 i-RMSD: 0.836 Fnat: 0.931 DockQ: 0.878
+First medium model - rank: 1 i-RMSD: 0.836 Fnat: 0.931 DockQ: 0.878
+Best model - rank: 7 i-RMSD: 0.829 Fnat: 0.845 DockQ: 0.854
+==============================================
+== run1-ens//09_caprieval/capri_ss.tsv
+==============================================
+Total number of acceptable or better models: 16 out of 83
+Total number of medium or better models: 9 out of 83
+Total number of high quality models: 3 out of 83
+
+First acceptable model - rank: 1 i-RMSD: 0.908 Fnat: 0.897 DockQ: 0.855
+First medium model - rank: 1 i-RMSD: 0.908 Fnat: 0.897 DockQ: 0.855
+Best model - rank: 12 i-RMSD: 0.851 Fnat: 0.845 DockQ: 0.851
+==============================================
+== run1-ens//12_caprieval/capri_ss.tsv
+==============================================
+Total number of acceptable or better models: 10 out of 44
+Total number of medium or better models: 4 out of 44
+Total number of high quality models: 2 out of 44
+
+First acceptable model - rank: 1 i-RMSD: 0.908 Fnat: 0.897 DockQ: 0.855
+First medium model - rank: 1 i-RMSD: 0.908 Fnat: 0.897 DockQ: 0.855
+Best model - rank: 2 i-RMSD: 0.879 Fnat: 0.948 DockQ: 0.881
+
+
+
+
+
+
+We started from three different conformations of the antibody: 1) the unbound crystal structure, 2) the ABodyBuilder2 model and 3) the AlphaFold2 model.
+
+
+Using the information in the _traceback_ directory, try to figure out which of the three starting antibody models makes it into the best cluster at the end of the workflow.
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus5-alphafold2.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus5-alphafold2.md
new file mode 100644
index 000000000..a8e468b21
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus5-alphafold2.md
@@ -0,0 +1,293 @@
+## BONUS 5: Antibody-antigen complex structure prediction from sequence using AlphaFold2
+
+
+With the advent of Artificial Intelligence (AI) and AlphaFold2, we can also try to predict directly the full antibody-antigen complex using AlphaFold2.
+For this we are going to use the _AlphaFold2_mmseq2_ Jupyter notebook which can be found with other interesting notebooks in Sergey Ovchinnikov
+[ColabFold GitHub repository](https://github.com/sokrypton/ColabFold){:target="_blank"}, making use of the Google Colab CLOUD resources.
+
+Start the AlphaFold2 notebook on Colab by clicking [here](https://colab.research.google.com/github/sokrypton/ColabFold/blob/main/AlphaFold2.ipynb){:target="_blank"}.
+
+**Note**: The bottom part of the notebook contains instructions on how to use it.
+
+
+
+### Setting up the antibody-antigen complex prediction with AlphaFold2
+
+To setup the prediction we need to provide the sequence of the heavy and light chains of the antibody and the sequence of the antigen.
+These are respectively
+
+* Antibody heavy chain:
+
+
+
+
+Define the _jobname_, e.g. Ab-Ag
+
+
+
+In the _Advanced settings_ block you can check the option to save the results to your Google Drive (if you have an account)
+
+
+
+In the top section of the Colab, click: _Runtime > Run All_
+
+
+(It may give a warning that this is not authored by Google because it is pulling code from GitHub - you can ignore it).
+
+This will automatically install, configure and run AlphaFold2 for you - leave this window open.
+After the prediction completed, you will be asked to download a zip archive with the results (if you configured it to use Google Drive, a result archive will be automatically saved to your Google Drive).
+
+
+_Time to grab a cup of tea or a coffee!
+And while waiting try to answer the following questions:_
+
+
+ How do you interpret AlphaFold2 predictions? What are the predicted LDDT (pLDDT), PAE, iptm?
+
+
+_Tip_: Try to find information about the prediction confidence at [https://alphafold.ebi.ac.uk/faq](https://alphafold.ebi.ac.uk/faq){:target="\_blank"}. A nice summary can also be found [here](https://www.rbvi.ucsf.edu/chimerax/data/pae-apr2022/pae.html){:target="\_blank"}.
+
+
+Pre-calculated AlphFold2 predictions are provided [here](abagtest_2d03e.result.zip){:target="\_blank"}. This archive contains the five predicted models (the naming indicates the rank), figures (png) files (PAE, pLDDT, coverage) and json files containing the corresponding values (the last part of the json files report the ptm and iptm values).
+
+
+
+
+### Analysis of the generated AF2 models
+
+While the notebook is running, models will appear first under the `Run Prediction` section, colored both by chain and by pLDDT.
+
+The best model will then be displayed under the `Display 3D structure` section. This is an interactive 3D viewer that allows you to rotate the molecule and zoom in or out.
+
+**Note** that you can change the model displayed with the _rank_num_ option. After changing, it execute the cell by clicking on the run cell icon on the left of it.
+
+
+ How similar are the five models generated by AF2?
+
+
+Consider the pLDDT of the various models (the higher the pLDDT the more reliable the model).
+
+
+ What is the confidence of those predictions? (check again the FAQ page of the Alphafold database provided above for pLDDT values)
+
+
+While the pLDDT score is an overall measure, you can also focus on the interface score reported in the `iptm` score (value between 0 and 1).
+
+
+
+
+
+ See the confidence statistics for the five generated models
+
+
+
+
+Note that if you performed a fresh run your results might well differ from those shown here.
+
+
+
+
+
+ Based on the iptm scores, would you qualify those models as reliable?
+
+
+**Note** that in this case the iptm score reports on all interfaces, i.e. both the interface between the two chains of the antibody, and the antibody-antigen interface
+
+Another useful way of looking at the model accuracy is to check the Predicted Alignment Error plots (PAE) (also referred to as Domain position confidence).
+The PAE gives a distance error for every pair of residues: It gives the estimate of the position error at residue x when the predicted and true structures are aligned on residue y.
+Values range from 0 to 35 Angstroms.
+It is usually shown as a heatmap image with residue numbers running along vertical and horizontal axes and each pixel colored according to the PAE value for the corresponding pair of residues.
+If the relative position of two domains is confidently predicted then the PAE values will be low (less than 5A - dark blue) for pairs of residues with one residue in each domain.
+When analysing your complex, the diagonal block will indicate the PAE within each molecule/domain, while the off-diagonal blocks report the accuracy of the domain-domain placement.
+
+
+Our antibody-antigen complex consists of three interfaces:
+
+* The interface between the heavy and light chains of the antibody
+* The interface between the heavy chain of the antibody and the antigen
+* The interface between the light chain of the antibody and the antigen
+
+
+
+
+ See the PAE plots for the five generated models
+
+
+
+
+
+
+
+
+
+ Based on the PAE plots, which interfaces can be considered reliable/unreliable?
+
+
+
+
+
+### Visualization of the generated AF2 models
+
+In order to visualize the models in PyMOL save your predictions to disk or download the precalculated AlphaFold2 models from [here](abagtest_2d03e.result.zip){:target="\_blank"}.
+
+Start PyMOL and load via the File menu all five AF2 models.
+
+File menu -> Open -> select abagtest_2d03e_unrelaxed_rank_001_alphafold2_multimer_v3_model_3_seed_000.pdb
+
+Repeat this for each model (`abagtest_2d03e_unrelaxed_rank_X_alphafold2_multimer_v3_model_X_seed_000.pdb` or whatever the naming of your model is).
+
+Let us superimpose all models on the antibody (the antibody in the provided AF2 models correspond to chains A and B):
+
+
+util.cbc
+select abagtest_2d03e_unrelaxed_rank_001_alphafold2_multimer_v3_model_3_seed_000 and chain A+B
+alignto sele
+
+
+This will align all clusters on the antibody, maximizing the differences in the orientation of the antigen.
+
+
+Examine the various models. How does the orientation of the antigen differ between them?
+
+
+**Note:** You can turn on and off a model by clicking on its name in the right panel of the PyMOL window.
+
+
+
+
+ See tips on how to visualize the prediction confidence in PyMOL
+
+
+ When looking at the structures generated by AlphaFold2 in PyMOL, the pLDDT is encoded as the B-factor.
+ To color the model according to the pLDDT type in PyMOL:
+
+
+ spectrum b
+
+
+ **Note** that the scale in the B-factor field is the inverse of the color coding in the PAE plots: i.e. red mean reliable (high pLDDT) and blue unreliable (low pLDDT))
+
+
+
+Since we do have NMR chemical shift perturbation data for the antigen, we can check if the perturbed residues are at the interface in the AF2 models.
+Note that there is a shift in the numbering of 2 residues between the AF2 and the HADDOCK models.
+
+
+util.cbc
+select epitope, (resi 70,71,72,73,81,82,87,88,90,92,94,95,96,113,114,115) and chain C
+color orange, epitope
+
+
+
+Does any model have the NMR-identified epitope at the interface with the antibody?
+
+
+
+
+
+
+ See the AlphaFold2 models with the NMR-mapped epitope
+
+
+
+
+
+
+
+
+
+It should be clear from the visualization of the NMR-mapped epitope on the AF2 models that none satisfies the NMR data.
+To further make that clear we can compare the models to the crystal structure of the complex (4G6M).
+
+For this download and superimpose the models onto the crystal structure in PyMOL with the following commands:
+
+
+fetch 4G6M
+remove resn HOH
+color yellow, 4G6M
+select 4G6M and chain H+L
+alignto sele
+
+
+
+
+
+ See the AlphaFold2 models superimposed onto the crystal structure of the complex (4G6M)
+
+
+
+
+
+
+
+
+
+
+More recently, the third version of AlphaFold (AlphaFold3) has been [published](https://www.nature.com/articles/s41586-024-07487-w){:target="\_blank"}.
+While the code is not yet released, a dedicated online tool [AlphaFoldServer](https://golgi.sandbox.google.com/){:target="\_blank"} is made available for the academic community to allow us to make upto 20 predictions per day with this new version.
+Pre-calculated AlphFold3 predictions are provided [here](af3server_abag_15052024.zip){:target="\_blank"}.
+
+
+Try to reproduce the previous steps and examine the quality of the various generated models. Do AlphaFold3 provide better predictions?
+
+
+
+
+
+ See the AlphaFold3 models with mapped epitope residues in orange
+
+
+
+
+
+
+
+
+
+
+
+
+ See the AlphaFold3 models onto the crystal structure of the complex (4G6M) in red
+
+
+
+
+
+
+
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus6-scoring.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus6-scoring.md
new file mode 100644
index 000000000..40e029b52
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/bonus6-scoring.md
@@ -0,0 +1,181 @@
+## BONUS 6: Running a scoring scenario
+
+This section demonstrates the use of HADDOCK3 to score the various models obtained at the previous stages (ensemble docking and AlphaFold predictions)
+and observe if the HADDOCK scoring function is able to detect the quality of the models.
+
+To this end the following workflow is defined:
+
+1. Generate the topologies for the various models.
+2. Energy Minimise all complexes.
+3. Cluster the models using Fraction of Common Contacts:
+ - set the parameter `min_population` to 1 so that all models, including singletons (models that do not cluster with any others), will be forwarded to the next steps.
+ - set the parameter `plot_matrix` to true to generate a matrix of the clusters for a visual representation.
+4. Comparison of the models with the reference complex `4G6M_matched.pdb` using CAPRI criteria.
+
+For this, two ensembles must be scored and one structure will be used as a reference. You can find them in the `pdbs/` directory:
+- `07_emref_and_top5af2_ensemble.pdb`: An ensemble of models obtained from the ensemble run, combined with top5 AlphaFold2 predictions.
+- `af3server_15052024_top5ens.pdb`: An ensemble of top5 AlphaFold3 predictions.
+- `4G6M_matched.pdb`: The reference structure for quality assessments.
+
+
+{% highlight toml %}
+# ====================================================================
+# Antibody-antigen docking example with restraints from the antibody
+# paratope to the NMR-identified epitope on the antigen
+# ====================================================================
+run_dir = "scoring-haddock3-alphafold2and3-ensemble"
+
+molecules = [
+ "pdbs/haddock3-ens-emref-ensemble.pdb",
+ "pdbs/af2-models.pdb",
+ "pdbs/af3-models.pdb",
+ ]
+
+# ====================================================================
+# Parameters for each stage are defined below
+# ====================================================================
+
+[topoaa]
+
+[emscoring]
+
+[clustfcc]
+# Reduce the min_population to define a cluster to 1 so that models
+# that do not cluster with any other will define singlotons
+min_population = 1
+# Generate a matrix of the clusters
+plot_matrix = true
+
+[caprieval]
+reference_fname = "4G6M_matched.pdb"
+
+# ====================================================================
+
+{% endhighlight %}
+
+
+A scoring scenario configuration file is provided in the `workflows/` directory as `scoring-antibody-antigen.cfg, precomputed results in `runs/run-scoring`.
+
+You can again look at the `capri_ss.tsv` file in the `4_caprieval` directory. It contains the energy minimised statistics:
+
+
The bottom eight models (the worst ranking ones) are all AlphaFold3/2 models. Looking at the componenents of the score
+ (some were left out in the table below for simplicity) one can see that it is mainly the van der Waals energy that causes the high scores,
+ which is indicative of clashes in the models.
+
+
+
+
+Inspect more closely the reported scores above? Can you discover something peculiar with the buried surface area?
+
+
+
+How can you explain that?
+
+
+**_Hint 1_**: The HADDOCK score is calculated over all existing interfaces defined by different chainIDs.
+
+**_Hint 2_**: Visualise two of the models with very different BSA values, color-coding the chains.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/conclusions.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/conclusions.md
new file mode 100644
index 000000000..2099c723d
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/conclusions.md
@@ -0,0 +1,6 @@
+## Conclusions
+
+We have demonstrated the usage of HADDOCK3 in an antibody-antigen docking scenario making use of the paratope information on the antibody side (i.e. no prior experimental information, but computational predictions) and an NMR-mapped epitope for the antigen.
+Compared to the static HADDOCK2.X workflow, the modularity and flexibility of HADDOCK3 allow to customise the docking protocols and to run a deeper analysis of the results.
+HADDOCK3's intrinsic flexibility can be used to improve the performance of antibody-antigen modelling compared to the results we presented in our
+[Structure 2020](https://doi.org/10.1016/j.str.2019.10.011){:target="_blank"} article and in the [related HADDOCK2.4 tutorial](/education/HADDOCK24/HADDOCK24-antibody-antigen){:target="_blank"}.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/congratulations.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/congratulations.md
new file mode 100644
index 000000000..79d35e043
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/congratulations.md
@@ -0,0 +1,5 @@
+## Congratulations! 🎉
+
+You have completed this tutorial. If you have any questions or suggestions, feel free to contact us via email or asking a question through our [support center](https://ask.bioexcel.eu){:target="_blank"}.
+
+And check also our [education](/education){:target="_blank"} web page where you will find more tutorials!
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/docking-intro.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/docking-intro.md
new file mode 100644
index 000000000..d15778191
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/docking-intro.md
@@ -0,0 +1,5 @@
+## Setting up and running the docking with HADDOCK3
+
+Now that we have all required files at hand (PDB and restraints files), it is time to setup our docking protocol.
+In this tutorial, considering we have rather good information about the paratope and epitope, we will execute a fast HADDOCK3 docking workflow,
+reducing the non-negligible computational cost of HADDOCK by decreasing the sampling, without impacting too much the accuracy of the resulting models.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/docking-workflow.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/docking-workflow.md
new file mode 100644
index 000000000..9b38d7e0e
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/docking-workflow.md
@@ -0,0 +1,150 @@
+### HADDOCK3 workflow definition
+
+The first step is to create a HADDOCK3 configuration file that will define the docking workflow.
+We will follow a classic HADDOCK workflow consisting of rigid body docking, semi-flexible refinement and final energy minimisation followed by clustering.
+
+We will also integrate two analysis modules in our workflow:
+
+- `caprieval` will be used at various stages to compare models to either the best scoring model (if no reference is given) or a reference structure, which in our case we have at hand (`pdbs/4G6M_matched.pdb`). This will directly allow us to assess the performance of the protocol. In the absence of a reference, `caprieval` is still usefull to assess the convergence of a run and analyse the results.
+- `contactmap` added as last module will generate contact matrices of both intra- and intermolecular contacts and a chordchart of intermolecular contacts for each cluster.
+
+
+Our workflow consists of the following modules:
+
+1. **`topoaa`**: *Generates the topologies for the CNS engine and builds missing atoms*
+2. **`rigidbody`**: *Performs rigid body energy minimisation (`it0` in haddock2.x)*
+3. **`caprieval`**: *Calculates CAPRI metrics (i-RMSD, l-RMSD, Fnat, DockQ) with respect to the top scoring model or reference structure if provided*
+4. **`seletop`** : *Selects the top X models from the previous module*
+5. **`flexref`**: *Preforms semi-flexible refinement of the interface (`it1` in haddock2.4)*
+6. **`caprieval`**
+7. **`emref`**: *Final refinement by energy minimisation (`itw` EM only in haddock2.4)*
+8. **`caprieval`**
+9. **`clustfcc`**: *Clustering of models based on the fraction of common contacts (FCC)*
+10. **`seletopclusts`**: *Selects the top models of all clusters*
+11. **`caprieval`**
+12. **`contactmap`**: *Contacts matrix and a chordchart of intermolecular contacts*
+
+
+The corresponding toml configuration file (provided in `workflows/docking-antibody-antigen.cfg`) looks like:
+
+{% highlight toml %}
+# ====================================================================
+# Antibody-antigen docking example with restraints from the antibody
+# paratope to the NMR-identified epitope on the antigen
+# ====================================================================
+
+# Directory in which the scoring will be done
+run_dir = "run1"
+
+# Compute mode
+mode = "local"
+ncores = 50
+
+# Self contained rundir (to avoid problems with long filename paths)
+self_contained = true
+
+# Post-processing to generate statistics and plots
+postprocess = true
+clean = true
+
+molecules = [
+ "pdbs/4G6K_clean.pdb",
+ "pdbs/4I1B_clean.pdb"
+ ]
+
+# ====================================================================
+# Parameters for each stage are defined below, prefer full paths
+# ====================================================================
+[topoaa]
+
+[rigidbody]
+# CDR to NMR epitope ambig restraints
+ambig_fname = "restraints/ambig-paratope-NMR-epitope.tbl"
+# Restraints to keep the antibody chains together
+unambig_fname = "restraints/antibody-unambig.tbl"
+# Reduced sampling (100 instead of the default of 1000)
+sampling = 100
+
+[caprieval]
+reference_fname = "pdbs/4G6M_matched.pdb"
+
+[seletop]
+# Selection of the top 50 best scoring complexes (instead of the default of 200)
+select = 50
+
+[flexref]
+tolerance = 5
+# CDR to NMR epitope ambig restraints
+ambig_fname = "restraints/ambig-paratope-NMR-epitope.tbl"
+# Restraints to keep the antibody chains together
+unambig_fname = "restraints/antibody-unambig.tbl"
+
+[caprieval]
+reference_fname = "pdbs/4G6M_matched.pdb"
+
+[emref]
+tolerance = 5
+# CDR to NMR epitope ambig restraints
+ambig_fname = "restraints/ambig-paratope-NMR-epitope.tbl"
+# Restraints to keep the antibody chains together
+unambig_fname = "restraints/antibody-unambig.tbl"
+
+[caprieval]
+reference_fname = "pdbs/4G6M_matched.pdb"
+
+[clustfcc]
+plot_matrix = true
+
+[seletopclusts]
+# Selection of the top 4 best scoring complexes from each cluster
+top_models = 4
+
+[caprieval]
+reference_fname = "pdbs/4G6M_matched.pdb"
+
+[contactmap]
+
+# ====================================================================
+
+{% endhighlight %}
+
+
+In this case, since we have information for both interfaces we use a low-sampling configuration file, which takes only a small amount of computational resources to run.
+The initial `sampling` parameter at the rigid-body energy minimization (`rigidbody`) module is set to 100 models, of which only best the 40 are passed to the flexible refinement (`flexref`) module with the `seletop` module.
+The subsequence flexible refinement (`flexref` module) and energy minimisation (*emref*) modules will use all models passed by the *seletop* module.
+FCC clustering (`clustfcc`) is then applied to group together models sharing a consistent fraction of the interface contacts.
+The top 4 models of each cluster are saved to disk (`seletopclusts`).
+
+Multiple `caprieval` modules are executed at different stages of the workflow to check how the quality (and rankings) of the models change throughout the protocol.
+In this case we are providing the known crystal structure of the complex as reference.
+
+
+**_Note_**: For making best use of the available CPU resources it is recommended to adapt the sampling parameter to be a multiple of the number of available cores when running in local mode. For this reason, for the ASM HPC/AI school the sampling is set to be a multiple of 48.
+
+**_Note_**: In case no reference is available (the usual scenario), the best ranked model is used as reference for each stage.
+Including `caprieval` at the various stages even when no reference is provided is useful to get the rankings and scores and visualise the results (see Analysis section below).
+
+**_Note_**: The default sampling would be 1000 models for `rigidbody` of which 200 are passed to the flexible refinement in `seletop`.
+As an indication of the computational requirements, the default sampling worflow for this tutorial completes in about 37min using 12 cores on a MaxOSX M2 processor.
+In comparison, the reduced sampling run (100/40) takes about 7-8min.
+
+
+
+**_Note_**: To get a list of all possible parameters that can be defined in a specific module (and their default values) you can use the following command:
+
+
+haddock3-cfg -m \
+
+
+Add the `-d` option to get a more detailed description of parameters and use the `-h` option to see a list of arguments and options.
+
+Alternatively, you can consult the [developer's guide](https://www.bonvinlab.org/haddock3/){:target="_blank"}, where each parameter of each module is listed along with their default values, short and long descriptions, etc. Navigate to the [Modules](https://www.bonvinlab.org/haddock3/modules/index.html#){:target="_blank"} and select a module which parameters you want to display.
+
+
+In the above workflow we see in three modules a *tolerance* parameter defined. Using the *haddock3-cfg* command try to figure out what this parameter does.
+
+
+
+*__Note__* that, in contrast to HADDOCK2.X, we have much more flexibility in defining our workflow.
+As an example, we could use this flexibility by introducing a clustering step after the initial rigid-body docking stage, selecting a given number of models per cluster and refining all of those.
+For an example of this strategy see the 4 section about ensemble docking.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/haddock-concepts.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/haddock-concepts.md
new file mode 100644
index 000000000..bd090ed5a
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/haddock-concepts.md
@@ -0,0 +1,24 @@
+## HADDOCK general concepts
+
+HADDOCK (see [https://www.bonvinlab.org/software/haddock2.4](https://www.bonvinlab.org/software/haddock2.4){:target="_blank"})
+is a collection of python scripts derived from ARIA ([https://aria.pasteur.fr](https://aria.pasteur.fr){:target="_blank"})
+that harness the power of CNS (Crystallography and NMR System – [https://cns-online.org](https://cns-online.org){:target="_blank"})
+for structure calculation of molecular complexes. What distinguishes HADDOCK from other docking software is its ability,
+inherited from CNS, to incorporate experimental data as restraints and use these to guide the docking process alongside
+traditional energetics and shape complementarity. Moreover, the intimate coupling with CNS endows HADDOCK with the
+ability to actually produce models of sufficient quality to be archived in the Protein Data Bank.
+
+A central aspect of HADDOCK is the definition of Ambiguous Interaction Restraints or AIRs. These allow the
+translation of raw data such as NMR chemical shift perturbation or mutagenesis experiments into distance
+restraints that are incorporated into the energy function used in the calculations. AIRs are defined through
+a list of residues that fall under two categories: active and passive. Generally, active residues are those
+of central importance for the interaction, such as residues whose knockouts abolish the interaction or those
+where the chemical shift perturbation is higher. Throughout the simulation, these active residues are
+restrained to be part of the interface, if possible, otherwise incurring a scoring penalty. Passive residues
+are those that contribute to the interaction but are deemed of less importance. If such a residue does
+not belong in the interface there is no scoring penalty. Hence, a careful selection of which residues are
+active and which are passive is critical for the success of the docking.
+
+
+
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/haddock3-execution-modes.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/haddock3-execution-modes.md
new file mode 100644
index 000000000..146e72b72
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/haddock3-execution-modes.md
@@ -0,0 +1,141 @@
+#### Learn more about the various execution modes of haddock3
+
+
+
+
+
+ Local executionexpand_more
+
+
+In this mode HADDOCK3 will run on the current system, using the defined number of cores (ncores)
+in the config file to a maximum of the total number of available cores on the system minus one.
+An example of the relevant parameters to be defined in the first section of the config file is:
+
+{% highlight toml %}
+# compute mode
+mode = "local"
+# 1 nodes x 50 ncores
+ncores = 50
+{% endhighlight %}
+
+In this mode HADDOCK3 can be started from the command line with as argument the configuration file of the defined workflow.
+
+{% highlight shell %}
+haddock3
+{% endhighlight %}
+
+Alternatively redirect the output to a log file and send haddock3 to the background.
+
+
+As an indication, running locally on an Apple M2 laptop using 10 cores, this workflow completed in 7 minutes.
+
+
+{% highlight shell %}
+haddock3 > haddock3.log &
+{% endhighlight %}
+
+Note: This is also the execution mode that should be used for example when submitting the HADDOCK3 job to a node of a cluster, requesting X number of cores.
+
+
+
+
+
+
+
+ Exection in batch mode using slurmexpand_more
+
+
+ Here is an example script for submitting via the slurm batch system:
+
+{% highlight shell %}
+#!/bin/bash
+#SBATCH --nodes=1
+#SBATCH --tasks-per-node=50
+#SBATCH -J haddock3
+#SBATCH --partition=medium
+
+# activate the haddock3 conda environment
+source $HOME/miniconda3/etc/profile.d/conda.sh
+conda activate haddock3
+
+# go to the run directory
+cd $HOME/HADDOCK3-antibody-antigen
+
+# execute
+haddock3
+{% endhighlight %}
+
+
+
+ In this mode HADDOCK3 will typically be started on your local server (e.g. the login node) and will dispatch jobs to the batch system of your cluster.
+ Two batch systems are currently supported: slurm and torque (defined by the batch_type parameter).
+ In the configuration file you will have to define the queue name and the maximum number of concurrent jobs sent to the queue (queue_limit).
+
+ Since HADDOCK3 single model calculations are quite fast, it is recommended to calculate multiple models within one job submitted to the batch system.
+ he number of model per job is defined by the concat parameter in the configuration file.
+ You want to avoid sending thousands of very short jobs to the batch system if you want to remain friend with your system administrators...
+
+ An example of the relevant parameters to be defined in the first section of the config file is:
+
+ {% highlight toml %}
+ # compute mode
+ mode = "batch"
+ # batch system
+ batch_type = "slurm"
+ # queue name
+ queue = "short"
+ # number of concurrent jobs to submit to the batch system
+ queue_limit = 100
+ # number of models to produce per submitted job
+ concat = 10
+ {% endhighlight %}
+
+ In this mode HADDOCK3 can be started from the command line as for the local mode.
+
+
+
+
+
+
+ Exection in MPI modeexpand_more
+
+
+
+HADDOCK3 supports a parallel pseudo-MPI implementation. For this to work, the mpi4py library must have been installed at installation time.
+Refer to the (MPI-related instructions).
+
+The execution mode should be set to `mpi` and the total number of cores should match the requested resources when submitting to the batch system.
+
+An example of the relevant parameters to be defined in the first section of the config file is:
+
+{% highlight toml %}
+# compute mode
+mode = "mpi"
+# 5 nodes x 50 tasks = ncores = 250
+ncores = 250
+{% endhighlight %}
+
+In this execution mode the HADDOCK3 job should be submitted to the batch system requesting the corresponding number of nodes and cores per node.
+
+
+ {% highlight shell %}
+ #!/bin/bash
+ #SBATCH --nodes=5
+ #SBATCH --tasks-per-node=50
+ #SBATCH -J haddock3mpi
+
+ # Make sure haddock3 is activated
+ source $HOME/miniconda3/etc/profile.d/conda.sh
+ conda activate haddock3
+
+ # go to the run directory
+ # edit if needed to specify the correct location
+ cd $HOME/HADDOCK3-antibody-antigen
+
+ # execute
+ haddock3 \
+ {% endhighlight %}
+
+
+
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/haddock3-intro.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/haddock3-intro.md
new file mode 100644
index 000000000..85a38d15b
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/haddock3-intro.md
@@ -0,0 +1,77 @@
+## A brief introduction to HADDOCK3
+
+HADDOCK3 is the next generation integrative modelling software in the
+long-lasting HADDOCK project. It represents a complete rethinking and rewriting
+of the HADDOCK2.X series, implementing a new way to interact with HADDOCK and
+offering new features to users who can now define custom workflows.
+
+In the previous HADDOCK2.x versions, users had access to a highly
+parameterisable yet rigid simulation pipeline composed of three steps:
+`rigid-body docking (it0)`, `semi-flexible refinement (it1)`, and `final refinement (itw)`.
+
+
+
+
+
+In HADDOCK3, users have the freedom to configure docking workflows into
+functional pipelines by combining the different HADDOCK3 modules, thus
+adapting the workflows to their projects. HADDOCK3 has therefore developed to
+truthfully work like a puzzle of many pieces (simulation modules) that users can
+combine freely. To this end, the "old" HADDOCK machinery has been modularized,
+and several new modules added, including third-party software additions. As a
+result, the modularization achieved in HADDOCK3 allows users to duplicate steps
+within one workflow (e.g., to repeat twice the `it1` stage of the HADDOCK2.x
+rigid workflow).
+
+Note that, for simplification purposes, at this time, not all functionalities of
+HADDOCK2.x have been ported to HADDOCK3, which does not (yet) support NMR RDC,
+PCS and diffusion anisotropy restraints, cryo-EM restraints and coarse-graining.
+Any type of information that can be converted into ambiguous interaction
+restraints can, however, be used in HADDOCK3, which also supports the
+*ab initio* docking modes of HADDOCK.
+
+
+
+
+
+To keep HADDOCK3 modules organized, we catalogued them into several
+categories. However, there are no constraints on piping modules of different
+categories.
+
+The main module categories are "topology", "sampling", "refinement",
+"scoring", and "analysis". There is no limit to how many modules can belong to a
+category. Modules are added as developed, and new categories will be created
+if/when needed. You can access the HADDOCK3 documentation page for the list of
+all categories and modules. Below is a summary of the available modules:
+
+* **Topology modules**
+ * `topoaa`: *generates the all-atom topologies for the CNS engine.*
+* **Sampling modules**
+ * `rigidbody`: *Rigid body energy minimization with CNS (`it0` in haddock2.x).*
+ * `lightdock`: *Third-party glow-worm swam optimization docking software.*
+* **Model refinement modules**
+ * `flexref`: *Semi-flexible refinement using a simulated annealing protocol through molecular dynamics simulations in torsion angle space (`it1` in haddock2.x).*
+ * `emref`: *Refinement by energy minimisation (`itw` EM only in haddock2.4).*
+ * `mdref`: *Refinement by a short molecular dynamics simulation in explicit solvent (`itw` in haddock2.X).*
+* **Scoring modules**
+ * `emscoring`: *scoring of a complex performing a short EM (builds the topology and all missing atoms).*
+ * `mdscoring`: *scoring of a complex performing a short MD in explicit solvent + EM (builds the topology and all missing atoms).*
+* **Analysis modules**
+ * `alascan`: *Performs a systematic (or user-define) alanine scanning mutagenesis of interface residues.*
+ * `caprieval`: *Calculates CAPRI metrics (i-RMSD, l-RMSD, Fnat, DockQ) with respect to the top-scoring model or reference structure if provided.*
+ * `clustfcc`: *Clusters models based on the fraction of common contacts (FCC)*
+ * `clustrmsd`: *Clusters models based on pairwise RMSD matrix calculated with the `rmsdmatrix` module.*
+ * `contactmap`: *Generate contact matrices of both intra- and intermolecular contacts and a chordchart of intermolecular contacts.*
+ * `rmsdmatrix`: *Calculates the pairwise RMSD matrix between all the models generated in the previous step.*
+ * `ilrmsdmatrix`: *Calculates the pairwise interface-ligand-RMSD (il-RMSD) matrix between all the models generated in the previous step.*
+ * `seletop`: *Selects the top N models from the previous step.*
+ * `seletopclusts`: *Selects the top N clusters from the previous step.*
+
+The HADDOCK3 workflows are defined in simple configuration text files, similar to the TOML format but with extra features.
+Contrary to HADDOCK2.X which follows a rigid (yet highly parameterisable)
+procedure, in HADDOCK3, you can create your own simulation workflows by
+combining a multitude of independent modules that perform specialized tasks.
+
+
+
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/intro.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/intro.md
new file mode 100644
index 000000000..57cd468c2
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/intro.md
@@ -0,0 +1,37 @@
+## Introduction
+
+This tutorial demonstrates the use of the new modular HADDOCK3 version for predicting
+the structure of an antibody-antigen complex using knowledge of the hypervariable loops
+on the antibody (i.e., the most basic knowledge) and epitope information identified from NMR experiments for the antigen to guide the docking.
+
+This tutorial was recorded at the BioExcel Sofia Workshop in May 2025:
+
+
+
+An antibody is a large protein that generally works by attaching itself to an antigen,
+which is a unique site of the pathogen. The binding harnesses the immune system to directly
+attack and destroy the pathogen. Antibodies can be highly specific while showing low immunogenicity (i.e. the ability to provoke an immune response),
+which is achieved by their unique structure. **The fragment crystallizable region (Fc region)**
+activates the immune response and is species-specific, i.e. the human Fc region should not
+induce an immune response in humans. **The fragment antigen-binding region (Fab region**)
+needs to be highly variable to be able to bind to antigens of various nature (high specificity).
+In this tutorial, we will concentrate on the terminal **variable domain (Fv)** of the Fab region.
+
+
+
+
+
+The small part of the Fab region that binds the antigen is called **paratope**. The part of the antigen
+that binds to an antibody is called **epitope**. The paratope consists of six highly flexible loops,
+known as **complementarity-determining regions (CDRs)** or hypervariable loops whose sequence
+and conformation are altered to bind to different antigens. CDRs are shown in red in the figure below:
+
+
+
+
+
+In this tutorial we will be working with Interleukin-1β (IL-1β)
+(PDB code [4I1B](https://www.ebi.ac.uk/pdbe/entry/pdb/4i1b){:target="_blank"}) as an antigen
+and its highly specific monoclonal antibody gevokizumab
+(PDB code [4G6K](https://www.ebi.ac.uk/pdbe/entry/pdb/4g6k){:target="_blank"})
+(PDB code of the complex [4G6M](https://www.ebi.ac.uk/pdbe/entry/pdb/4g6m){:target="_blank"}).
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/preparing-antibody.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/preparing-antibody.md
new file mode 100644
index 000000000..42ae6a526
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/preparing-antibody.md
@@ -0,0 +1,41 @@
+### Preparing the antibody structure
+
+Using PDB-tools we will download the unbound structure of the antibody from the PDB database (the PDB ID is [4G6K](https://www.ebi.ac.uk/pdbe/entry/pdb/4g6k){:target="_blank"})
+and then process it to have a unique chain ID (A) and non-overlapping residue numbering by renumbering the merged pdb (starting from 1). For this we will concatenate the following PDB-tools commands:
+
+1. fetch the PDB entry from the PDB database (`pdb_fetch`)
+2. clean the PDB file (`pdb_tidy`)
+3. select the chain (`pdb_selchain`),
+4. remove any hetero atoms from the structure (e.g. crystal waters, small molecules from the crystallisation buffer and such) (`pdb_delhetatm`),
+5. fix residue numbering insertion in the HV loops (often occuring in antibodies - see note below) (`pdb_fixinsert`)
+6. remove any possible side-chain duplication (can be present in high-resolution crystal structures in case of multiple conformations of some side chains) (`pdb_selaltloc`)
+7. keep only the coordinates lines (`pdb_keepcoord`),
+8. select only the variable domain (FV) of the antibody (to reduce computing time) (`pdb_selres`)
+9. clean the PDB file (`pdb_tidy`)
+
+**_Note_** that the `pdb_tidy -strict` commands cleans the PDB file, add TER statements only between different chains).
+Without the -strict option TER statements would be added between each chain break (e.g. missing residues), which should be avoided.
+
+**_Note_**: An important part for antibodies is the `pdb_fixinsert` command that fixes the residue numbering of the HV loops:
+Antibodies often follow the [Chothia numbering scheme](https://pubmed.ncbi.nlm.nih.gov/9367782/?otool=inluulib){:target="_blank"}
+and insertions created by this numbering scheme (e.g. 82A, 82B, 82C) cannot be processed by HADDOCK directly
+(if not done those residues will not be considered resulting effectively in a break in the loop).
+As such, renumbering is necessary before starting the docking.
+
+
+This can be done from the command line with:
+
+
+pdb_fetch 4G6K | pdb_tidy \-strict | pdb_selchain \-H | pdb_delhetatm | pdb_fixinsert | pdb_selaltloc | pdb_keepcoord | pdb_selres \-1:120 | pdb_tidy -strict > 4G6K_H.pdb
+
+
+pdb_fetch 4G6K | pdb_tidy \-strict | pdb_selchain -L | pdb_delhetatm | pdb_fixinsert | pdb_selaltloc | pdb_keepcoord | pdb_selres \-1:107 | pdb_tidy \-strict > 4G6K_L.pdb
+
+
+We then combined the heavy and light chain into one, renumbering the residues starting at 1 to avoid overlap in residue numbering between the chains and assigning a unique chainID/segID:
+
+
+pdb_merge 4G6K_H.pdb 4G6K_L.pdb | pdb_reres \-1 | pdb_chain \-A | pdb_chainxseg | pdb_tidy \-strict > 4G6K_clean.pdb
+
+
+_**Note**_ The ready-to-use file can be found in the `pdbs` directory of the provided tutorial data.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/preparing-antigen.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/preparing-antigen.md
new file mode 100644
index 000000000..77575dd05
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/preparing-antigen.md
@@ -0,0 +1,10 @@
+### Preparing the antigen structure
+
+Using PDB-tools, we will now download the unbound structure of Interleukin-1β from the PDB database (the PDB ID is [4I1B](https://www.ebi.ac.uk/pdbe/entry/pdb/4i1b){:target="_blank"}),
+remove the hetero atoms and then process it to assign it chainID B.
+
+*__Important__: Each molecule given to HADDOCK in a docking scenario must have a unique chainID/segID.*
+
+
+pdb_fetch 4I1B | pdb_tidy \-strict | pdb_delhetatm | pdb_selaltloc | pdb_keepcoord | pdb_chain \-B | pdb_chainxseg | pdb_tidy \-strict > 4I1B_clean.pdb
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/preparing-pdb-intro.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/preparing-pdb-intro.md
new file mode 100644
index 000000000..91be1c2d6
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/preparing-pdb-intro.md
@@ -0,0 +1,11 @@
+## Preparing PDB files for docking
+
+In this section we will prepare the PDB files of the antibody and antigen for docking.
+Crystal structures of both the antibody and the antigen in their free forms are available from the
+[PDBe database](https://www.pdbe.org){:target="_blank"}.
+
+__Important:__ For a docking run with HADDOCK, each molecule should consist of a single chain with non-overlapping residue numbering within the same chain.
+
+As an antibody consists of two chains (L+H), we will have to prepare it for use in HADDOCK. For this we will be making use of `pdb-tools` from the command line.
+
+_**Note**_ that `pdb-tools` is also available as a [web service](https://wenmr.science.uu.nl/pdbtools/){:target="_blank"}.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/prompt-legend.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/prompt-legend.md
new file mode 100644
index 000000000..81668b8ee
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/prompt-legend.md
@@ -0,0 +1,7 @@
+Throughout the tutorial, colored text will be used to refer to questions or
+instructions, and/or PyMOL commands.
+
+This is a question prompt: try answering it!
+This an instruction prompt: follow it!
+This is a PyMOL prompt: write this in the PyMOL command line prompt!
+This is a Linux prompt: insert the commands in the terminal!
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-ambiguous.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-ambiguous.md
new file mode 100644
index 000000000..958b769b8
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-ambiguous.md
@@ -0,0 +1,152 @@
+### Defining ambiguous restraints
+
+Once you have identified your active and passive residues for both molecules, you can proceed with the generation of the ambiguous interaction restraints (AIR) file for HADDOCK.
+For this you can either make use of our online `Generate Restraints` [haddock-restraints][haddock-restraints] web service, entering the list of active and passive residues for each molecule,
+the chainIDs of each molecule and saving the resulting restraint list to a text file, or use another `haddock3-restraints` sub-command.
+
+To use our `haddock3-restraints active_passive_to_ambig` script, you need to
+create for each molecule a file containing two lines:
+
+* The first line corresponds to the list of active residues (numbers separated by spaces)
+* The second line corresponds to the list of passive residues (numbers separated by spaces).
+
+*__Important__*: The file must consist of two lines, but a line can be empty (e.g., if you do not want to define active residues for one molecule).
+However, there must be at least one set of active residue defined for one of the molecules.
+
+
+* For the antibody we will use the predicted paratope as active and no passive residues defined.
+The corresponding file can be found in the `restraints` directory as `antibody-paratope.act-pass`:
+
+
+
+* For the antigen we will use the NMR-identified epitope as active and the surface neighbors as passive.
+The corresponding file can be found in the `restraints` directory as `antigen-NMR-epitope.act-pass`:
+
+
+assign (resi 31 and segid A)
+(
+ (resi 72 and segid B)
+ or
+ (resi 73 and segid B)
+ or
+ (resi 74 and segid B)
+ or
+ (resi 75 and segid B)
+ or
+ (resi 81 and segid B)
+ or
+ (resi 83 and segid B)
+ or
+ (resi 84 and segid B)
+ or
+ (resi 89 and segid B)
+ or
+ (resi 90 and segid B)
+ or
+ (resi 92 and segid B)
+ or
+ (resi 94 and segid B)
+ or
+ (resi 96 and segid B)
+ or
+ (resi 97 and segid B)
+ or
+ (resi 98 and segid B)
+ or
+ (resi 115 and segid B)
+ or
+ (resi 116 and segid B)
+ or
+ (resi 117 and segid B)
+ or
+ (resi 3 and segid B)
+ or
+ (resi 24 and segid B)
+ or
+ (resi 46 and segid B)
+ or
+ (resi 47 and segid B)
+ or
+ (resi 48 and segid B)
+ or
+ (resi 50 and segid B)
+ or
+ (resi 66 and segid B)
+ or
+ (resi 76 and segid B)
+ or
+ (resi 77 and segid B)
+ or
+ (resi 79 and segid B)
+ or
+ (resi 80 and segid B)
+ or
+ (resi 82 and segid B)
+ or
+ (resi 86 and segid B)
+ or
+ (resi 87 and segid B)
+ or
+ (resi 88 and segid B)
+ or
+ (resi 91 and segid B)
+ or
+ (resi 93 and segid B)
+ or
+ (resi 95 and segid B)
+ or
+ (resi 118 and segid B)
+ or
+ (resi 119 and segid B)
+ or
+ (resi 120 and segid B)
+) 2.0 2.0 0.0
+...
+
+
+
+
+
+
+Refering to the way the distance restraints are defined (see above), what is the distance range for the ambiguous distance restraints?
+
+
+
+
+ See answerexpand_more
+
+The default distance range for those is between 0 and 2Å, which
+might seem short but makes senses because of the 1/r^6 summation in the AIR
+energy function that makes the effective distance to be significantly shorter than
+the shortest distance entering the sum.
+
+
+The effective distance is calculated as the SUM over all pairwise atom-atom
+distance combinations between an active residue and all the active+passive on
+the other molecule: SUM[1/r^6]^(-1/6).
+
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-epitope.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-epitope.md
new file mode 100644
index 000000000..f34064b16
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-epitope.md
@@ -0,0 +1,105 @@
+### Identifying the epitope of the antigen
+
+The article describing the crystal structure of the antibody-antigen complex we are modeling also reports experimental NMR chemical shift titration experiments
+to map the binding site of the antibody (gevokizumab) on Interleukin-1β.
+The residues affected by binding are listed in Table 5 of [Blech et al. JMB 2013](https://dx.doi.org/10.1016/j.jmb.2012.09.021){:target="_blank"}:
+
+
+
+
+
+The list of binding site (epitope) residues identified by NMR is:
+
+
+
+We will now visualize the epitope on Interleukin-1β.
+To do this, start PyMOL and open the provided PDB file of the antigen from the PyMOL File menu.
+
+
+File menu -> Open -> select 4I1B_clean.pdb
+
+
+
+color white, all
+show surface
+select epitope, (resi 72+73+74+75+81+83+84+89+90+92+94+96+97+98+115+116+117)
+color red, epitope
+
+
+Inspect the surface.
+
+
+Do the identified residues form a well-defined patch on the surface?
+
+
+The answer to that question should be yes, but we can see some residues not colored that might also be involved in the binding - there are some white spots around/in the red surface.
+
+
+
+ See surface view of the epitope identified by NMRexpand_more
+
+
+
+
+
+
+
+
+
+In HADDOCK, we are dealing with potentially incomplete binding sites by defining surface neighbors as `passive` residues.
+These passive residues are added in the definition of the interface but do not incur any energetic penalty if they are not part of the binding site in the final models.
+In contrast, residues defined as active (typically the identified or predicted binding site residues) will incur an energetic penalty.
+When using the HADDOCK2.x webserver, `passive` residues will be automatically defined.
+Here, since we are using a local version, we need to define those manually.
+
+This can easily be done using a haddock3 command line tool in the following way:
+
+
+haddock3-restraints passive_from_active 4I1B_clean.pdb 72,73,74,75,81,83,84,89,90,92,94,96,97,98,115,116,117
+
+
+The command prints a list of solvent accessible passive residues, which you should save to a file for further use.
+
+We can visualize the epitope and its surface neighbors using PyMOL:
+
+
+File menu -> Open -> select 4I1B_clean.pdb
+
+
+
+color white, all
+show surface
+select epitope, (resi 72+73+74+75+81+83+84+89+90+92+94+96+97+98+115+116+117)
+color red, epitope
+select passive, (resi 3+24+46+47+48+50+66+76+77+79+80+82+86+87+88+91+93+95+118+119+120)
+color green, passive
+
+
+
+
+
+ See the epitope and passive residuesexpand_more
+
+
+
+
+
+
+
+
+The NMR-identified residues and their surface neighbors generated with the above command can be used to define ambiguous interactions restraints,
+either using the NMR identified residues as active in HADDOCK, or combining those with the surface neighbors.
+
+The difference between `active` and `passive` residues in HADDOCK is as follows:
+
+*__Active residues__*: These residues are "forced" to be at the interface. If they are not part of the interface in the final models, an energetic penalty will be applied. The interface in this context is defined by the union of active and passive residues on the partner molecules.
+
+*__Passive residues__*: These residues are expected to be at the interface. However, if they are not, no energetic penalty is applied.
+
+
+In general, it is better to be too generous rather than too strict in the definition of passive residues.
+An important aspect is to filter both the active (the residues identified from your mapping experiment) and passive residues by their solvent accessibility.
+This is done automatically when using the `haddock3-restraints passive_from_active` command: residues with less that 15% relative solvent accessibility (same cutoff as the default in the HADDOCK server) are discared.
+This is, however, not a hard limit, and you might consider including even more buried residues if some important chemical group seems solvent accessible from a visual inspection.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-intro.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-intro.md
new file mode 100644
index 000000000..32657cb82
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-intro.md
@@ -0,0 +1,34 @@
+## Defining restraints for docking
+
+Before setting up the docking, we first need to generate distance restraint files in a format suitable for HADDOCK.
+HADDOCK uses [CNS][link-cns]{:target="_blank"} as computational engine.
+A description of the format for the various restraint types supported by HADDOCK can be found in our [Nature Protocol 2024][nat-pro]{:target="_blank"} paper, Box 1.
+
+Distance restraints are defined as follows:
+
+
+
+The lower limit for the distance is calculated as: distance minus lower-bound correction
+and the upper limit as: distance plus upper-bound correction.
+
+The syntax for the selections can combine information about:
+
+* chainID - `segid` keyword
+* residue number - `resid` keyword
+* atom name - `name` keyword.
+
+Other keywords can be used in various combinations of OR and AND statements. Please refer for that to the [online CNS manual][link-cns]{:target="_blank"}.
+
+E.g.: a distance restraint between the CB carbons of residues 10 and 200 in chains A and B with an
+allowed distance range between 10Å and 20Å would be defined as follows:
+
+
+assign (segid A and resid 10 and name CB) (segid B and resid 200 and name CB) 20.0 10.0 0.0
+
+
+
+Can you think of a different way of defining the distance and lower and upper corrections while maintaining the same
+allowed range?
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-multichain.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-multichain.md
new file mode 100644
index 000000000..5d03e7b2d
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-multichain.md
@@ -0,0 +1,18 @@
+### Additional restraints for multi-chain proteins
+
+As an antibody consists of two separate chains, it is important to define a few distance restraints
+to keep them together during the high temperature flexible refinement stage of HADDOCK otherwise they might slightly drift appart.
+This can easily be done using the `haddock3-restraints restrain_bodies` sub-command.
+
+
+haddock3-restraints restrain_bodies 4G6K_clean.pdb > antibody-unambig.tbl
+
+
+The result file contains two CA-CA distance restraints with the exact distance measured between two randomly picked CA atoms pairs:
+
+
+ assign (segid A and resi 110 and name CA) (segid A and resi 132 and name CA) 26.326 0.0 0.0
+ assign (segid A and resi 97 and name CA) (segid A and resi 204 and name CA) 19.352 0.0 0.0
+
+
+This file is also provided in the `restraints` directory.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-paratope.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-paratope.md
new file mode 100644
index 000000000..7fbc1e63e
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-paratope.md
@@ -0,0 +1,63 @@
+### Identifying the paratope of the antibody
+
+Nowadays several computational tools can identify the paratope (the residues of the hypervariable loops involved in binding) from the provided antibody sequence.
+In this tutorial, we are providing you with the corresponding list of residue obtained using [ProABC-2](https://github.com/haddocking/proabc-2){:target="_blank"}.
+ProABC-2 uses a convolutional neural network to identify not only residues which are located in the paratope region
+but also the nature of interactions they are most likely involved in (hydrophobic or hydrophilic).
+The work is described in [Ambrosetti, *et al* Bioinformatics, 2020](https://academic.oup.com/bioinformatics/article/36/20/5107/5873593){:target="_blank"}.
+
+The corresponding paratope residues (those with either an overall probability >= 0.4 or a probability for hydrophobic or hydrophilic > 0.3) are:
+
+
+
+The numbering corresponds to the numbering of the `4G6K_clean.pdb` PDB file.
+
+Let us visualize those onto the 3D structure.
+For this start PyMOL and load `4G6K_clean.pdb`
+
+
+File menu -> Open -> select 4G6K_clean.pdb
+
+
+Alternatively, if PyMOL is accessible from the command line, simply type:
+
+
+pymol 4G6K_clean.pdb
+
+
+We will now highlight the predicted paratope residues in red. In PyMOL type the following commands:
+
+
+color white, all
+select paratope, (resi 31+32+33+34+35+52+54+55+56+100+101+102+103+104+105+106+151+152+169+170+173+211+212+213+214+216)
+color red, paratope
+
+
+
+Can you identify the H3 loop? H stands for heavy chain (the first domain in our case with lower residue numbering). H3 is typically the longest loop.
+
+
+Let us now switch to a surface representation to inspect the predicted binding site.
+
+
+show surface
+
+
+Inspect the surface.
+
+
+Do the identified paratope residues form a well-defined patch on the surface?
+
+
+
+
+
+ See surface view of the paratopeexpand_more
+
+
+
+
+
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-validation.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-validation.md
new file mode 100644
index 000000000..82a7f8540
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/restraints-validation.md
@@ -0,0 +1,11 @@
+### Restraints validation
+
+If you modify manually this generated restraint files or create your own, it is possible to quickly check if the format is valid using the following `haddock3-restraints` sub-command:
+
+
+haddock3-restraints validate_tbl ambig-paratope-NMR-epitope.tbl \-\-silent
+
+
+No output means that your TBL file is valid.
+
+*__Note__* that this only validates the syntax of the restraint file, but does not check if the selections defined in the restraints are actually existing in your input PDB files.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-bioexcel2025.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-bioexcel2025.md
new file mode 100644
index 000000000..4a0a0dc06
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-bioexcel2025.md
@@ -0,0 +1,12 @@
+#### Execution of HADDOCK3 on the computers of the BioExcel 2025 summerschool
+
+To execute the HADDOCK3 workflow on the computational resources provided for this workshop,
+we will simply run in local mode, calling haddock3 with as argument the workflow you want to execute.
+
+{% highlight shell %}
+haddock3
+{% endhighlight %}
+
+Alternatively redirect the output to a log file and send haddock3 to the background.
+
+As an indication, running locally on an Apple M2 laptop using 10 cores, this workflow completed in 7 minutes.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-discoverer.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-discoverer.md
new file mode 100644
index 000000000..e10ffd6c5
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-discoverer.md
@@ -0,0 +1,45 @@
+#### Execution of HADDOCK3 on DISCOVERER (BioExcel Sofia May 2025 workshop)
+
+
+
+ View execution instructions for running HADDOCK3 on DISCOVERERexpand_more
+
+
+To execute the HADDOCK3 workflow on the computational resources provided for this workshop,
+you should create an execution script contain specific requirements for the queueing system and the HADDOCK3 configuration and execution.
+An example slurm script is provided with the data you unzipped:
+
+{% highlight shell %}
+run-haddock3-discoverer.sh
+{% endhighlight %}
+
+
+Here is an example of such an execution script (also provided in the `HADDOCK3-antibody-antigen` directory as `run-haddock3-discoverer.sh`):
+
+{% highlight shell %}
+#!/bin/bash
+#SBATCH --nodes=1
+#SBATCH --account=school-01
+#SBATCH --qos=school-01
+#SBATCH --job-name "haddock3"
+#SBATCH --tasks-per-node=50
+#SBATCH --mem-per-cpu 1500
+#SBATCH --time 04:00:00
+
+module load python/3/3.12
+module load haddock3/2025.5.0
+haddock3 workflows/docking-antibody-antigen.cfg
+
+{% endhighlight %}
+
+This file should be submitted to the batch system using the `sbatch` command:
+
+
+sbatch run-haddock3-discoverer.sh
+
+
+And you can check the status in the queue using the `squeue`command.
+
+This example run should take about 7 minutes to complete on a single node using 50 cores.
+
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-fugaku.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-fugaku.md
new file mode 100644
index 000000000..5bb71f063
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-fugaku.md
@@ -0,0 +1,61 @@
+#### Execution of HADDOCK3 on Fugaku (ASM 2026 HPC/AI school, Kobe Japan)
+
+
+
+ View execution instructions for running HADDOCK3 on Fugakuexpand_more
+
+
+To execute the workflow on Fugaku, you can either start an interactive session or create a job file that will execute HADDOCK3 on a node,
+with HADDOCK3 running in local mode (the setup in the above configuration file with mode="local") and harvesting all core of that node (ncores=48).
+
+
+Interactive session on a node:
+
+{% highlight shell %}
+pjsub -x PJM_LLIO_GFSCACHE=/vol0003:/vol0004 -g "hp250477" --interact -L "node=1" - -L "rscgrp=int" -L "elapse=2:00:00" --sparam "wait-time=600"
+{% endhighlight %}
+
+Once the session is active, activate HADDOCK3 with:
+
+{% highlight shell %}
+source /vol0300/data/hp250477/Materials/Life_Science/20250202_Bonvin/haddock3/.venv/bin/activate
+{% endhighlight %}
+
+You can then run the workflow with:
+
+{% highlight shell %}
+haddock3 ./workflows/docking-antibody-antigen.cfg
+{% endhighlight %}
+Job submission to the batch system:
+
+
+For this execution mode you should create an execution script contain specific requirements for the queueing system and the HADDOCK3 configuration and execution.
+Here is an example of such an execution script (also provided in the HADDOCK3-antibody-antigen directory as run-haddock3-fugaku.sh):
+
+{% highlight shell %}
+#!/bin/sh -x
+#PJM -L "node=1" # Assign node 1 node
+#PJM -L "rscgrp=small" # Specify resource group
+#PJM -L "elapse=02:00:00" # Elapsed time limit 1 hour
+#PJM -g hp250477 # group name
+#PJM -x PJM_LLIO_GFSCACHE=/vol0003:/vol0004 # volume names that job uses
+#PJM -s # Statistical information output
+
+source /vol0300/data/hp250477/Materials/Life_Science/20260202-HADDOCK/haddock3/.venv/bin/activate
+haddock3 ./workflows/docking-antibody-antigen.cfg
+
+{% endhighlight %}
+
+This file should be submitted to the batch system using the pjsub command:
+
+{% highlight shell %}
+pjsub run-haddock3-fugaku.sh
+{% endhighlight %}
+
+
+
+And you can check the status in the queue using pjstat.
+
+This run should take about 25 minutes to complete on a single node using 48 arm cores.
+
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-haddock3-intro.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-haddock3-intro.md
new file mode 100644
index 000000000..0fc93677b
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-haddock3-intro.md
@@ -0,0 +1,7 @@
+### Running HADDOCK3
+
+In in the first section of the workflow above we have a parameter `mode` defining the execution mode. HADDOCK3 currently supports three difference execution modes:
+
+- **local** : In this mode, HADDOCK3 will run on the current system, using the defined number of cores (`ncores`) in the config file to a maximum of the total number of available cores on the system.
+- **batch**: In this mode, HADDOCK3 will typically be started on your local server (e.g. the login node) and will dispatch jobs to the batch system of your cluster (slurm and torque are currently supported).
+- **mpi**: HADDOCK3 also supports a pseudo parallel MPI implementation, which allows to harvest the power of multiple nodes to distribute the computations (functional but still very experimental at this stage).
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-ljubljana-2026.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-ljubljana-2026.md
new file mode 100644
index 000000000..8766a7b52
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-ljubljana-2026.md
@@ -0,0 +1,67 @@
+#### Execution of HADDOCK3 on ADD Ljubljana (BioExcel Adriatic edition 2026, Ljubljana, Slovenia)
+
+To execute the workflow, you can either start an interactive session or create a job file that will execute HADDOCK3 on a node,
+with HADDOCK3 running in local mode (the setup in the above configuration file with mode="local") and harvesting all core of that node (ncores=16).
+
+
+Start an interactive session on a node:
+
+{% highlight shell %}
+salloc --job-name=interactive_haddock3 --partition=amd --nodes=1 --cpus-per-task=16 --time-min=120
+{% endhighlight %}
+
+Once the session is active, activate HADDOCK3 with:
+
+{% highlight shell %}
+source /home/vreys/haddock3/.haddock3-env/bin/activate
+{% endhighlight %}
+
+You can then follow the tutorial and run all the commands present in it, such as starting a haddock3 docking workflow with:
+
+{% highlight shell %}
+haddock3 ./workflows/docking-antibody-antigen.cfg
+{% endhighlight %}
+Job submission to the batch system:
+
+
+For this execution mode you should create an execution script contain specific requirements for the queueing system and the HADDOCK3 configuration and execution.
+Here is an example of such an execution script (that can be saved under the name run-haddock3-slurm.sh):
+
+{% highlight shell %}
+#!/bin/bash
+#SBATCH --partition=amd
+#SBATCH --job-name=haddock3_run
+#SBATCH --nodes=1
+#SBATCH --cpus-per-task=16
+#SBATCH --time-min=120
+#SBATCH --output="haddock3_run_log.txt"
+
+# Source the environement
+source /home/vreys/haddock3/.haddock3-env/bin/activate
+
+# Go to the appropriate directory
+cd ~/HADDOCK3-antibody-antigen
+
+# Launch haddock3
+haddock3 workflows/docking-antibody-antigen.cfg
+
+
+{% endhighlight %}
+
+This file should be submitted to the batch system using the sbatch command:
+
+{% highlight shell %}
+sbatch run-haddock3-slurm.sh
+{% endhighlight %}
+
+
+
+And you can check the status in the queue using squeue -u Username.
+
+Also, you can follow the state of your run by looking a the content of either the log file or the slurm output using:
+
+{% highlight shell %}
+tail -f haddock3_run_log.txt
+{% endhighlight %}
+
+This run should take around 20 minutes to complete on a single node using 16 arm cores.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-truba.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-truba.md
new file mode 100644
index 000000000..0cd81af7e
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/run-truba.md
@@ -0,0 +1,43 @@
+#### Execution of HADDOCK3 on the TRUBA resources (EuroCC Istanbul April 2024 workshop)
+
+
+
+ View execution instructions for running HADDOCK3 the TRUBA resourcesexpand_more
+
+
+To execute the HADDOCK3 workflow on the computational resources provided for this workshop,
+you should create an execution script contain specific requirements for the queueing system and the HADDOCK3 configuration and execution.
+Two scripts are provided with the data you unzipped, one for execution on the hamsri cluster and one for the barbun cluster:
+
+{% highlight shell %}
+run-haddock3-barbun.sh
+run-haddock3-hamsri.sh
+{% endhighlight %}
+
+Here is an example of such an execution script (also provided in the HADDOCK3-antibody-antigen directory as run-haddock3-hamsri.sh):
+
+{% highlight shell %}
+#!/bin/bash
+#SBATCH --nodes=1
+#SBATCH --tasks-per-node=54
+#SBATCH -C weka
+#SBATCH -p hamsi
+#SBATCH --time 00:30:00
+
+source ~egitim/HADDOCK/haddock3/.venv/bin/activate
+haddock3 workflows/docking-antibody-antigen.cfg
+{% endhighlight %}
+
+This file should be submitted to the batch system using the sbatch command:
+
+{% highlight shell %}
+sbatch run-haddock3-hamsri.sh
+{% endhighlight %}
+
+Note that batch submission is only possible from the scratch partition (/arf/scratch/my-home-directory)
+
+And you can check the status in the queue using the squeuecommand.
+
+This example run should take about 7 minutes to complete on a single node using 50 cores.
+
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-intro.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-intro.md
new file mode 100644
index 000000000..a74423415
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-intro.md
@@ -0,0 +1,42 @@
+## Software and data setup
+
+In order to follow this tutorial you will need to work on a Linux or MacOSX
+system. We will also make use of [**PyMOL**](https://www.pymol.org/){:target="_blank"} (freely available for
+most operating systems) in order to visualize the input and output data. We will
+provide you links to download the various required software and data.
+
+Further, we are providing pre-processed PDB files for docking and analysis (but the
+preprocessing of those files will also be explained in this tutorial). The files have been processed
+to facilitate their use in HADDOCK and to allow comparison with the known reference
+structure of the complex.
+
+If you are running this tutorial on your own resources _download and unzip the following_
+[zip archive](https://surfdrive.surf.nl/public.php/dav/files/R7VHGQM9nx8QuQn){:target="_blank"}
+_and note the location of the extracted PDB files in your system_.
+
+_If running as part of the ASM HPC/AI school or a BioExcel workshop or summerschool see the instructions in the respective next sections._
+
+_Note_ that you can also download and unzip this archive directly from the Linux command line:
+
+
+wget https://surfdrive.surf.nl/public.php/dav/files/R7VHGQM9nx8QuQn -O HADDOCK3-antibody-antigen.zip
+unzip HADDOCK3-antibody-antigen.zip
+
+
+
+Unziping the file will create the `HADDOCK3-antibody-antigen` directory which should contain the following directories and files:
+
+* `pdbs`: a directory containing the pre-processed PDB files
+* `restraints`: a directory containing the interface information and the corresponding restraint files for HADDOCK3
+* `runs`: a directory containing pre-calculated results
+* `scripts`: a directory containing various scripts used in this tutorial
+* `workflows`: a directory containing configuration file examples for HADDOCK3
+
+In case of a workshop of course, HADDOCK3 will usually have been installed on the system you will be using.
+
+In case HADDOCK3 is not pre-installed in your system, you will have to install it.
+To obtain HADDOCK3, fill the [registration form](https://docs.google.com/forms/d/e/1FAIpQLScDcd0rWtuzJ_4nftkDAHoLVwr1IAVwNJGhbaZdTYZ4vWu25w/viewform?){:target="_blank"}, and then follow the [installation instructions](https://www.bonvinlab.org/haddock3-user-manual/install.html){:target="_blank"}.
+
+In this tutorial we will use the PyMOL molecular visualisation system. If not already installed, download and install PyMOL from [here](https://pymol.org/){:target="_blank"}. You can use your favourite visualisation software instead, but be aware that instructions in this tutorial are provided only for PyMOL.
+
+This tutorial was last tested using HADDOCK3 version 2024.10.0b7. The provided pre-calculated runs were obtained on a Macbook Pro M2 processors with as OS Sequoia 15.3.1.
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-kobe-2026.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-kobe-2026.md
new file mode 100644
index 000000000..78c7b7f88
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-kobe-2026.md
@@ -0,0 +1,79 @@
+### ASM 2026 HPC/AI school, Kobe, Japan, February 2026
+
+
+
+
+ click to expand
+
+You can either:
+
+ * make use of the Fugaku supercomputer for this tutorial, working at the command line,
+ * or [start a Colab notebook](https://colab.research.google.com/github/haddocking/haddock3/blob/main/notebooks/HADDOCK3-antibody-antigen.ipynb){:target="_blank"} (provided you have Google credentials) and follow the instructions in that notebook (simpler).
+
+
+If running on Fugaku, the software and data required for this tutorial have been pre-installed.
+Please connect to Fugaku using your credentials either via ssh connection or from a web browser using OnDemand:
+
+[https://ondemand.fugaku.r-ccs.riken.jp/](https://ondemand.fugaku.r-ccs.riken.jp/){:target="_blank"}
+
+
+If using OnDemand, open then a terminal session, requiring one node and 48 processes and change the working directory to your directory under _/vol0300/data/hp250477/Students/..._.
+
+
+In order to run the tutorial, go into you data directory, then copy and unzip the required data:
+
+
+unzip /vol0300/data/hp250477/Materials/Life_Science/20260202-HADDOCK/HADDOCK3-antibody-antigen.zip
+
+
+This will create the `HADDOCK3-antibody-antigen` directory with all necessary data and scripts and job examples ready for submission to the batch system.
+
+HADDOCK3 has been pre-installed on the compute nodes. To test the installation, first create an interactive session on a node with:
+
+
+
+pjsub \-\-interact \-L \"node=1\" \-L \"rscgrp=int\" \-L \"elapse=2:00:00\" \-\-sparam \"wait-time=600\" \-g hp250477 \-x PJM_LLIO_GFSCACHE=/vol0003:/vol0004
+
+
+Once the session is active, activate HADDOCK3 with:
+
+
+source /vol0300/data/hp250477/Materials/Life_Science/20260202-HADDOCK/haddock3/.venv/bin/activate
+
+
+You can then test that `haddock3` is indeed accessible with:
+
+
+haddock3 -h
+
+
+You should see a small help message explaining how to use the software.
+
+
+
+ View outputexpand_more
+
+
+(haddock3)$ haddock3 -h
+usage: haddock3 [-h] [--restart RESTART] [--extend-run EXTEND_RUN] [--setup]
+ [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-v]
+ recipe
+
+positional arguments:
+ recipe The input recipe file path
+
+optional arguments:
+ -h, --help show this help message and exit
+ --restart RESTART Restart the run from a given step. Previous folders from the
+ selected step onward will be deleted.
+ --extend-run EXTEND_RUN
+ Start a run from a run directory previously prepared with the
+ `haddock3-copy` CLI. Provide the run directory created with
+ `haddock3-copy` CLI.
+ --setup Only setup the run, do not execute
+ --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+ -v, --version show version
+
+
+
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-ljubljana-2026.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-ljubljana-2026.md
new file mode 100644
index 000000000..187810868
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-ljubljana-2026.md
@@ -0,0 +1,69 @@
+### BioExcel Adriatic edition 2026, Ljubljana, Slovenia
+
+You can either:
+
+ * make use of the ADD HPC system for this tutorial, working at the command line,
+ * or [start a Colab notebook](https://colab.research.google.com/github/haddocking/haddock3/blob/main/notebooks/HADDOCK3-antibody-antigen.ipynb){:target="_blank"} (provided you have Google credentials) and follow the instructions in that notebook (simpler).
+
+
+If running on HPC system, the software and data required for this tutorial have been pre-installed.
+Please connect to the HPC system using your credentials either via ssh connection.
+
+In order to run the tutorial, go into you data directory, then copy and unzip the required data:
+
+
+unzip /home/vreys/HADDOCK3-antibody-antigen.zip
+
+
+This will create the `HADDOCK3-antibody-antigen` directory with all necessary data and scripts and job examples ready for submission to the batch system.
+
+HADDOCK3 has been pre-installed on the compute nodes.
+To test the installation, first create an interactive session on a node with:
+
+
+
+salloc --job-name=interactive_haddock3 --partition=amd --nodes=1 --cpus-per-task=8 --time-min=120
+
+
+Once the session is active, activate HADDOCK3 with:
+
+
+source /home/vreys/haddock3/.haddock3-env/bin/activate
+
+
+
+You can then test that `haddock3` is indeed accessible with:
+
+
+haddock3 -h
+
+
+You should see a small help message explaining how to use the software.
+
+
+
+ View outputexpand_more
+
+
+(haddock3)$ haddock3 -h
+usage: haddock3 [-h] [--restart RESTART] [--extend-run EXTEND_RUN] [--setup]
+ [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-v]
+ recipe
+
+positional arguments:
+ recipe The input recipe file path
+
+optional arguments:
+ -h, --help show this help message and exit
+ --restart RESTART Restart the run from a given step. Previous folders from the
+ selected step onward will be deleted.
+ --extend-run EXTEND_RUN
+ Start a run from a run directory previously prepared with the
+ `haddock3-copy` CLI. Provide the run directory created with
+ `haddock3-copy` CLI.
+ --setup Only setup the run, do not execute
+ --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+ -v, --version show version
+
+
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-local.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-local.md
new file mode 100644
index 000000000..c240a391d
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-local.md
@@ -0,0 +1,46 @@
+### Local setup (on your own)
+
+
+
+ click to expand
+
+
+ If you are installing HADDOCK3 on your own system, check the instructions and requirements below.
+
+
+ Note that depending on the system you are installing HADDOCK3 on,
+ you might have to recompile CNS if the provided executable is not working.
+ See the
+
+ CNS troubleshooting section
+
+ on the HADDOCK3 GitHub repository for instructions.
+
+
+
+
Auxiliary software
+
+
+ PyMOL:
+ In this tutorial we will make use of PyMOL for visualization.
+ If not already installed on your system, download and install
+ PyMOL.
+ Note that you can use your favorite visualization software,
+ but instructions are only provided here for PyMOL.
+
+
+
+
diff --git a/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-pula-2025.md b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-pula-2025.md
new file mode 100644
index 000000000..632ac42ac
--- /dev/null
+++ b/education/HADDOCK3/HADDOCK3-antibody-antigen/sections/setup-pula-2025.md
@@ -0,0 +1,65 @@
+### BioExcel summerschool, Pula, Sardinia June 2025
+
+
+
+ click to expand
+
+
+ We will be making use of the local computers for this tutorial.
+ The software and data required for this tutorial have been pre-installed.
+
+
+
+ In order to run the tutorial, go into the
+ HADDOCK3-antibody-antigen directory and activate the HADDOCK3 environment:
+
+ which is an alias for:
+ source ~/BioExcel_SS_2025/HADDOCK/haddock3/.venv/bin/activate
+
+
+
+ You can then test that haddock3 is accessible with:
+
+
+ haddock3 -h
+ You should see a small help message explaining how to use the software.
+
+
+
+ View outputexpand_more
+
+
+ (haddock3)$ haddock3 -h
+ usage: haddock3 [-h] [--restart RESTART] [--extend-run EXTEND_RUN] [--setup]
+ [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-v]
+ recipe
+
+ positional arguments:
+ recipe The input recipe file path
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --restart RESTART Restart the run from a given step. Previous folders from the
+ selected step onward will be deleted.
+ --extend-run EXTEND_RUN
+ Start a run from a run directory previously prepared with the
+ `haddock3-copy` CLI. Provide the run directory created with
+ `haddock3-copy` CLI.
+ --setup Only setup the run, do not execute
+ --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+ -v, --version show version
+
-
-
-
-
- 
-
- 
- 
-
-
-
- 
- 
- 
- 
-
- 
- 
- 
- 
- 
+ 
+ 
+ 
+ 
+