EMSL 60699 - iTops

Project Title: INTEGRATOR, INTEGRAtive TempOral and stRuctural Analysis of protein modules

Description

INTEGRATOR is a robust, multi-stage integrative modeling workflow designed to elucidate the architecture of large, flexible, and multi-subunit protein assemblies that are challenging for traditional structural methods.

Installation

1. Clone the repository

git clone https://code.emsl.pnl.gov/maup214/emsl-60699-itops.git

2. Create and activate a python virtual environment

conda create -n itops python=3.11
conda activate itops

3. Install dependencies

pip install -r requirements.txt

4. Install the package in the editable mode.

pip install -e .

Features

• Create input files of atomistic protein structures for Haddock docking
• Create input files of coarse-grained protein structures for AWSEM-MD optimizations
• Visualize outputs from molecular dynamics optimizations.

Usage

We report a computational model of the three-dimensional structure of the S. cerevisiae INO80 complex using an integrative approach that combines experimental crosslinking mass spectrometry, molecular docking, and molecular dynamics simulations.

Haddock Docking

Requirement:

• Protein structures downloaded from PDB or,
• Inferred protein structures with AlphaFold2

Capability

• Create input files for two structures
• Create input files for a sequence

Creating Haddock input files

An example notebook is given at scripts/create_haddock_inputs.ipynb. This package prvodes three options for creating docking jobs.

1. Dock two protein structures.
2. Docking a protein to a protein complex.
3. Dock a series of structures.

Every docking job requires following to be specfied.

DATA_DIR='docking-protein-protein' 
SUBUNIT_DIR='./SUBUNITS/'   
cl_path='./cross_linking_data.csv' 
subunit_config_path='subunits.yaml'  

• DATA_DIR is the directory for Haddock input files. By default docking-protein-protein will be used as the DATA_DIR and will be automatically created.
• SUBUNIT_DIR is the location where the input protein structures are saved. The user has to store the required files here.
• cl_path is the location of the cross-links .csv file. This is a required file. The protein names in this file should match those in the file corresponding to the subunit_config_path.
• subunit_config_path is the path to a .yaml file that contains the number of residues corresponding to a every protein used for the docking job. See file scripts/subunits.yaml. This is a required file. In this file, you should add the protein name and the corresponding residue numbers for each protein being docked.

The default Haddock settings are given in the docking-protein-protein/docking-protein-protein-cltsel-test-2.cfg. If you need to make changes, please do so by referring to the official documentation https://www.bonvinlab.org/haddock3/index.html.

subunit_dict:
  Arp8: 881
  Act: 375
  Arp4: 489
  Taf14: 244
  Ies4: 116

Dock two protein structures

This is the option for running a new docking job. We will start with two protein structures.

from itops.haddock.utils_run import HaddockRun

A = ['Arp8']
B = 'Act'

run = HaddockRun(DATA_DIR, SUBUNIT_DIR, cl_path, subunit_config_path)
run.create_docking_input(A, B, None)

Once the input files are generated, the docking job can be initiated with,

python run_tests.py --folder docking-protein-protein --file docking-protein-protein-cltsel-test-2-Arp8_Act.cfg

Docking a protein to a protein complex

This is the option to use when you want to dock a third protein B, to an already docked protein complex A1+A2.

# Import HaddockRun
from itops.haddock.utils_run import HaddockRun

# Specify the following parameters.
A  = ['Arp8', 'Act'] # A1 and A2 proteins
B =  'Arp4'
prev_rundir = 'docking-protein-protein/Arp8_Act'

run = HaddockRun(DATA_DIR, SUBUNIT_DIR, cl_path, subunit_config_path)
run.create_docking_input(A, B, prev_rundir)

Docking a sequence of proteins

This option automates the input file creation for docking a sequence of proteins by combiniing the above two options.

proteins = ['Arp8', 'Act','Arp4', 'Taf14', 'Ies4']

for i in [0, 2, 3, 4]:
    if i ==0:
        A = [proteins[i]]
        B = proteins[i+1]

        run = HaddockRun(DATA_DIR, SUBUNIT_DIR, cl_path, subunit_config_path)
        run.create_docking_input(A, B, None)

    else:
        A = proteins[:i]
        B = proteins[i]

        run = HaddockRun(DATA_DIR, SUBUNIT_DIR, cl_path, subunit_config_path)
        prev_rundir = f"docking-protein-protein/{'_'.join(A)}"
        run.create_docking_input(A, B, prev_rundir)

    # code execution has to be puased until the current docking job finishes.

Note that each iteration after the first should wait until the previous iteration finishes.

MD Optimizations

This script create_md_inputs.py and the notebook create_md_inputs.py (under Scripts folder) can be used to generate input files for molecular dynamics (MD) simulations using the ARP8 complex. It automates the creation of main input files, group files, and memory files required for the simulation workflow.

The memory files from known protein structures are created from PDB. The memory files for the flexible components are created from MD.

Usage

Run the script create_md_inputs.py from the command line:

python create_md_inputs.py --pdb_path <PDB_FILE_PATH> --job_name <JOB_NAME> [--cl_data_path <CROSS_LINK_DATA_CSV>] [--subunit_dir <SUBUNIT_DIR>] [--res_dict <RES_DICT>]

Arguments

• --pdb_path (required): Path to the PDB file for the complex.
• --job_name (required): Name of the job/protein complex.
• --cl_data_path: Path to the cross-linking data CSV file (default: assets/cross_linking_data.csv).
• --subunit_dir: Directory containing subunit PDB files (default: assets/SUBUNITS).
• --res_dict: Residue dictionary as a string (e.g., "{'Arp8':881, 'Act':375, 'Arp4':489, 'Taf14':244, 'Ies4':116}"). If not provided, values are loaded from subunits.yaml.

Example

python create_md_inputs.py --pdb_path ./docking-protein-protein/Arp8_Act_Arp4/7_seletopclusts/cluster_1_model_1.pdb --job_name ARP8 --cl_data_path ./cross_linking_data.csv --subunit_dir /home/pana982/emsl-60699-itops/scripts/SUBUNITS

Output

• Main input files for MD simulation
• Memory file
• Groups file -> groups_file_entries.txt
• Cross Link entries -> cross_link_entries.txt

After this step, you have to copy and paste the contents in groups_file_entries.txt and cross_link_entries.txt in the groups.dat file and in the main input file.

Notes

• If --res_dict is not provided, the script will attempt to load residue information from subunits.yaml in the current directory.
• Make sure all required input files and directories exist before running the script.

License

Copyright Battelle Memorial Institute 2026

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Disclaimer

DISCLAIMER This material was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights.

Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.

             PACIFIC NORTHWEST NATIONAL LABORATORY
                          operated by
                            BATTELLE
                            for the
               UNITED STATES DEPARTMENT OF ENERGY
                under Contract DE-AC05-76RL01830