Coordinates to RES

Transforms the coordinates of protein-protein structures in PDB format into the rotation/translation landscape mapping format required by the GRAMMCell pipeline.

Dependencies

• Python: 3.8 or higher

• Python packages:

  • Biopython
  • numpy
  • scipy

• External: iPOT energy scoring program

Installation

git clone https://github.com/VakserLab/iPot.git
cd iPot
make
cd ..
git clone https://gitlab.ku.edu/vakserlab/tools/c2res.git
cd c2res
pip install -r requirements.txt

• The script expects the aace18 executable inside the iPot directory. If not installed, the script runs fully but energy values will be N/A.

Input File Naming

• Model PDB files must follow one of these naming formats, where N is a positive integer.
  • receptor-ligand_N.pdb (Example: receptor-ligand_1.pdb)
  • receptor-ligand_mN.pdb (Example: 1mat-1g81_m1.pdb)
• Files in --model_dir that do not match this format will be skipped and reported at the start of the run.
• Only dimers (two-chain complexes) are supported. Models with any other number of chains will be skipped with a note.

Usage

Example:

python c2res \
  --model_dir /path/to/models \
  --ref_receptor /path/to/receptor.pdb \
  --ref_ligand /path/to/ligand.pdb \
  [--aace_path /path/to/iPot] \
  [--output_dir /path/to/output]

Argument Options

Argument	Required	Description
--model_dir	yes	Directory containing model PDB files
--ref_receptor	yes	Reference receptor PDB (unbound)
--ref_ligand	yes	Reference ligand PDB (unbound)
--aace_path	no	Path to the iPot containing aace18 executable
--output_dir	no	Output directory (default: aligned_complexes)

NOTE: If --aace_path is omitted, the script runs fully but energy values in all output files will be N/A. A warning with the iPOT download URL is printed at the end.

NOTE: Running the script with no arguments prints a usage summary.

Output

File	Description
receptor-ligand.res	GRAMM-format file ready for GRAMMCell input
ligand_alignments_summary.txt	Euler angles, translation, RMSD, and AACE energy per model

Per-model subdirectory (model_ranked_N/):

File	Description
*_aligned_complex.pdb	Full complex aligned to the reference receptor
*_aligned_receptor.pdb	Receptor chain in aligned frame
*_aligned_ligand.pdb	Ligand chain in aligned frame
*_original_receptor.pdb	Receptor chain in original unaligned coordinates
*_original_ligand.pdb	Ligand chain in original unaligned coordinates
ref_ligand_aligned_to_model_N.pdb	Reference ligand transformed to match model ligand position
ref_ligand_transformation.txt	Rotation matrix, translation vector, Euler angles, and RMSD
aace_output_energy.txt	Raw AACE energy output (only when AACE is provided)

Notes

• Dimers only: each model PDB must contain exactly two chains. Models with one chain or more than two chains are skipped with a note.
• Homodimers: if the two chains of a model are identical in sequence, the complex is treated as a homodimer. Chain A is assigned as receptor and chain B as ligand.
• Reference validation: for heterodimers, each model chain is compared against the provided reference structures using 100% sequence identity. If neither chain reaches 100% identity, the model is skipped with a note. Sequence identity scores are printed for every model so the user can verify chain assignments.
• Wrong references: if --ref_receptor and --ref_ligand do not correspond to the proteins in the model files, affected models will be skipped with a note indicating the identity scores found.
• Energy scoring: if --aace_path is not provided, the script runs fully and outputs N/A in all energy columns. A warning is printed at the end with the iPot download URL.

Questions

If you have questions, please send your questions to kamilayounis6@ku.edu.