Integrating AlphaFold and pyDock for Protein–Protein Complex Modeling

This repository accompanies the chapter Modeling Protein–Protein Complexes by Combining pyDock and AlphaFold published in Methods in Molecular Biology (2026), and provides a practical, reproducible implementation of the workflow described.

Warning

Development status — refactoring in progress (approximately 90% complete). The main workflow is available, but some scripts and documentation are still being reviewed and harmonized. Test each stage with a small model set and inspect the generated files before starting production calculations.

The main goal is to demonstrate how artificial intelligence–based modeling (AlphaFold2-Multimer and AlphaFold3) can be combined with energy-based scoring from pyDock to improve the accuracy of protein–protein complex predictions, particularly for challenging cases such as:

• antibody–antigen complexes
• multiprotein assemblies
• weak or transient interactions
• highly flexible proteins

Repository organization

This repository includes an adapted helper for installing ColabFold locally. It does not reproduce the complete local AlphaFold 3 (AF3) installation; instead, it provides a short AF3 overview and links to the separately maintained installation guide. For the complete scientific protocol, refer to the book chapter Modeling Protein–Protein Complexes by Combining pyDock and AlphaFold, published in Methods in Molecular Biology (2026).

For the local AlphaFold 3 installation instructions, refer to AlphaFold3-Conda-Install.

The repository is organized into eight main workflow folders plus a case-study directory. Their numbered names correspond directly to the section numbering and headings used in the Methods in Molecular Biology chapter, making it possible to map each folder to the relevant part of the published protocol:

---

📁 Repository Structure

├── environment.yml
│     Lightweight Conda environment for the Python helper and analysis notebook.
│
├── 2.2.3_ColabFold_on_a_Local_Machine_with_LocalColabFold/
│     Adapted LocalColabFold installer, requirements, activation notes,
│     troubleshooting and upstream attribution.
│
├── 2.2.4_AlphaFold3/
│     Brief overview of AlphaFold Server and local AF3, including links to the
│     official parameter request and the external Conda installation guide.
│
├── 2.3_pyDock_Scoring/
│     Guide for obtaining, configuring and verifying the licensed pyDock3
│     distribution used for binding-energy scoring in this repository.
│
├── 2.4_SCWRL/
│     Installation and pyDock3 configuration of the bundled SCWRL3 package
│     used to rebuild incomplete protein side chains when required.
│
├── 2.5_Greasy/
│     Installation and usage guide for the BSC Greasy task scheduler, adapted
│     to the parallel relaxation and pyDock workflows in this repository.
│
├── 3.1_Generating_3D_Models_for_Protein_Protein_Complexes_with_AlphaFold/
│     Scripts for generating multiple conformations with ColabFold (AlphaFold2-Multimer)
│     and models generated by AlphaFold 3, plus an optional helper to relax
│     AlphaFold2 PDB models before pyDock scoring.
│
├── 3.3.2_Computing_pyDock_Scores_for_a_Set_of_Complexes/
│     Template (.ini) generation, bindEy execution, pyDock3-controlled
│     side-chain reconstruction with SCWRL3, and pyDock energy tables.
│
├── 3.4_Combined_Model_Confidence_and_pyDock_Score/
│     Jupyter Notebook Analysis_protocol.ipynb for integrating AlphaFold
│     confidence metrics (AF-MC) with pyDock energy scores, including parsed
│     energy tables and extracted AF2/AF3 metadata. The notebook computes
│     z-scores for both scoring functions, generates combined AF–pyDock
│     rankings, and outputs the final prioritized model list.
│
└── 4_Case_Studies/
    ├── 2FJG/
    │   └── 2FJG.tar.gz
    └── 4POU/
        └── 4POU.tar.gz

Each workflow section provides the relevant scripts or usage notes. The two case-study archives contain precomputed AlphaFold2-Multimer and local AlphaFold3 model-generation outputs. Extract the selected archive inside its case directory before running the downstream pyDock scoring and combined analysis workflows. pyDock .ene files and Analysis/ results are generated locally and are not included in the archives.

---

Lightweight Python environment

The root environment.yml installs only the Python dependencies needed by cif_to_pdb.py and Analysis_protocol.ipynb. It does not install AlphaFold2, AlphaFold3, pyDock, SCWRL or Greasy; those programs retain their own installation procedures. Consequently, users preparing AF3 Server files or analysing supported AF3 and supplied case-study outputs do not need to install AlphaFold2 merely to use the Python tools.

The default creates an independent environment:

conda env create --file environment.yml
conda activate af-pydock-analysis

The environment name and dependency constraints are visible and editable in the YAML. A different name can also be selected without editing it:

conda env create --name my-analysis-env --file environment.yml

Users who deliberately prefer an existing environment can apply the same YAML to it. Before doing so, review the python= constraint in environment.yml and adjust it if the existing software requires another compatible Python version. For example:

conda env update --name Alphafold3 --file environment.yml

The command-line name overrides the default name in the YAML. Do not add --prune: packages specific to the existing environment are not listed in this repository file. Updating an existing scientific environment may change its dependency resolution, so the independent environment remains the safer default. See the section 3.4 README for kernel selection and execution.

---

🛠 2.2.3 Installing ColabFold locally

This section contains install_colabbatch_linux.sh, an adapted version of the Linux installer from YoshitakaMo/localcolabfold. It creates or reuses a Conda environment, installs the ColabFold/AlphaFold2 dependencies and downloads the model parameters.

The installer modifies a Conda environment and downloads substantial external data. Read 2.2.3_README.md before running it, especially the installation-location, existing-environment and reproducibility warnings.

---

🧬 2.2.4 AlphaFold 3 access and installation

AlphaFold 3 can be accessed through AlphaFold Server or installed locally after requesting the model parameters from Google DeepMind. The local installation is documented in the external AlphaFold3-Conda-Install guide rather than duplicated here.

See 2.2.4_README.md for the supported workflow routes, parameter access and license distinctions.

---

⚡ 2.3 pyDock scoring

pyDock is developed by the Protein Interactions and Docking Group at the Barcelona Supercomputing Center. The complete package supports protein–protein docking, but this repository uses pyDock3 only to score existing AlphaFold complex models through its bindEy module. The software must be requested separately and is not redistributed with this repository.

See 2.3_README.md for access and license information, 32-bit compatibility requirements, PYDOCK configuration, verification and the repository-specific .ini-to-.ene scoring workflow.

---

🧩 2.4 SCWRL side-chain reconstruction

pyDock3 uses SCWRL3 when it needs to rebuild incomplete side chains in an input structure. The licensed pyDock3 distribution described in this repository includes scwrl3_lin.tar.gz; after installation, the resulting scwrl3 executable must be declared in pyDock's etc/pydock.conf file. SCWRL4 is a separate, newer program and is not treated as a drop-in replacement for SCWRL3 in the pyDock3 workflow.

See 2.4_README.md for the bundled installation procedure, configuration, compatibility notes and upstream attribution.

---

⚙️ 2.5 Greasy task scheduler

Greasy, developed by the HPC User Support Team at the Barcelona Supercomputing Center, executes independent commands concurrently from a text task file. This repository uses it for optional AlphaFold2 relaxation and parallel pyDock bindEy calculations.

See 2.5_README.md for the chapter-compatible GREASY_2.2 installation layout, environment variables, verification, repository-specific task files, attribution and license information.

---

🧬 3.1 Generating Diverse Complex Models with AlphaFold

This folder contains:

• Workflows for configurable AlphaFold2-Multimer versions, using v2 and v3 by default while retaining v1 for legacy reproducibility, with:

  • increased recycles
  • dropout during inference
  • saving all intermediate recycles
  • GPU Amber relaxation of the final ranked models

• Optional post-processing of saved AlphaFold2 recycle PDB models with colabfold_relax when a complete relaxed recycle ensemble is required.

• Scripts using a local ColabFold installation for rapid predictions without downloading the full AlphaFold database set.

• AlphaFold3 examples (server-based and local execution), including CIF-to-PDB conversion.

• Configurable sequence inputs for heterodimers and other multichain complexes.

The main helper scripts are run_alphafold2_multimer.sh, relax_alphafold2_models.sh, run_alphafold3.sh, and cif_to_pdb.py.

The aim is to generate >100 structural models per complex, which is essential for the subsequent scoring stage.

---

⚡ 3.3.2 pyDock Energy Scoring

This folder includes:

• Automatic generation of all required *.ini files.

• Parallel execution of bindEy via Greasy.

• Reconstruction of incomplete side chains by pyDock3 using its configured SCWRL3 executable when required.

• Example *.ene energy tables including:

  • Electrostatics (ELE)
  • Desolvation (DESOLV)
  • Van der Waals (VDW)
  • pyDock-0.1VDW (the native .ene Total score)
  • pyDock-1VDW (recalculated with the full VDW contribution)

The VHH–RNase A (PDB 4POU) complex is provided as an illustrative example.

---

🔗 3.4. Integrating AlphaFold Confidence and pyDock Energies

This section combines AlphaFold model confidence (AF-MC = 0.8·ipTM + 0.2·pTM) with pyDock energies using z-score normalization to prioritize the most promising complex models.

Included:

• Extraction of pTM and ipTM from AF2 log.txt or AF3 *_summary_confidences.json, followed by calculation of AF-MC.

• Computation of:

  Z = (X − μ) / σ
  

• Calculation of the chapter metrics:

  • Z_AF-MC
  • Z_pyDock-0.1VDW
  • Z_pyDock-1VDW
  • Z_AF/pyDock-1VDW = Z_AF-MC – Z_pyDock-1VDW

• Final ranking and filtering of top predictions.

When AF-MC < 0.8, the protocol recommends complementing AlphaFold predictions with classical pyDock docking, following the decision tree shown in Fig. 1 of the chapter.

This repository supports the part of the protocol highlighted in the red box:

• Generation of AlphaFold2-Multimer models using ColabFold (optional use AlphaFold3 server)
• Extraction of ipTM and pTM
• Computation of Model Confidence (AF-MC)
• Calculation of pyDock energy scoring for AF2/AF3-generated complexes

The docking stage starting from monomeric or unbound structures is outside the scope of this repository. If docking poses are needed, they can be generated via the pyDockWEB server:

👉 https://life.bsc.es/pid/pydockweb

---

📘 Case Studies Included

1. VHH–RNase A (4POU) → AF2 rank 1 fails; pyDock identifies an acceptable model.
2. Fab–VEGF (2FJG) → Additional case with precomputed AF2/AF3 model outputs.

The case-study archives include precomputed AlphaFold2-Multimer and AlphaFold3 outputs so users can test the downstream pyDock scoring and z-score analysis without recalculating the most computationally expensive step.

---

🛠 Requirements

• Python 3.12 by default for the lightweight helper and notebook environment
• GNU Bash and wget for the optional ColabFold installer
• pyDock3, requested and installed separately
• SCWRL3, when pyDock3 needs to rebuild incomplete side chains
• Greasy (for task parallelization)
• AlphaFold2-Multimer / ColabFold / AlphaFold3 (depending on workflow)
• colabfold_relax for the optional AF2 relaxation step

---

🚀 Quick Installation

git clone https://github.com/PyDock/AF_pyDock/
cd AF_pyDock

Each internal folder includes its own usage notes and example scripts.

For software setup and workflow requirements, start with:

• 2.2.3_README.md for ColabFold;
• 2.2.4_README.md for AlphaFold Server and local AF3 installation links;
• 2.3_README.md for obtaining and configuring pyDock3;
• 2.4_README.md for installing the SCWRL3 archive bundled with pyDock3;
• 2.5_README.md for Greasy installation and integration with the parallel repository workflows.
• 3.1_README.md for generating and preparing AF2 and AF3 models;
• 3.3.2_README.md for generating pyDock configurations and energy tables for a set of models;
• 3.4_README.md for combining AlphaFold confidence with pyDock energies in the analysis notebook.

---

📄 Citation

If you use this repository, please cite:

Rodríguez-Lumbreras LA, Monteagudo V, Fernández-Recio J. Modeling Protein–Protein Complexes by Combining pyDock and AlphaFold. Methods in Molecular Biology (2026).

---

🤝 Contributing

Contributions, suggestions, and pull requests are welcome.

---

📧 Contact

For questions related to the protocol or pyDock software:

Juan Fernández-Recio Group