Grade2 outputs

Running the grade2 command, as described in the Usage and Examples chapters, will result in outputs both to file(s) and to the terminal. This chapter gives a guide to as to what to expect.

Terminal Output

grade2 writes out information about the restraint generation process as it runs to the terminal. This output is intended to be intelligible and to give an indication that the restraints generation process it proceeding normally for the ligand in question.

For example, generating a restraint dictionary for the PDB chemical component ID VIA (Sildenafil) running

$ grade2 --PDB_ligand VIA

produces an initial output giving copyright, authors and program version information, following the normal BUSTER package convention:

$ grade2 --PDB_ligand VIA
 set CSDHOME=/home/software/xtal/CCDC/CSDS/2021.3/CSD_2022 from $BDG_TOOL_MOGUL=/home/software/xtal/CCDC/CSDS/2021.3/CSD_2022/bin/mogul
 ############################################################################
 ##   [grade2] ligand restraint dictionary generation
 ############################################################################

      Copyright (C) 2019-2022 by Global Phasing Limited

                All rights reserved.

                This software is proprietary to and embodies the confidential
                technology of Global Phasing Limited (GPhL). Possession, use,
                duplication or dissemination of the software is authorised
                only pursuant to a valid written licence from GPhL.

   Version:   1.1.0 <2022-02-01>
   Authors:   Smart OS, Sharff A, Holstein J, Womack TO,  Flensburg C,
              Keller P, Paciorek W, Vonrhein C and Bricogne G

 -----------------------------------------------------------------------------

This is followed by output lines saying where the information from where the PDB chemical components definition for VIA is collected and giving web URLs to get further information about VIA (https://www.rcsb.org/ligand/VIA and https://www.ebi.ac.uk/pdbe-srv/pdbechem/chemicalCompound/show/VIA ).

Collected PDB chemical components definition for PDB id VIA
from: ftp://ftp.ebi.ac.uk/pub/databases/msd/pdbechem_v2/V/VIA/VIA.cif
Molecule name: "5-{2-ethoxy-5-[(4-methylpiperazin-1-yl)sulfonyl]phenyl}-1-methyl-3-propyl-1H,6H,7H-pyrazolo[4,3-D]pyrimidin-7-one"
For more information about "VIA" see:
---- https://www.rcsb.org/ligand/VIA
---- https://www.ebi.ac.uk/pdbe-srv/pdbechem/chemicalCompound/show/VIA

This is followed by information that the VIA molecule has a nitrogen atom that will normally be charged at neutral pH and a proton has been added to the molecule:

 WARNING: Charging groups likely to be charged at neutral pH.
 WARNING: ---- If you do not want this, rerun with the option: -N, --no_charging
         charging trialkylamine to trialkylammonium
         add new proton HN17 onto atom N17 (existing hydrogen atom_ids: None)
[16:42:04] WARNING: Proton(s) added/removed

If this charging is not wanted then the use --no_charging command-line option. For more details on the charging process see the Charging chapter.

A check is then made that the RDKit molecule generated for restraint production has an InChI that matches that from the input file (if this is available). InChI is short for International_Chemical_Identifier and provide a way to quickly check that the stereochemistry of molecules match. In this case, the output indicates that there is a match other than for the protonation layer, as would be expected giving the charging:

RDKit molecule generated has the same InChIKey as the other than the last protonation character.
---- This indicates that the stereochemistry matches other than the change caused by charging.

For all input sources, a check is made comparing the InChiKey of the RDKit molecule generated for restraint production with those for known PDB components (from the wwPDB Chemical Component Dictionary https://www.wwpdb.org/data/ccd ). In this case, the CHECK produces the expected result - that the molecule matches component VIA (apart from the checking):

CHECK: Check the molecule's InChiKey against known PDB components:
CHECK: Match to PDB chemical component(s) with a different number of protons:
CHECK:   VIA https://www.rcsb.org/ligand/VIA "5-{2-ethoxy-5-[(4-methylpiperazin-1-yl)sulfonyl]phenyl}-1-methyl-3-propyl-1H,6H,7H-pyrazolo[4,3-D]pyrimidin-7-one"

The check is most important for when using a molecule from a SMILES string or file input when this matches an existing PDB component (see example of this). If there is a match then it normally makes sense to use the restraint dictionary for the matching PDB component (see FAQ on matching components).

The checks are followed by information about the progress of restraint-generation including the force field used, the Mogul version and the final geometry optimization:

Minimization with MMFF94s reduces energy from 64.88 to 8.35 kcal/mol
Using CCDC Mogul-like geometry analysis.
Mogul version 2021.3.0, CSD version 543, csd-python-api 3.0.9
Geometry Optimize coordinates against restraints using gelly ....
---- gelly: Took 1472 steps, reducing the rms gradient to 0.05
---- gelly: and the rms bond deviation to 0.002 Angstroms.

The final part of the terminal output gives information about the output files produced and suggestions as to commands to view the results:

Have written CIF-format restraint dictionary to:   VIA.restraints.cif
Have written ideal coordinates to PDB-format file: VIA.xyz.pdb
Have written ideal coordinates to SDF-format file: VIA.xyz.sdf
Have written ideal coordinates in  MOL2-format to: VIA.xyz.mol2
Have written schematic 2D diagram SVG-format file: VIA.diagram.svg
Have written 2D diagram & atom_id labels to file:  VIA.diagram.atom_labels.svg
Suggestion: to view/edit the restraints, use one of the commands:
   coot -p VIA.xyz.pdb --dict VIA.restraints.cif
   EditREFMAC VIA.restraints.cif VIA.xyz.pdb VIA
Normal termination (7 secs)

grade2 follows standard Unix (and BUSTER) practice with normal output being written to STDOUT and errors to STDERR. This means that redirection or pipe/tee can be used to capture the output to a file (see How do I save terminal output to a file? for a guide to the many ways to do this).

CIF-format restraint dictionary

The CIF-format restraint dictionary file is the principal output of Grade2. The file lists the restraints generated as well as the important run-related information. The CIF-format restraint dictionary produced by Grade2 can be used with the BUSTER refine, Rhofit, Buster-report and the EditREFMAC restraint editor. In addition it can be used with Coot and should work with other 3rd-party refinement programs. Please let us know any compatibility issues you find.

The CIF-format restraint dictionary standard used by Grade2 is currently rather loosely set by what is understood by REFMAC and Coot, and has many items not set in the official PDBx/mmCIF Dictionary. Grade2-specific extensions are stored as data categories with name starting _gphl_ for instance _gphl_chem_comp_info. The command-line option --no_extra can be used to turn off Grade2-specific CIF categories and items.

Systematic names

If available, the output CIF-format restraint dictionary will contain information as to the systematic name of the ligand. The pdbx_chem_comp_identifier data category will be used. Systematic names for PDB ligands are automatically obtained from the input PDB chemical component definition (if the ligand is charged by Grade2 then " (CHARGED)" will be added). The --pubchem_names option can be used to do a online lookup the systematic name for ligands that occur in PubChem. The --systematic option allows the systematic name to be manually set. Currently, we are not aware of any open source systematic chemical name programs but commercial programs to produce systematic names are available from ACD/Labs, OpenEye and Chemaxon.

Database Information

From Grade2 version 1.3.0 information about entries for the ligand in Chemical databases is included in the output CIF restraint dictionary. This information is held in the CIF data category gphl_chem_comp_database. For example, for PDB chemical component VIA output restraint dictionary will have the automatically have the information:

 #
loop_
_gphl_chem_comp_database.comp_id
_gphl_chem_comp_database.id
_gphl_chem_comp_database.database
_gphl_chem_comp_database.url
_gphl_chem_comp_database.details
VIA VIA PDB                                   https://www.rcsb.org/ligand/VIA "RCSB PDB"
VIA VIA PDB https://www.ebi.ac.uk/pdbe-srv/pdbechem/chemicalCompound/show/VIA       PDBe
#

For PDB chemical components Grade2 automatically provides details to access RCSB PDB and PDBe pages. The --pubchem_names also automatically sets the

The information pro

"Ideal" coordinate files

At the end of the restraint generation process a geometry optimization of the coordinates of molecule with the gelly geometry-only minimizer is made. This produces a set of coordinates that where the bond length, bond angles and other terms are adjusted to be as close as possible to the "ideal" values. These coordinates are then used to output files in a variety of formats. Please note that the "ideal" coordinates can be trapped at a local minimum.

PDB-format

PDB-format is a widely used exchange chemical file format for proteins. Grade PDB-format ideal coordinates are written using RDKit routines, as so have CONECT records giving the bond order that are recognized by some molecular graphics programs (such as Jmol).

SDF-format

Please note that SDF-format file will use Kekulé bonding (where aromatic bonds are marked with alternating single and double bonds) whereas the MOL2-format uses CSD conventions for aromatic bonds.

MOL2-format

The MOL2-format file uses aromatic bonding following the CSD convention. This makes them suitable for running addition Mogul geometry analysis.

schematic 2D molecular diagrams

As well as writing a CIF restraint dictionary and "ideal" coordinates files Grade2 will produce schematic 2D molecular diagrams that can be useful. For instance, for the PDB ligand CFF caffeine, running grade2 --PDB_ligand CFF will write two SVG files that can be visualized using a web-browser (such as Chrome):

  1. CFF.diagram.svg

    CFF.diagram.svg converted to png
  2. CFF.diagram.atom_labels.svg the diagram with atoms labelled

    CFF.diagram.atom_labels.svg converted to png