Frequently Asked Questions

Please check the online version of this FAQs page: https://gphl.gitlab.io/grade2_docs/faqs.html as this is updated as new questions come in.

Please also see:

General FAQs

How can I check that Grade2 is correctly installed and works properly?

Click to expand/hide answer

To check that Grade2 is correctly installed and configured run:

grade2 -checkdeps

If this results in a final line starting with SUCCESS then Grade2 has been successfully configured with access to a working CSD software installation. If there is a problem please see the Configuration Instructions.

To test that all the components used by Grade2 work as expected on your system then run the command:

grade2_tests

grade2_tests will run over 300 unit, functional and integration tests written as part of the test-driven development used for coding Grade2. Please see Testing section for more details.

How can I run Grade2 without a CSD installation?

Click to expand/hide answer

Grade2 uses the Mogul and the CSD Python API tools from the CCDC. Because of this Grade2 requires an installation of the CSD-Core package to work. For details on how to obtain CSD-Core please see:

https://www.ccdc.cam.ac.uk/solutions/csd-core/

If you cannot get access to CSD-Core then you can run Grade (the predecessor of Grade2) using the Grade Web Server:

http://grade.globalphasing.org/

We hope to extend this service to run Grade2 soon (work is underway).

Why must I enter my name and email address to use the Grade Web Server?

Click to expand/hide answer

We ask you to enter your name and email address so that we can contact you if an issue arises when Grade2 is run with your molecule. We do not routinely contact people and do not store email addresses in the long term. For further details please see the Grade Web Server Conditions of Use and Privacy Policy: http://grade.globalphasing.org/grade_server/conditions.html .

Does Grade2 work with the latest update of CSD?

Click to expand/hide answer

Because the CSD and BUSTER installations are separate incompatibilities can arise. Before you update your CSD update please check https://gphl.gitlab.io/grade2_docs/csd_compatibility.html to make sure there is not a problem.

How do I make a suggestion for a new feature in Grade2?

Click to expand/hide answer

We really like suggestions for improvements to Grade2. Please send an E-mail to buster-develop@GlobalPhasing.com saying what you would like.

I have a problem with Grade2: what should I do?

Click to expand/hide answer

In order to help us in the book-keeping of user support requests, of the issues they raise and of the responses we supply, it would be really helpful if you could follow the following guidelines.

If you have a problem with Grade2 please:

  1. First check the online Known issues page:

    https://gphl.gitlab.io/grade2_docs/issues.html

    as it may already be a known problem with a solution or workaround.

  2. Then check the online version of this FAQs page:

    https://gphl.gitlab.io/grade2_docs/faqs.html

    as this is updated frequently as new questions come in.

  3. Please send an e-mail to buster-develop@GlobalPhasing.com describing the problem with as much detail as possible.

    Please make sure you include the following information in the e-mail:

    • A clear description of the issue, what kind of input was used and from where it originated (for instance, if a MOL2 file was used what program wrote it).

    • A descriptive subject for the e-mail. For instance, "Grade2 crashes for ligands containing boron" is much better than "Restraints Problem".

    • The terminal output of Grade2 where the problem is encountered.

    • The outputs of the commands:

      grade2 -checkdeps
      grade2_tests
      
    • The operating system and its version you are running.

    It is really helpful for us if you could follow the following guidelines.

    • That you report separate problems one at a time rather than raising multiple issues in a single e-mail. Separate e-mails make it much easier to tackle and respond fully to each of the problems.

    • That you avoid reporting a new unrelated problem in a reply to an e-mail about a previous issue. Replies are automatically linked to the original report so making things rather confusing. It is much better if you could send a new email describing the new problem (with a relevant subject). It gets a bit confusing when a report comes in with a subject that is "Re: old issue with Grade2" when it is actually about something entirely different.

    • The article "9 Best Practices for Software Bug Reporting" gives some really useful further advice.

How to cite Grade2?

Click to expand/hide answer

The main citation for Grade2 is:

Smart, O.S., Sharff A., Holstein, J., Womack, T.O., Flensburg, C., Keller, P., Paciorek, W., Vonrhein, C. and Bricogne G. (2021) Grade2 version 1.3.0. Cambridge, United Kingdom: Global Phasing Ltd.

The Grade2 version number is reported when Grade2 is run and can be found from any Grade2 output CIF restraint dictionary by using grep. For example:

$ grep grade2_version LIG.restraints.cif
_gphl_chem_comp_info.grade2_version                   1.0.0

Security: does Grade2 upload any ligand information to public servers?

Click to expand/hide answer

Grade2 does not upload any information about a ligand to public servers, unless you activate and then choose to use the --pubchem_names option.

The --PDB_ligand ID option retrieves information from wwPDB sites about the specified existing PDB chemical component given ID, its three letter code . Similarly the --lookup ID uses a script to retrieve information for a molecule with ID from a public or internal chemical database depending on the script used. Both of these options retrieve information about pre-existing molecules.

During a Grade2 run a check for related PDB components is made. This check is entirely local with no use of any external services. The procedure finds the input molecule's InChIKey using RDKit routines. This InChIKey is compared to a precalculated list of InChIKeys for all PDB components that is distributed as part of Grade2. The list of InChiKeys will be up-to-date at the time of the Grade2 release and can be found in one of the following files (depending on the operating system):

$BDG_home/.mc/linux64/lib/python3.7/site-packages/pdbccdinchikeys/data/PDBCCD_id_status_date_inchikey_name.csv

$BDG_home/.mc/darwin/lib/python3.7/site-packages/pdbccdinchikeys/data/PDBCCD_id_status_date_inchikey_name.csv

The --pubchem_names option involves uploading the SMILES string of the molecule to PubChem and so it should not be used for confidential ligands. To be extra careful, by default this option is deactivated and will not work until it is activated. Please see --pubchem_names documentation for details of the activation process.

The Grade Web Server http://grade.globalphasing.org/ provides a way to Grade2 online. Clearly, this necessarily involves transmission of the molecule of interest to a public web server, so the Grade Web Server should not be used for confidential ligands.

Input FAQs

How can I use Grade2 to generate a restraint dictionary with atom names consistent with an existing Grade dictionary?

Click to expand/hide answer

Suppose you are working on a project and have used Grade to generate a restraint dictionary for the ligand, used this for model building & refinement and now want to continue using a Grade2 restraint dictionary. To make the switch painless it is important that the atom naming for the ligand should not be altered. Thanks to Wei-Chun Kao for raising this question.

Grade2 can reliably use CIF restraint dictionaries from AceDRG, eLBOW and Grade2 as an input. But Grade's restraint dictionaries CIF lacks explicit atom charge records (_chem_comp_atom.charge). The first release of Grade2 (1.0.0) would terminate with an error message in such a case. However, in most cases it is normally OK to assign all atoms a charge of 0 . Hence, from release 1.1.0, when Grade2 reads such as file it assigns a charge of 0 to each atom and writes a WARNING message to the terminal output:

WARNING:
WARNING: Input restraint file CIF lacks explicit atom charge records _chem_comp_atom.charge
WARNING: ---- so will set all the atom charges to 0 and continue.
WARNING: ---- This should be fine for most neutral molecules.
WARNING: ---- But for charged atoms/molecules it will fail!
WARNING: ---- See FAQs https://gphl.gitlab.io/grade2_docs/faqs.html for more information
WARNING: ---- and instructions about a manual workaround to set atom charges.
WARNING: ----
WARNING: ---- Check InChi match messages below for problems!
WARNING:

For most neutral molecules assigning a charge of zero will be fine. However, for charged molecules or those containing groups like nitro the approach will produce incorrect chemistry. It is important to check the subsequent terminal output for messages about the checks made on the InChI read from the input file and that for the RDKit molecule used by Grade2. There should be a message:

RDKit molecule generated has the same InChI as that from the input.
---- This indicates that the stereochemistry matches so setup is successful.

indicating success. But if there is output like:

WARNING: RDKit molecule created has an InChI that does not match that read from the input.
WARNING: This means the stereochemistry of the molecules is likely to be different.
WARNING: You are advised to check molecules and restraints carefully.

then it will be necessary to manually edit the molecule's bonding and charge state - please see the next FAQ for a guide of how to do so.

How can I run Grade2 if I only have a PDB file for the ligand?

Click to expand/hide answer

Grade2 does not allow PDB-format files to be directly used as an input. This is because the PDB-format does not normally carry information as to the order of the molecule's bonds. Assigning the bond order is necessary before restraints can be generated. If the PDB file for the ligand includes hydrogen atoms, then Open Babel can be used to assign bond orders and produce a MOL2-format file. For example for grade-INH.pdb:

$ obabel grade-INH.pdb -O grade-INH.mol2

Use the MOL2-format that results as an input to Grade2, for example:

$ grade2 --in grade-INH.mol2 --resname INH

Carefully examine the results checking that chemistry of the resulting molecule matches that of the original Grade. If there is any difference then Mercury should be used for the conversion to MOL2 as Mercury allows a manual editing of the chemical markup as described next.

In the case of an old macromolecular refinement result, ligands routinely lack explicit hydrogen atoms and this makes chemical markup particularly challenging and prone to error.

The CSD-core program Mercury (that you will have access to as it is distributed alongside Mogul) can be used to read in a PDB-format file of a ligand, assign bond orders and add hydrogen atoms if necessary. There is an "auto Edit Structure..." option but the results of this should always be carefully checked. If there is a problem then Mercury has comprehensive manual editing options that can be used to alter bond orders, add/delete hydrogen atoms and set atom charges. Once you are happy the chemistry of the ligand molecule is correct, then in Mercury save it to a MOL2 format. The MOL2 file can then be used as an input to Grade2, using the --in option.

As an example to show this process, lets use the PQA ligand from PDB structure 2bal. Suppose that the only details of the ligand available was the conformation from the PDB file that lacks hydrogen atoms (in reality the grade2 option --PDB_ligand PQA should be used).

Extracting the coordinates of the ligand from the PDB file:

$  egrep "HETATM.*PQA" 2bal/2bal.pdb > 2bal_pqa.pdb

Then run Mercury and load the file 2bal_pqa.pdb. Once loaded, select the Mercury option "Edit" -> "Auto Edit Structure..."

Screenshot Mercury Auto Edit on 2bal PQA - menu

If your molecule lacks explicit hydrogen atoms tick the option "Add missing H atoms". Then click the "Apply" button and Mercury will then analyze the structure, assign bond orders and add hydrogen atoms:

Screenshot Mercury Auto Edit on 2bal PQA - the result

You should check the results carefully as ascribing chemistry to a molecular structure in the absence of bond orders and without hydrogen atoms is a difficult task. If the bond orders and/or hydrogen atoms added are wrong then Mercury has comprehensive manual editing options that can be used to alter bond orders, add/delete hydrogen atoms and set atom charges. In the PQA example test case, Mercury correctly assigns the bond orders and adds hydrogen atoms to the PQA molecule and no editing is required, despite the piperidine ring being in a 'mangled' conformation.

Once you are happy that the edited chemical markup of the molecule is correct, select the Mercury menu item "File" -> "Save As" and the option "Mol2 files". This will save the molecule as a MOL2 file that will preserve the atom names from the original PDB file as well as your edited chemical markup.

Then use the resulting MOL2 file as the input to grade2 using the --in option. Note that you will also need to specify the correct residue name (3-letter code) for the molecule as this is not preserved by Mercury. Doing this for the example test case:

$ grade2 --in 2bal_pqa_mercury_autoedit.mol2 --resname PQA

results in producing a restraint dictionary for the molecule where the piperidine is charged. The non-hydrogen atom names are consistent with the input PDB file. The restraint dictionary can then be used for further fitting and/or refinement.

If you want to use a command line tool to do the process rather than Mercury then this can be done with OpenBabel, please see BUSTER wiki page Hydrogenate PDB with Open Babel. It is still essential to carefully check/correct the results if this is done.

Finally once again, it should be noted that in practice for structures from the PDB databank the --PDB_ligand option should be used as this downloads all information from the PDB chemical component dictionary.

How can I produce restraints for a ligand with a different protonation state or tautomer?

Click to expand/hide answer

The CSD-core program Mercury (that you will have access to as it is distributed alongside Mogul) can be used to manually edit the bonding, hydrogen atom positions and atomic charges of a ligand. Mercury can be used to edit a ligand's tautomeric or protonation state, while preserving its atom names. For a demonstration of how to do this in practice please see:

Editing MOL2 file of a charged molecule with atomic partial charges

Click to expand/hide answer

There is currently an issue Grade2 cannot read a MOL2 file of a charged molecule when it has atomic partial charges. When this happens, it is possible to manually edit correct formal charges using Mercury. For a demonstration of how to do this in practice please see:

Editing MOL2 file of a charged molecule with atomic partial charges

What can be done if there is an ERROR in generating a 3D conformation for the molecule?

Click to expand/hide answer

Some molecular inputs to Grade2, such as SMILES strings or 2D SDF files, do not have 3D coordinates for the atoms. When given such an input, Grade2 will use RDKit routines to produce an initial 3D conformation.

Generating 3D conformations for a knotted molecule with many intersecting rings can be difficult. Indeed, it is possible to construct SMILES strings for molecules that cannot be constructed in 3D, for instance c1c2ccc3cc2ccc13 is a napthalene with an additional bond between carbon atoms on opposite sides of the double ring:

impossible bridged napthalene image from http://hulab.rxnfinder.org/smi2img/

If Grade2 produces a message ERROR: Cannot generate a 3D conformation for the input molecule. then we would suggest:

  • Check the input SMILES string. Has it been corrupted? How reliable is its source?

  • Use an online 2D image generator for instance http://hulab.rxnfinder.org/smi2img/ or https://cactus.nci.nih.gov/gifcreator/ . Does the image make sense?

  • If the molecule is already available in another format (for instance SDF) then use this.

  • If the SMILES string contains stereo atom specifiers @ try removing or altering these.

  • Try other 3D conformation generators. These could be restraint generation programs (for instance Grade or AceDRG) or an online tool such as https://cactus.nci.nih.gov/translate/ . Check any results carefully using molecular graphics (for instance Mercury). If a reasonable 3D conformation is produced then use this as an input to Grade2.

If you are still stuck, please contact us at buster-develop@GlobalPhasing.com and we will try to help.

Output FAQs

Grade2 says that the ligand matches an existing PDB chemical component. What should I do?

Click to expand/hide answer

As part of the Grade2 run a check is made whether the molecule matches any existing PDB chemical component (from the wwPDB Chemical Component Dictionary https://www.wwpdb.org/data/ccd ). The check uses the InChIKey of the ligand. The InChIKey is a shortened form of the International_Chemical_Identifier (InChI) that facilitates the comparison of molecules.

For example, if Grade2 is supplied the SMILES string Cn1cnc2c1C(=O)N(C(=O)N2C)C then the following terminal output will result:

CHECK: Check the molecule`s InChiKey against known PDB components:
CHECK: Exact match to PDB chemical component(s):
CHECK:   CFF https://www.rcsb.org/ligand/CFF "caffeine"

So the SMILES string is for caffeine that is an existing PDB component https://www.rcsb.org/ligand/CFF. It is likely to be sensible to use the Grade2 dictionary for CFF for fitting and refinement.

Please note that tautomers normally have the same InChIKey (for an example see PDB components 2D3 and XQK).

If Grade2 reports an unexpected match to an existing PDB chemical component, then it may be a good idea to switch to using a Grade2 restraint dictionary for the matching chemical component. If you deposit the structure to the PDB with a ligand that matches an existing PDB chemical component then it will be renamed (including all the atom IDs). If a match is reported please check that the tautomeric/charge state is what you want before switching.

We are currently working on a Grade2 option that will allow atom IDs to be taken from related compounds, such as tautomers or stereoisomers. Please let us know if you would like this option.

What are the Grade2/BUSTER restrictions on residue name?

Click to expand/hide answer

There is no problem in Grade2 using any string as a residue name for a novel ligand (using the --resname option. It is common practice for companies to use LIG, INH or DRG, although these three codes were issued in the PDB chemical component library, they have now been withdrawn:

From Jasmine Young <jasmine.young@rcsb.org>
Date: Wed, 27 Oct 2021 11:12:43 -0400

Dear all,

The wwPDB OneDep team would like to inform you that we have reserved a set of
ligand identifier codes that will never be used by the PDB. This is to allow
depositors to use such codes for their new ligands during structure
determination processes.

These reserved ligand codes are LIG, INH, DRG, and 01-99 (two digits). The
OneDep deposition system will be ready for this change in December 2021.

We encourage you adopt these ligand codes in your software packages.

Regards,

Jasmine

It can be noted, that some groups use the work code UNL but this has a specific meaning in the wwPDB database meaning "unknown ligand" https://www.rcsb.org/ligand/UNL. This normally indicates that an unexpected ligand has been identified from a blob of electron density. So it is best to avoid UNL as a working residue name.

By default, Grade2 now uses residue name LIG.

Grade2 can produce CIF restraint dictionaries for residue names longer than three-characters but currently there are often compatibility problems with downstream programs, such as BUSTER. BUSTER uses PDB-format for molecular input and currently can only handle residue names that are 3-characters or shorter. This will need to be dealt with soon (PDB news: once all three-character alphanumeric codes are exhausted four-character codes will be issued).

Please note, that it is also necessary to avoid residue names for the common compounds (such as SO4) that can be found in $BDG_home/tnt/data/common-compounds.

.


























(the blank lines above are included so that hyperlinks work better).

Please check the online version of this FAQs page: https://gphl.gitlab.io/grade2_docs/faqs.html as this is updated as new questions come in.