Subpex

<h1 align="center">SubPEx</h1> <h4 align="center">Generate a diverse ensemble of protein conformations for use in ensemble docking</h4> <h4 align="center" style="padding-bottom: 0.5em;"><a href="https://durrantlab.github.io/subpex/">Documentation</a></h4> <p align="center"> <a href="https://github.com/durrantlab/subpex/actions/workflows/build.yml"> <img src="https://github.com/durrantlab/subpex/actions/workflows/build.yml/badge.svg" alt="Build Status "> </a> <a href="https://codecov.io/gh/durrantlab/subpex"> <img src="https://codecov.io/gh/durrantlab/subpex/graph/badge.svg?token=784B2H5JW0" alt="codecov"> </a> <a href="https://github.com/durrantlab/subpex/releases"> <img src="https://img.shields.io/github/v/release/durrantlab/subpex" alt="GitHub release (latest by date)"> </a> <a href="https://github.com/durrantlab/subpex/blob/main/LICENSE.md" target="_blank"> <img src="https://img.shields.io/github/license/durrantlab/subpex" alt="License"> </a> <a href="https://github.com/durrantlab/subpex/" target="_blank"> <img src="https://img.shields.io/github/repo-size/durrantlab/subpex" alt="GitHub repo size"> </a> <a href="https://github.com/psf/black" target="_blank"> <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Black style"> </a> <a href="https://github.com/astral-sh/ruff" target="_blank"> <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Black style"> </a> </p>

What is it?

Subpocket explorer (SubPEx) is a tool that uses weighted ensemble (WE) path sampling, as implemented in WESTPA, to maximize pocket conformational search. SubPEx's goal is to produce a diverse ensemble of protein conformations for use in ensemble docking.

As with any WE implementation, SubPEx uses a progress coordinate to focus computational power on sampling phase space. The available progress coordinates are:

• composite RMSD (a linear combination of backbone and pocket heavy-atom RMSD)
• pocket heavy atoms RMSD
• backbone RMSD
• Jaccard distance of pocket volumes (jd)

We highly recommend using the composite RMSD progress coordinate. Use of other coordinates may have inadequate performance.

Installation

The first step is to download, clone, or copy the repository.

git clone git@github.com:durrantlab/subpex.git

The repository includes lock files to build the same environment we use for development. Simply run this command (after ensuring you have Makefile tools installed):

make environment

To activate the new conda environment, run:

conda activate subpex-dev

Some users may wish to create their own environments or to use an existing WESTPA environment. If so, install the following packages so SubPEx can calculate the progress coordinate:

• loguru
• mdanalysis
• westpa
• numpy
• scipy
• scikit-learn
• jinja2
• pydantic
• pydantic-settings

Usage

TODO: Needs to be updated to new version

Users should take advantage of our autobuilder (wizard.py) to setup their SubPEx simulations. In some cases, however, users may wish to manually set up their simulations by editing key SubPEx/WESTPA files. This approach is not officially supported, but we provide the below instructions for advanced/adventurous users.

Link your preliminary, equilibrated simulation

1. SubPEx assumes you have already run preliminary simulations to equilibrate your system. Soft link or copy your preliminary, equilibrated trajectories and necessary restart files to the ./reference/ directory. Rename the files mol with the appropriate extension. (Note that ./reference/ already contains the namd.md.conf and amber.prod_npt.in template files, which SubPEX uses to interface with the NAMD and AMBER MD engines, respectively.)

   • If using NAMD, soft link the .dcd file of the final equilibration run. NAMD requires other files to restart simulations as well. Be sure to soft link the .xsc, .coor, and .inpcrd files as well. Remember the .prmtop file as well.

   ln -s /file/path/to/simulation/my_namd_file.dcd /WEST/ROOT/reference/mol.dcd
   ln -s /file/path/to/simulation/my_namd_file.xsc /WEST/ROOT/reference/mol.xsc
   ln -s /file/path/to/simulation/my_namd_file.coor /WEST/ROOT/reference/mol.coor
   ln -s /file/path/to/simulation/my_namd_file.inpcrd /WEST/ROOT/reference/mol.inpcrd
   ln -s /file/path/to/simulation/my_namd_file.prmtop /WEST/ROOT/reference/mol.prmtop
   

   • If using Amber, the filetype that works with the SubPEx algorithm is .nc. You need to soft link the .rst file of the final equilibration run as well. Remember the .prmtop file as well.

   ln -s /file/path/to/trajectory/my_amber_file.nc /WEST/ROOT/reference/mol.nc
   ln -s /file/path/to/trajectory/my_amber_file.rst /WEST/ROOT/reference/mol.rst
   ln -s /file/path/to/trajectory/my_amber_file.prmtop /WEST/ROOT/reference/mol.prmtop
   

2. Extract the last frame of the preliminary, equilibrated trajectory as a pdb file with your preferred molecular analysis program (e.g., VMD). Soft link that to the ./reference/ directory as well, and name the link last_frame.pdb.

   ln -s /file/path/to/last/frame/my_last_frame.pdb /WEST/ROOT/reference/last_frame.pdb
   

Edit the west.cfg file

1. Edit the following parameters in the west.cfg file:
   • the directory portion of the path variables, though the basename itself should not change. NOTE: Be sure to use full (not relative) paths.
   • reference: the PDB file that will be used in EVERY SINGLE progress-coordinate calculation (the last frame of the preliminary, equilibrated simulation mentioned above).
   • selection_file: path to a text file that will contain the pocket selection string (MDAnalysis selection notation). This file will be automatically generated in a subsequent step, but specify its future path here.
   • reference_fop: path to an xyz file that will contain the field of points needed to calculate the jd progress coordinate. This file is also useful for visualizing the selected pocket. It will be automatically generated in a subsequent step.
   • west_home: home directory of the SubPEx run. You'll most likely want to use the same directory that contains the west.cfg file itself.
   • topology: topology file needed for the MD simulations (likely the same topology file used in the preliminary, equilibrated simulations).
   • the progress coordinate (pcoord) to use.
   • composite: composite RMSD (recommended)
   • prmsd: pocket heavy atoms RMSD (not officially supported)
   • bb: backbone RMSD (not officially supported)
   • jd: Jaccard distance (not officially supported)
   • the auxiliary data (auxdata) to calculate and save.
   • composite: composite RMSD
   • prmsd: pocket heavy atoms RMSD*
   • pvol: pocket volume (requires jd too)
   • bb: backbone RMSD
   • rog: radius of gyration of the pocket (requires jd too)
   • jd: Jaccard distance
   • make sure that the WESTPA progress coordinate and auxdata match the SubPEx ones (these sections are both found in the west.cfg file).
   • The WESTPA progress coordinate is specified at west -> data -> datasets, subpex -> pcoord, and in adaptive_binning/adaptive.py
   • The WESTPA auxiliary data is at west -> executable -> datasets
   • The SubPEx progress coordinate is at subpex -> pcoord
   • The SubPEx auxiliary data is at subpex -> auxdata

Define the pocket to sample

1. You must define the location of the binding pocket you wish to sample. Find the coordinates of the pocket center and radius using the extracted last frame.
   • Visual inspection is often useful at this step. You might first create a PDB file with a CA dummy atom. Load that together with the extracted last frame of the previous step into your preferred visualization software (ChimeraX, PyMol, VMD, etc.). Then manually move the dummy atom to the pocket center and measure its location. Similarly, use the dummy atom to determine the radius from that center required to encompass the pocket of interest.
2. Return to the west.cfg file and edit the following parameters:

• center: the pocket center
• radius: the pocket radius
• resolution: the distance between adjacent pocket-filling grid points (especially important if using the jd progress coordinate)

3. Run python westpa_scripts/get_reference_fop.py west.cfg. This script will generate the files specified by the selection_file and reference_fop parameters in the west.cfg file.
4. Visually inspect the pocket field of points (fop) and/or the selection string (MDAnalysis selection syntax).

• Ensure that the points in the fop (reference_fop) file entirely fill the pocket of interest.
• Ensure that the residues (selection_file) truly line the pocket of interest.
• Note that the popular molecular visualization program VMD can load xyz files and select residues.

5. After visual inspection, adjust the west.cfg file (center, radius, and resolution parameters) and re-run the westpa_scripts/get_reference_fop.py script. Continue to recalculate the pocket as needed to fine-tune your pocket.

Setup the progress coordinate calculations

1. Update the variables in the adaptive_binning/adaptive.py file to indicate the number of walkers per bin