XModeScore Usage & Tutorial

XModeScore Usage & Tutorial

The qbphenix Command Line arguments cover various standard functions and features available within the tool box. If you are looking for X-ray refinement tools and options, please see the X-ray Refinement Manual. Otherwise, the documentation below will provide you with a starting point.

(If you would like to be notified when these other functions are documented, email support@quantumbioinc.com to register your interest).

Method Summary

An understanding of the protein:ligand complex structure is crucial for obtaining meaningful results in structure-guided drug discovery and structure-based drug discovery. Unfortunately, due to well-known limitations of conventional X-ray crystallography, tautomer and protomer modes are often difficult to establish. QuantumBio’s Phenix/DivCon plugin combines linear-scaling, semi-empirical, quantum mechanics (QM) with the popular Phenix crystallographic refinement engine in order to derive models that exhibit greater chemical accuracy. This plugin has been shown to be exquisitely sensitive to the protonation and rotameric modes chosen by the crystallographer or modeler. XModeScore is built on this solid foundation and uses a combination of energetic strain (e.g. ligand strain) along with a rigorous statistical analysis of the difference electron density distribution (ZDD) in order to determine the tautomer, protomer, and rotamer which best fits the density and correctly captures the chemistry within the active site. The key publication you should review is available for free download at the following reference:

  • Borbulevych, O., Martin, R. I., Tickle, I. J., & Westerhoff, L. M. (2016). XModeScore: a novel method for accurate protonation/tautomer-state determination using quantum-mechanically driven macromolecular X-ray crystallographic refinement. Acta Cryst. D72, 586-598 [Doi:10.1107/S2059798316002837], 1–13. http://doi.org/10.1107/S2059798316002837

Unlike conventional, energy based scoring functions used to determine binding affinity, XModeScore uses a combination of computational methods and X-ray crystallographic data to determine bound protomers/tautomers, rotomers, flip-states, ligand binding modes, and even fragment positions within the active site. Since the method directly uses experimental density, the results are considered experimental in nature. In fact, the method is currently being patented as a diagnostic for X-ray data!

General Usage Notes:

  • Prior to using XModeScore, you should familiarize yourself with the tutorials available for Phenix/DivCon. The tutorials provided below assumes this knowlege.
  • Modern X-ray refinement using “all atom” methods such as DivCon and XModeScore require full ligand and protein protonation.
  • When using the “xmodestats.sh” support script to compare the results obtained from several different refinement engines, it is crucial that all starting structures are identically prepared – including all protons and so on.
  • Analyses based upon X-ray refinement data – such as XModeScore – will provide you with the configuration of the molecule within the crystal at the pH and temperature at which the molecule was crystalized.
  • In addition to requiring a proper install of Phenix 1.10, currently XModeScore also requires that the MOE platform is available and in your path.

Be sure to also type the following command at the command line in order to read updated descriptions of each command line and its available arguments:

     /path/to/DivConSuite/bin/qbphenix --help

XModeScore Specific Output Explained:

Upon completion of the XModeScore process, a table will be generated by the XModeSore method which summarizes the characteristics associated with each provided or generated structural conformer or Species (e.g. protomer/tautomer, docked pose, rotamer, etcetera). This table is largely broken down into a list of structures or “Species” in the left-most column followed by columns for Residue [of the Selection], Strain Energy, Real Space Correlation Coefficient [RSCC], Z-score of the Difference Density [ZDD], XModeScore, and several interaction energies if they are calculated: [QM] Interaction energy, MOE Interaction energy, and MOE binding affinity score. This table is presented here:

Species Residue Strain Energy RSCC ZDD XModeScore Interaction MOE Interaction MOE Score
0_0_0_0 /A/18K/299// 2.31 0.944 4.31 2.64 0 -75.1 -6.81
1_1_2_0 /A/18K/299// 2.46 0.943 4.89 1.39 0 -55.4 -6.87
1_0_1_0 /A/18K/299// 4.9 0.941 5.05 0.184 0 -28.7 -7.1
2_0_1_0 /A/18K/299// 4.25 0.941 5.41 -0.325 0 -11.5 -7.13
1_0_0_0 /A/18K/299// 10.1 0.942 4.89 -1.31 0 -88.0 -6.91
1_0_0_0 /A/18K/299// 10.1 0.942 4.89 -1.31 0 -88.0 -6.91

Note: These terms are discussed in detail in Borbulevych, O. et al. Acta Cryst (2016). D72, 586-598 and are summarized below.

  • Strain Energy (measured in PM6 kcal/mol): the lower the value, the lower the conformational strain of the selected residue where the conformational strain is calculated as the difference in single-point energy between the bound conformation and the unbound/optimized conformation.
  • Real Space Correlation Coefficient [RSCC]: a value between 0 and 1 where the higher the value, the greater similarity between the electron density map calculated from the model and the electron density map calculated from the experimental data (note: this is a conventional metric which does not properly distinguish between precision and accuracy – which explains why we generally do not see a lot of variation).
  • Z-score of the Difference Density [ZDD]: analogous to strain, the lower the value, the better agreement between the model (i.e. refined coordinates of the selected residue) and the experimental density. Since this metric is based on the difference density, it is a proper measure of the accuracy of the model.
  • XModeScore: the patent-pending XModeScore method joins Strain with ZDD to score each refined conformation of the selected residue where the higher the value, the more likely the particular species is the one actually found in the crystal. It should be noted that one can sometimes observe two or more conformers with similar XModeScores which would suggest some disorder in the structure. It should also be noted that XModeScore is a “normalized score” in the sense that the score of each conformer is based on a comparison between the conformers in the set and therefore the score should not be thought of as “transferable” between different simulation cycles.
  • Interaction Energy Scores (various): finally, the table is filled out with additional target:residue interaction energy values and scores which could be provided by DivCon, MOE, or other tools as they become available. The column “Interaction” is itself related to the QM interaction energy calculation available in DivCon. The MOE Interaction and MOEScore are MOE-based values which calculate the energy and binding affinity respectively.

Back to Top

Tutorial #1: XModeScore executed on PDBid:1OPK

XModeScore is the fundemental analysis tool which brings together strain with difference density in order to determine the correct protonation state, tautomer state, rotamer state, and flip state of the molecule within the crystal structure. The XModeScore method is fully encapsulated in the qbphenix script therefore you do not need to manage any of the steps outside of the execution of this script.

To download final input/output for this tutorial, click here.

  1. Source the proper Phenix and DivCon versions (assuming Bash shell): 
    source /path/to/phenix-1.10.1-xxxx/phenix_env.sh
source /path/to/DivConDiscoverySuite-7.x.x-bxxxx/etc/qbenv.sh
  2. Create a clean, empty directory and change directory into it.
  3. Execute phenix.ready_set to prepare and protonate structure: 
    qbphenix --pdbID 1OPK --XModeScore --protonation MOE --selection "chain A resname 18K resid 299" --np 20 --dir test1
Switch Value Description
–pdbID 1OPK Automatically download coordinates and structure factors for 1OPK directly from PDB
–protonation MOE Protonate the structure using MOE (i.e. Protonate3D)
–XModeScore Execute MOE-generated protomer/tautomer exploration using XModeScore
–dir test1 (optional) Run within subdirectory named ‘test1’ where ‘test1’ is created at run time
–nproc 16 Set the number of threads for the run.

The calculation will perform 4 refinements in parallel with the various protonation states generated and upon conclusion, the following table will be produced and printed to the screen:

Species Residue Strain Energy RSCC ZDD XModeScore Interaction MOE Interaction MOE Score
0_0_0_0 /A/18K/299// 2.31 0.944 4.31 2.64 0 -75.1 -6.81
1_1_2_0 /A/18K/299// 2.46 0.943 4.89 1.39 0 -55.4 -6.87
1_0_1_0 /A/18K/299// 4.9 0.941 5.05 0.184 0 -28.7 -7.1
2_0_1_0 /A/18K/299// 4.25 0.941 5.41 -0.325 0 -11.5 -7.13
1_0_0_0 /A/18K/299// 10.1 0.942 4.89 -1.31 0 -88.0 -6.91
2_0_2_0 /A/18K/299// 7.99 0.94 5.86 -2.58 0 -63.2 -6.87

Back to Top

 

Tutorial 2a: XModeScore on AZM PDBid:3HS4

In this example, XModeScore is used to run on the PDB file corresponding to the RCSB PDBid 3HS4. The qbphenix script will automatically download the corresponding PDB structure (in this case, 3HS4) along with the structure factor data and run the refinement.

To download final input/output for this tutorial, click here.

  1. Source the proper Phenix and DivCon versions (assuming Bash shell): 
    source /path/to/phenix-1.10.1-xxxx/phenix_env.sh
source /path/to/DivConDiscoverySuite/etc/qbenv.sh
  2. Create a clean, empty directory and change directory into it.
  3. Execute phenix.ready_set to prepare and protonate structure: 
    qbphenix --pdbID 3HS4 --XModeScore --protonation MOE --nproc 20
    --dir xmodeData --selection "chain A resname AZM resid 701" --protPH 9.0
    --generateTautomers divcon --protomers "-1..0"
Switch Value Description
–pdbID 3HS4 Automatically download coordinates and structure factors for 3HS4 directly from the RCSB and run it.
-XModeScore Execute XModeScore
–protonation MOE Protonate the structure using MOE (i.e. Protonate3D)
–generateTautomers divcon Generate tautomers/protomers using built -in function in DivConDiscoverySuite
–protomers “-1..0” Generate tautomers for the base state as well as possible tautomers for -1 and +1 protonation states. Other common settings:
–protomers 0  (default) generate tautomers only
–protomers -1  generate tautomers for a negative (-1) protonation state only
–protpH 9.0 Protonate the structure using MOE (i.e. Protonate3D) using the crystal pH of 9.0
–dir xmodeData (optional) Run within subdirectory named ‘test1’ where ‘xmodeData’ is created at run time
–nproc 16 Set the number of threads for the run.

The calculation will perform 4 refinements in parallel with the various protonation states generated and upon conclusion, the following table will be produced and printed to the screen:

Species Residue Strain Energy RSCC ZDD XModeScore1 Interaction
1_0_0_-1 /A/AZM/701// 7.65 0.986 14.2 2.9 0
1_0_2_-1 /A/AZM/701// 10.8 0.985 17.5 0.44 0
0_0_0_0 /A/AZM/701// 9.68 0.981 19.3 0.196 0
0_0_0_-1 /A/AZM/701// 10.0 0.977 21.2 -0.665 0
1_0_1_0 /A/AZM/701// 15.0 0.978 21.7 -2.87 0

Back to Top

 

Tutorial 2b: XModeScore on user-provided AZM 3HS4.pdb file

In this example, XModeScore is executed on a file which has already been protonated elsewhere (such as in MOE or Maestro) and therefore we will skip the protonation. This is a good tutorial in the event that you already have a structure preparation toolbox you feel comfortable with and you wish to continue to use it. MOE is still required for the XModeScore protonation after the tautomers/protomers are generated, but MOE is not required during the initial protonation process.

  1. Source the proper Phenix and DivCon versions (assuming Bash shell): 
    source /path/to/phenix-1.10.1-xxxx/phenix_env.sh
source /path/to/DivConDiscoverySuite/etc/qbenv.sh
  2. Create a clean, empty directory and change directory into it.
  3. Execute phenix.ready_set to prepare and protonate structure: 
    qbphenix --pdbFile 3HS4.pdb --dataFile  3HS4.mtz --cifFile  3HS4.cif
    --XModeScore --protonation skip --nproc 20
    --dir xmodeData --selection "chain A resname AZM resid 701" --protPH 9.0
    --generateTautomers divcon --protomers "-1..0"
Switch Value Description
–pdbFile 3HS4.pdb Use a user-provided PDB file named 3HS4.pdb.
–dataFile 3HS4.mtz Use a user-provided MTZ file named 3HS4.mtz.
–cifFile 3HS4.pdb Use a user-provided ligand CIF file named 3HS4.cif.
–XModeScore Execute XModeScore on the above noted files.
–protonation skip Do not run an initial protonation. You may use the MOE option as noted above if you prefer. WARNING: using option skip assumes that you have already prepared the file outside of the call to qbphenix and you are running the calculation on this prepared file. If you have not prepared it correctly, then the calculation will fail.
–generateTautomers divcon Generate tautomers/protomers using built -in function in DivConDiscoverySuite
–protomers “-1..0” Generate tautomers for the base state as well as possible tautomers for -1 and +1 protonation states. Other common settings:
–protomers 0  (default) generate tautomers only
–protomers -1  generate tautomers for a negative (-1) protonation state only
–protpH 9.0 Protonate the structure using MOE (i.e. Protonate3D) using the crystal pH of 9.0
–dir xmodeData (optional) Run within subdirectory named ‘test1’ where ‘xmodeData’ is created at run time
–nproc 16 Set the number of threads for the run.

The calculation will perform 4 refinements in parallel with the various protonation states generated and upon conclusion, the following table will be produced and printed to the screen:

Species Residue Strain Energy RSCC ZDD XModeScore1 Interaction
1_0_0_-1 /A/AZM/701// 7.65 0.986 14.2 2.9 0
1_0_2_-1 /A/AZM/701// 10.8 0.985 17.5 0.44 0
0_0_0_0 /A/AZM/701// 9.68 0.981 19.3 0.196 0
0_0_0_-1 /A/AZM/701// 10.0 0.977 21.2 -0.665 0
1_0_1_0 /A/AZM/701// 15.0 0.978 21.7 -2.87 0

Back to Top

 

Tutorial 2c: XModeScore on pre-generated files

In this example, we will run it on a directory full of pdb files which have already been protonated and prepared elsewhere (such as in MOE or Maestro) and therefore we will skip the protonation and tautomer generation. This is a particularly useful scenario in fragment-based screening.

  1. Source the proper Phenix and DivCon versions (assuming Bash shell): 
    source /path/to/DivConDiscoverySuite/etc/qbenv.sh
  2. Create a clean, empty directory and change directory into it.
  3. Execute phenix.ready_set to prepare and protonate structure: 
    qbphenix --jobID 3HS4 --XModeScore preparedDir --protonation skip --nproc 20
    --dir xmodeData --selection "chain A resname AZM resid 701" --protPH 9.0
    --generateTautomers skip --makeCIF MOE
Switch Value Description
–jobID 3HS4 Use a user-provided PDB file named 3HS4.pdb and corresponding user-provided structure factor file named 3HS4.sf (or mtz). Note: since this example takes a command line argument for the XModeScore, only the MTZ or SF file is used.
–XModeScore preparedDir Execute XModeScore on all of the files as user-provided within the directory named preparedDir.
–protonation skip Do not run an initial protonation. You may use the MOE option as noted above if you prefer. WARNING: using option skip assumes that you have already prepared the file outside of the call to qbphenix and you are running the calculation on this prepared file. If you have not prepared the file correctly, then the calculation will fail.
–generateTautomers skip Do not generate any tautomers/protomers automatically and instead just use the files provided in the xmodeData directory as provided. WARNING: using option skip assumes that you have already prepared the files outside of the call to qbphenix and you are running the calculation on this prepared files. If you have not prepared the files correctly, then the calculation will fail.
–protpH 9.0 Protonate the structure using MOE (i.e. Protonate3D) using the crystal pH of 9.0
–dir xmodeData (optional) Run within subdirectory named ‘test1’ where ‘xmodeData’ is created at run time
–nproc 16 Set the number of threads for the run.
–makeCIF MOE (Optional) Use MOE instead of elbow to generate the CIF files for all ligand states within the protonatedFiles directory.

The calculation will perform 4 refinements in parallel with the various protonation states generated and upon conclusion, the following table will be produced and printed to the screen:

Species Residue Strain Energy RSCC ZDD XModeScore1 Interaction
1_0_0_-1 /A/AZM/701// 7.65 0.986 14.2 2.9 0
1_0_2_-1 /A/AZM/701// 10.8 0.985 17.5 0.44 0
0_0_0_0 /A/AZM/701// 9.68 0.981 19.3 0.196 0
0_0_0_-1 /A/AZM/701// 10.0 0.977 21.2 -0.665 0
1_0_1_0 /A/AZM/701// 15.0 0.978 21.7 -2.87 0

Back to Top

 

Tutorial #3: XModeScore on Refmac/Buster structures

The QuantumBio-provided script called xmodestats.sh is available within the DivConDiscoverySuite-bxxxx/scripts directory. This script can be executed in order to call XModeScore on directories and data generated by alternate X-ray refinement engines such as Phenix, Refmac, and Buster. The following workflow will use the qbphenix script in order to generate the input which should then be used in subsequent calls to these alternate X-ray refinement engines. Using consistent input files will limit artifactual variability due to differing inputs, settings, protonation states, CIF’s, and so on.

  1. Source the proper Phenix and DivCon versions (assuming Bash shell): 
    source /path/to/phenix-1.10.1-xxxx/phenix_env.sh
source /path/to/DivConDiscoverySuite/etc/qbenv.sh
  2. Create a clean, empty directory and change directory into it.
  3. Assume a typical case when there are three input files: 1TOW.pdb (unprotonated PDB), 1TOW.mtz and 1TOW.cif (which in this example only partial description of the ligand structure e.g. no hydrogens). The CIF is optional and if not given then the correct CIF will be generated at the end of the qbphenix run (see Step 3). 
    qbphenix --jobID 1TOW --protonation MOE --autobuildMOE
    --selection "chain A resname CRZ resid 501" --nproc 8
    Switch Value Description
    –jobID 1TOW Uses the 1TOW.pdb, 1TOW.mtz, and 1TOW.cif [if available] found within the current working directory.
    –protonation MOE Protonate the structure using MOE (i.e. Protonate3D)
    –autobuildMOE Uses MOE to prepare the structure including rebuilding side chains and other factors.
    –nproc 8 Set the number of threads for the run.
  4. Execute the command ./run to run the Phenix/Divcon refinement.
  5. (Optional) If you wish to run conventional phenix, make a new directory (e.g. phenix) and copy those input files (1TOW.pdb, 1TOW.mtz, 1TOW.cif, and 1TOW-Supplementary.cif (if any)) and then run the conventional phenix refinement: 
    phenix.refine 1TOW.pdb 1TOW.mtz 1TOW.cif 1TOW-Supplementary.cif
  6. (Optional) If you wish to run conventional Refmac on the same fully prepared/protonated input, make a new directory (e.g. refmac) and copy those input files (1TOW.pdb, 1TOW.mtz, 1TOW.cif, and 1TOW-Supplementary.cif (if any)) and then run the conventional Refmac refinement.
  7. (Optional) If you wish to run conventional Buster on the same fully prepared/protonated input, make a new directory (e.g. buster) and copy those input files (1TOW.pdb, 1TOW.mtz, 1TOW.cif, and 1TOW-Supplementary.cif (if any)) and then run the conventional Buster refinement.
  8. Make a new directory (e.g. ‘xmodescore’) and chdir to that directory.
  9. Perform one (1) of the following Options:
    Option (A): Copy all output pdb and mtz files from refinements you would like to score into the directory ‘‘xmodescore’’. Then create a job list (e.g. joblist.txt) with the following format:

    1TOW_QM_refine_001.pdb 1TOW_QM_refine_001.mtz
1TOW_refine_001.pdb 1TOW_refine_001.mtz
1TOW-refmac1.pdb 1TOW-refmac1.mtz

    Option (B): Do not copy output pdb and mtz files into the directory ‘xmodescore’ but provide the full path in the job list file such as:

    /path/divcon/1TOW_QM_refine_001.pdb /path/divcon/1TOW_QM_refine_001.mtz
/path/phenix/1TOW_refine_001.pdb /path/phenix/1TOW_refine_001.mtz
/path/refmac/1TOW-refmac1.pdb /path/refmac/1TOW-refmac1.mtz
  10. Run XmodeScore using the command: 
    /path/to/DivConDiscoverySuite-bxxxx/scripts/xmodestats.sh
    --filelist joblist.txt --selection /A/CRZ/501// --np 8
    --QMdecomp off --allatom on
    Switch Value Description
    –filelist joblist.txt Use the list of files created above (referred to in this example as joblist.txt).
    –selection /A/CRZ/501// Specify the ligand using standard residue name/chain/ID designation as noted in the PDB file.
    -QMdecomp off Turn off/on QM-based interaction energy decomposition. WARNING: this can be a long running calculation (espcially if the structure is of questionable quality).
    –allatom on Turn off/on all atom calculations within the analysis. As noted above, it is highly recommended that you perform all refinements using protons. When a structure has all protons added it is considered an “all atom” model.
    –np 8 Set the number of threads for the run.
  11. Switch Value DescriptionExamine the CSV file named after the job list file (‘joblist.csv’ in this case) that has all scoring results.

Back to Top

 

Tutorial #4: ONIOM (QM/MM) XModeScore on PDBid:3HS4

In this example, XModeScore with ONIOM (QM/MM) is used to run on the PDB file corresponding to the RCSB PDBid 3HS4. The ONIOM method is a mixed-QM/MM algorithm which uses the AMBER force field mixed with the quantum mechanics functional. We have fully automated the process of atom typing, adding link atoms, and so on which tends to make QM/MM so problematic.

To download final input/output for this tutorial, click here.

  1. Source the proper Phenix and DivCon versions (assuming Bash shell): 
    source /path/to/phenix-1.10.1-xxxx/phenix_env.sh
source /path/to/DivConDiscoverySuite/etc/qbenv.sh
  2. Create a clean, empty directory and change directory into it.
  3. Execute phenix.ready_set to prepare and protonate structure: 
    qbphenix --pdbid 3HS4 --XmodeScore --protonation moe --nproc 20 --dir xmodeData
    --selection "chain A resname AZM resid 701" --protPH 9.0 --generateTautomers divcon
    --protomers "-1,0" --mmMethod amberff14 --qmMethod pm6 --buffer-radius 0.0
    --region-radius 3.0
Switch Value Description
–pdbID 3HS4 Automatically download coordinates and structure factors for 3HS4 directly from the RCSB and run it.
–XModeScore Execute XModeScore on the data provided in the pdbID command line option.
–protonation MOE Protonate the structure using MOE (i.e. Protonate3D)
–generateTautomers divcon Generate tautomers/protomers using built -in function in DivConDiscoverySuite
–protomers “-1..0” Generate tautomers for the base state as well as possible tautomers for -1 and +1 protonation states. Other common settings:
–protomers 0  (default) generate tautomers only
–protomers -1  generate tautomers for a negative (-1) protonation state only
–protpH 9.0 Protonate the structure using MOE (i.e. Protonate3D) using the crystal pH of 9.0
–dir xmodeData (optional) Run within subdirectory named ‘test1’ where ‘xmodeData’ is created at run time
–nproc 16 Set the number of threads for the run.
–mmMethod amberff14 Use the AMBER14 force field for the molecular mechanics portion of the structure (e.g. all residues outside of the region-radius).
–qmMethod pm6 Use the PM6 Hamiltonian for the quantum mechanics region(s) of the structure (e.g. all residues within the region-radius.
–buffer-radius 0.0 The buffer radius may be set to 0.0 Å as the ONIOM method will address interaction between QM and MM.
–region-radius 3.0 Include the residues within 3.0 Å of the selected ligand.

The calculation will perform 4 refinements in parallel with the various protonation states generated and upon conclusion, the following table will be produced and printed to the screen:

Species Residue Strain Energy RSCC ZDD XModeScore1 Interaction
1_0_0_-1 /A/AZM/701// 7.65 0.986 14.2 2.9 0
1_0_2_-1 /A/AZM/701// 10.8 0.985 17.5 0.44 0
0_0_0_0 /A/AZM/701// 9.68 0.981 19.3 0.196 0
0_0_0_-1 /A/AZM/701// 10.0 0.977 21.2 -0.665 0
1_0_1_0 /A/AZM/701// 15.0 0.978 21.7 -2.87 0

Back to Top

 

XModeScore for Fragment Based Drug Discovery

Protomer/tautomer cases have been automated as discussed in the examples above, and in the present case study, we will look at the use of XModeScore in Fragment Based Drug Design (FBDD). These steps can be modified for other cases as well (such as rotamer and binding mode determination). For example, at some firms, these steps have been applied to treatment of structures generated by several different refinement engines or density-driven docking methods, along with alternate structure cases. Once the workflow is automated within an organization, it can be executed within a pipeline environment.

The qbphenix execution script is already built to do most of the heavy lifting, but you still must provide the script with a set of structures to analyze. In this example, we will use the density-driven docking mechanism within MOE to generate a set of fragment poses for the 5C3K PDB file. You could just as easily use an alternate tool from other parties. For this Tutorial, you can download the following documents:

  1. Make initial preparation of the structure. This generally includes protonation. 
        qbphenix --pdbId 5C3K --protonation MOE --autoBuildMoe --nproc 4
        --selection "chain A resname 4XF resid 402"
  2. Open the protonated structure in MOE and check the ligand protonation. Use ‘Builder’ menu to correct formal charges if needed.
  3. Run phenix.maps to generate the mtz file with initial map coefficients (named ‘5C3K_map_coeffs.mtz’ in this case). 
      phenix.maps 5C3K.pdb 5C3K.mtz
  4. Open the protonated structure in MOE and go to Menu ‘Compute’ -> ‘Dock’. Choose the tab ‘Electron Density’ and ‘Open 5C3K_map_coeffs.mtz’ as density file. Choose Map type ‘2FOFCWT’ (default). Select ‘electron density’ as the scoring methodology. Then set the desirable number of poses for example, 50 and 10 (retained) under the menu ‘poses’. Select the desirable ligand to dock using the tab ‘Ligand’. Click ‘run’.
  5. After docking is complete save docked poses as an SD file using the menu ‘Database Viewer->File’->’Save as’ and select from ‘Output’ drop down menu the option ‘SD File’ . Then specify the file name , for example, ‘docked’ . This will create a single sd file ‘docked.sdf’ that contain all ligand poses.
  6. Make a directory named “preparedFiles” and change into that directory and run qmechanic command as shown below. This script will generate a set of files (5C3K_0.pdb to 5C3K_10.pdb in this case) where 5C3K_0.pdb is the original pdb 5C3K.pdb and each 5C3K_#.pdb corresponds to # ligand pose starting from 1. Note: re-protonate each file in MOE fixing the protonated state of the ligand. 
        mkdir preparedFiles ; cd preparedFiles
    qmechanic ../5C3K.pdb --edit "/A/4XF/402//, ../docked.sdf"
    cd ..
  7. Run XmodeScore using qbphenix as follows. The first example is provided using regular Phenix/DivCon (region refinement) while the second uses our new ONIOM (QM/MM) implementation. You may choose either version. 
    qbphenix --jobid 5C3K --XmodeScore preparedFiles --qmMethod pm6 --nproc 22
        --dir xmodeData --selection "chain A resname 4XF resid 402" --makeCIF moe
    Command Line Options are:
<<<
--jobid 5C3K 
--XmodeScore preparedFiles 
--qmMethod pm6 
--nproc 22 
--dir xmodeData 
--resname 4XF 
--resid 402 
--chain A 
--makeCIF moe 
<<<

XmodeScoreOverride

XModeScore Routine Started at 03-Nov-2016 21:22

# of Jobs (Total): 11,  # of Concurrent Jobs: 11, # of CPU's per Concurrent Job: 2

Preparing Job for Refinement: 7.pdb
........

$ cat 5C3K.XModeScore_final.log

Species       "Residue" "Strain Energy"  "RSCC"   "ZDD"  "XModeScore" "Interaction" "MOE Interaction" "MOE Score"
 1 /A/4XF/402//      5.39       0.978        2.12           3           0        -126       -4.88
 6 /A/4XF/402//      4.54       0.946        10.1        2.36           0        -175       -5.22
 7 /A/4XF/402//      5.12       0.901        17.9       0.713           0        -155        -5.1
 8 /A/4XF/402//      6.47       0.892        15.5      0.0984           0        -119       -4.86
 4 /A/4XF/402//      7.28       0.923        11.8      0.0816           0        -151       -4.85
 2 /A/4XF/402//      8.29       0.956        7.24      0.0593           0        -153       -5.11
 5 /A/4XF/402//      7.38       0.926        11.8      0.0073           0        -151       -4.87
10 /A/4XF/402//      6.59       0.882        20.2      -0.738           0        -141        -5.2
 3 /A/4XF/402//      9.04       0.916        13.9       -1.54           0        -122       -4.96
 9 /A/4XF/402//       8.3       0.869        19.5       -1.88           0        -151       -5.15
11 /A/4XF/402//      7.28       0.864          26       -2.16           0       -82.5       -4.66
    qbphenix --jobid 5C3K --XmodeScore preparedFiles --qmMethod pm6 --mmMethod amberff14
        --nproc 22 --dir xmodeData --selection "chain A resname 4XF resid 402" --makeCIF moe
    ........
cat 5C3K.XModeScore_final.log
Species       "Residue" "Strain Energy"  "RSCC"   "ZDD"  "XModeScore" "Interaction" "MOE Interaction" "MOE Score"
 1 /A/4XF/402//      5.34       0.978        1.91        3.18           0        -124       -4.94
 6 /A/4XF/402//      5.44       0.947        10.6        1.71           0        -176       -5.19
 4 /A/4XF/402//      5.85       0.933        12.5        1.09           0        -138       -4.87
 5 /A/4XF/402//      5.94       0.916        12.2        1.06           0        -138       -4.85
 7 /A/4XF/402//      5.62       0.899        18.2       0.354           0        -155       -5.04
 8 /A/4XF/402//      6.37       0.891        15.8       0.133           0        -111       -4.83
 2 /A/4XF/402//       8.4       0.953        7.52      -0.164           0        -153       -5.13
 3 /A/4XF/402//      8.79       0.919        14.7       -1.63           0        -120       -5.04
 9 /A/4XF/402//      7.79       0.861        19.8       -1.64           0        -155       -5.09
11 /A/4XF/402//      6.95       0.854        25.5       -1.88           0       -81.1       -4.66
10 /A/4XF/402//       8.4       0.866        20.2       -2.19           0        -149       -5.13

Back to Top

 

Automated MOE-based Docking – using qbphenix

Protomer/tautomer cases have been automated as discussed in the examples above, but the same principles are applicable to ligands, fragments, water molecules, and other species as well. In the present study, we will use MOE-based, density driven docking to automatically dock a ligand fragment within the active site, allow MOE to choose the best docked ligands as starting structures, and then perform an XModeScore calculation to choose the ligand binding mode which best fits the density. We have chosen to use the MOE-based docking method in this workflow, but one could easily modify the included $QBHOME/perl/qbphenix.pl script to run a similar analysis using a docking tool of your choice.

  1. Source the proper Phenix and DivCon versions (assuming Bash shell): 
    source /path/to/phenix-1.X-xxxx/phenix_env.sh
source /path/to/DivConDiscoverySuite/etc/qbenv.sh
  2. Perform an intial preparation of the structure. This includes download (in this case) and protonation. 
    qbphenix --pdbId 5C3K --protonation MOE --autoBuildMoe --nproc 4
        --selection "chain A resname 4XF resid 402"
  3. Using any text editor or other software remove the ligand from pdb file 5C3K-H.pdb and save it into another file e.g. 4XF_A_402.pdb
  4. Run phenix.refine to generate a difference map using 5C3K-H.pdb (without ligand). This step will perform a quick refinement and produce files 5C3K-H_refine_001.mtz and 5C3K-H_refine_001.pdb that will be used on the next step. 
    phenix.refine 5C3K-H.pdb 5C3K.cif 5C3K.mtz main.number_of_macro_cycles=1
  5. Run qbphenix to generate docking poses and execute XModeScore on each of those poses using a single command: 
    qbphenix --pdbFile 5C3K-H_refine_001.pdb --dataFile 5C3K.mtz
        --densityFile 5C3K-H_refine_001.mtz --ligandFile 4XF_A_402.pdb --dock dockFolderResults
        --qmMethod pm6 --Xmodescore --enforceprotonation --protonateTautomers MOE --np 22 --dir test1Res
Switch Value Description
–pdbFile 5C3K-H_refine_001.pdb Run the calculation on the previously generated, fully prepared 5C3K-H_refine_001.pdb file.
–dataFile 5C3K.mtz Use the mtz file generated in the first step.
–densityFile 5C3K-H_refine_001.mtz At the same time, include the density file from the previous step. This is the density into which the ligand will be docked during the refinement.
–ligandFile 4XF_A_402.pdb Finally, include the ligand PDB file which will be docked into the target.
–XModeScore Execute XModeScore on the above noted files.
–protonateTautomers MOE (re)Protonate the structure using MOE (i.e. Protonate3D) for each docked ligand. This option allows for some flexibily after docking and during refinement in the event that a pose is placed too close to binding pocket residues.
–dock dockFolderResults When the ligand is docked into the target, the output is placed in this directory for use during the XModeScore process.
–enforceprotonation (re)Protonate each docked file using the method specified by –protonateTautomers (default is MOE)
–dir xmodeData (optional) Run within subdirectory named ‘xmodeData’ where ‘xmodeData’ is created at run time
–nproc 16 Set the number of threads for the run.
–mmMethod amberff14 Use the AMBER14 force field for the molecular mechanics portion of the structure (e.g. all residues outside of the region-radius).
–qmMethod pm6 Use the PM6 Hamiltonian for the quantum mechanics region(s) of the structure (e.g. all residues within the region-radius.

Back to Top

 

Clustered XModeScore with PBS (or SGE)

With the DivCon Discovery Suite version 7.5, integrated support for PBS (and SGE) has been provided for running XModeScore across an entire cluster using a queuing platform. This implementation does assume a few key cluster characteristics. Since each cluster is different and there is no way we can fully generalize our implementation for all environments, it is perfectly acceptable and expected that some environment-specific modification will be required. You and your administrator should review the following key points and modify the discussed template files in order to fit your environment. If you require support in this effort, please Contact Us and we’ll be happy to help!

  1. The XModeScore workflow actually involves the main process and a number of sub-processes (one for each tautomer/protomer/pose/etc being treated). Generally, the main process which actually uses qbphenix will be run on the master node (or other node having “job submission” permission). This main process will create all of the sub-process PBS/SGE scripts as required, submit these scripts to the chosen queuing system (using qsub), and then “watch” these sub-processes until they are finished and the final results appear in the execution directory.
  2. With this workflow in mind, the main process (qbphenix) must be executed either interactively or within a job script created and submitted by the user on a node (master or cluster) which has permission to submit jobs.
  3. The templates for each queuing system are provided in the $QBHOME/perl/ directory with the file names phenix_pbs.tmpl and phenix_sge.tmpl for PBS and SGE respectively. These templates are processed by the main-process at runtime to generate the sub-process scripts. Therefore, any modifications or “tweaks” required for your particular environment should be done within these templates so that these changes are captured in subsequent executions of XModeScore.
  4. The current templates are built so that calculations are performed within local /scratch directories on each node and then the required files from these scratch directories are copied back to the $PBS_O_WORKDIR or $SGE_O_WORKDIR upon completion. If your environment does not require the use of local /scratch directories, then you may remove the references to scratch and the WORKDIR’s since all calculations will be – by definition – executed in the WORKDIR.
  5. XModeScore (along with almost all of QuantumBio software) utilizes thread-based, symmetric multiprocessing (SMP) parallelism for each sub-process and therefore it is highly recommended that each node have multiple cores (and your queuing system support SMP).

Once you have successfully modified the template files for your environment, the following tutorial demonstrates the specific command line options which qbphenix requires to “switch on” cluster support and use your cluster platform to distribute jobs to various nodes:

  1. Source the proper Phenix and DivCon versions (assuming Bash shell): 
    source /path/to/phenix-1.X-xxxx/phenix_env.sh
source /path/to/DivConDiscoverySuite/etc/qbenv.sh
  2. Run qbphenix on the master node (or within another PBS/SGE script of your own design on a node with job submission permission). 
    qbphenix --pdbID 3HS4 --protonation divcon --qmMethod pm6 --mmMethod amberff14  
        --region-radius 4.0 --buffer-radius 0.0 --nproc 4 --selection "chain A resname AZM resid 701"  
        --dir xmodeData --protomers "-1..0" --cluster sge --XModeScore
Switch Value Description
–pdbID 3HS4 Run the calculation first by downloading the PDB and structure factor files from the RCSB.
–protonation DivCon or MOE FUse qmechanic (DivCon) for the initial protonation prior to tautomer/protomer generation.
–XModeScore Execute XModeScore
–protonateTautomers MOE (re)Protonate the structure using qmechanic (DivCon) for each tautomer.
–cluster sge or pbs Using the template files found within $QBHOME/perl, generate PBS/SGE scripts for each sub-process and qsub the each job to the configured cluster.
–dir xmodeData (optional) Run within subdirectory named ‘xmodeData’ where ‘xmodeData’ is created at run time
–nproc 4 In the cluster context, this is the number of processors for each XModeScore sub-process.
–mmMethod amberff14 Use the AMBER14 force field for the molecular mechanics portion of the structure (e.g. all residues outside of the region-radius).
–qmMethod pm6 Use the PM6 Hamiltonian for the quantum mechanics region(s) of the structure (e.g. all residues within the region-radius.

Back to Top

Key Resources