Installation, Configuration & Testing¶
Installation¶
Grade2 is installed as part of the BUSTER distribution. For a full description of how to install BUSTER please see the installation documentation available at https://www.globalphasing.com/buster/manual/installation/index.html
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 no local installation of CSD-Core is available, we would recommend using the Grade Webserver at http://grade.globalphasing.org (for non-confidential ligands). The Grade Webserver will soon be upgraded to use Grade2.
Initial Configuration¶
To work Grade2 needs to be able to locate the CSD and CSD Python API installations. The locations are found by setting environment variable(s). If you have followed the BUSTER Snapshot Installation Guide available at https://www.globalphasing.com/buster/manual/installation/index.html and can run Grade it is likely that Grade2 will already work.
To check whether Grade2 can find the CSD installations use the grade2
command-line option -checkdeps:
grade2 -checkdeps
If this results in a final line starting with SUCCESS then Grade2 has been
successfully setup, for example:
$ grade2 -checkdeps
############################################################################
## [grade2] ligand restraint dictionary generation
############################################################################
... (output abbreviated) ...
-checkdeps option: verbose dependencies check for required external tools
with tests all tools work properly.
CSD installation found
Test using carbon dioxide from SMILES O=C=O bond angle:
RDKit generated molecule and coordinates from input SMILES: O=C=O
CHECK: Check the molecule's InChiKey against known PDB components:
CHECK: Exact match to PDB chemical component(s):
CHECK: CO2 https://www.rcsb.org/ligand/CO2 "carbon dioxide"
For help on checks against known PDB components, , see: ....
---- https://gphl.gitlab.io/grade2_docs/faqs.html#checkpdbmatch
Minimization with MMFF94s reduces energy from 30.80 to 0.00 kcal/mol
Using CCDC Mogul-like geometry analysis.
Mogul version 2022.2.0, CSD version 543, csd-python-api 3.0.13
Mogul Data Libraries: as543be_ASER, Mar22_ASER, Jun22_ASER
Geometry Optimization is turned off.
Result: O=C=O ideal bond angle 179.1 degs from Mogul_mean_30_hits
SUCCESS: grade2 -checkdeps indicates that everything needed to run grade2 works fine
If instead grade2 -checkdeps has lines starting with ERROR then you
should set the
shell variable BDG_TOOL_MOGUL to the location the mogul executable on your
system. If are a sh, bash or dash user this can be achieved by a
command like:
export BDG_TOOL_MOGUL=/Applications/CCDC/CSD_2022/mogul.app/Contents/MacOS/mogul
whereas if you are a tcsh or csh you should use a command like:
setenv BDG_TOOL_MOGUL /Applications/CCDC/CSD_2022/mogul.app/Contents/MacOS/mogul
You will need to modify the command used to the correct location on your system.
Please note that there was a major change in the CSD file locations and configuration in the release CSD 2023.1 made in April 2023. This can lead to problems where Grade2 terminates with a "CSDNotFoundException" error, if this occurs please see: FAQ Grade2 terminates with a "CSDNotFoundException", what should I do?.
As well as setting the environment variable BDG_TOOL_MOGUL, if there has
been creative use of symbolic links, it might be necessary to set
the environment variable BDG_TOOL_CSD_PYTHON_API to the location
of the Python_API_2022 directory or csd-python-api directory
included in your CSD distribution.
Once you have found the environment variables necessary to get
grade2 -checkdeps reporting SUCCESS it is best if these are added to
the BUSTER setup_local.sh or setup_local.csh file, as explained
in the BUSTER Snapshot Installation Guide BUSTER configure section.
This means that the Grade2 configuration will done together
with BUSTER by the setup script setup.sh or setup.csh.
Testing Grade2¶
To test whether Grade2 has been configured correctly then use the grade2
command-line option -checkdeps:
grade2 -checkdeps
If this does not result in a final line that starts with SUCCESS then
please follow instructions in the Configuration section above.
To test that all the components used by Grade2 work as expected on your
system then run the command grade2_tests. For example:
$ grade2_tests
using CSD from $CSDHOME=/Applications/CCDC/CSD_2022
============================ test session starts =============================
platform darwin -- Python 3.7.4, pytest-6.2.2, py-1.10.0, pluggy-0.13.1
rootdir: /Users/osmart/GPhL/BUSTER_snapshot_20220420/.mc/darwin/lib/python3.7/site-packages/grade2/tests
plugins: forked-1.2.0, cov-2.11.1, xdist-2.2.0, mock-3.5.1
collected 350 items
test_big_planes.py ....... [ 2%]
test_charge_neutral_groups.py ................. [ 6%]
test_csd_mol2_file_parser.py ............................. [ 15%]
test_dictionary_comparison.py .... [ 16%]
test_dictionary_creation.py .......................................... [ 28%]
............................ [ 36%]
test_dictionary_reader.py ....................... [ 42%]
test_geometry_optimization.py .... [ 44%]
test_grade2_cli.py ................................................... [ 58%]
............................................ [ 71%]
test_grade2_utils_cli.py .......... [ 74%]
test_ideal_pdb_contents.py ..... [ 75%]
test_metal_handling.py .. [ 76%]
test_mogul_dictionary_creation.py ....s............. [ 81%]
test_pdb_ccd_cif_reader.py .. [ 81%]
test_producing_shelx_restraints.py ........... [ 84%]
test_recognise_pdb_ccd.py ............. [ 88%]
test_restraint_cif.py ............. [ 92%]
test_svg_diagram.py .ss [ 93%]
test_type_energys_for_rdkit.py ................... [ 98%]
test_utilities.py ..... [100%]
================= 347 passed, 3 skipped in 209.53s (0:03:29) =================
grade2_tests will run over 300 unit, functional and integration tests
written as part of the test-driven development used for coding Grade2.
Any failure is serious, please report it to buster-develop@globalphasing.com.
Please also see the Examples section for how to
run/test the grade2 command-line tool.
Advanced Configuration¶
If is possible to configure site-specific features for Grade2 by using the environment variables as set out below. Do not worry about these if are a new user of Grade2.
Grade2 environment variables¶
In general, environment variables are used to configure an installation of
Grade2 by specifying site-specific choices
that have can be set once and will not vary
from run to run. In contrast,
command-line arguments
are used to specify things that will vary for individual grade2 runs.
It is best Grade2 environment variables are are added to
the BUSTER setup_local.sh or setup_local.csh file, as explained
in the BUSTER Snapshot Installation Guide BUSTER configure section,
so that there are setup together with BUSTER. Users can of course set or
alter any of the environment variables if they wish by using
export or setenv (depending on the shell they use).
BDG_TOOL_MOGUL¶
BDG_TOOL_MOGUL is the environment variable that gives the location
of the Mogul executable. Grade2 does not use this executable but instead
uses it to find the location of CSD data and the CSD Python API direction.
Please see the Initial Configuration
section above for more detail.
BDG_GRADE2_PYTHON_VERSION¶
Grade2 is distributed with BUSTER within in a miniconda environment.
In order to work with the CSD Python API that is loaded at run time
from the CSD Python API distributed with the CSD the two
Python versions must be compatible. To use Grade2 following release
1.4.1 or above with a CSD installation
that predates 2023.2.0, released in July 2023 set the
environment variable BDG_GRADE2_PYTHON_VERSION to 3.7.
If not set, then BDG_GRADE2_PYTHON_VERSION currently defaults
to 3.9.
BDG_TOOL_CSD_PYTHON_API¶
BDG_TOOL_CSD_PYTHON_API is provided in case it is necessary
to provide the of the CSD Python API directory included in the CSD
distribution. If you have a standard CSD installation then the location
of CSD Python API will be found from BDG_TOOL_MOGUL, so it
is seldom necessary to set BDG_TOOL_CSD_PYTHON_API.
Please see the Initial Configuration
section above for more detail.
BDG_GRADE2_PUBCHEM_NAMES_ON_ACCEPT_SMILES_TO_WEB¶
The grade2 command line option --pubchem_names
does an online lookup the systematic (IUPAC) name for ligands
that occur in PubChem.
This online search involves uploading the
SMILES string of the molecule to the PubChem server.
For this reason, the --pubchem_names
option should not be used for confidential ligands.
To be extra careful, by default the --pubchem_names
option is deactivated until the environment variable
is set. To enable the --pubchem_names option set
BDG_GRADE2_PUBCHEM_NAMES_ON_ACCEPT_SMILES_TO_WEB
to "yes".
Apologies for the long name but it is chosen to explicitly show you have accepted that the ligand's SMILES string is uploaded to a public web server.
BDG_GRADE2_LIGAND_LOOKUP¶
The --lookup option provides a mechanism whereby
an external script
is invoked to look up details of a ligand from a database.
To use your own script, set environment variable BDG_GRADE2_LIGAND_LOOKUP
to the location of the script. Please see the
--lookup option for more details.
BDG_GRADE2_SSL_DISABLE_VERIFICATION¶
When BUSTER is installed on some Ubuntu Linux OS the
--lookup ID using the default
pubchem_g2_lookup_script.py script distributed with BUSTER can fail
terminating with an error message that includes SSL: CERTIFICATE_VERIFY_FAILED.
A similar error when the --pubchem_names option
is used. If the problem occurs set environment variable
BDG_GRADE2_SSL_DISABLE_VERIFICATION to "yes". This will
disable SSL verification for PubChem lookups and should
mean the options work. As you should not using the options
for any confidential ligands turning off verification should be fine.
BDG_GRADE2_CIF_LOOP_ALL¶
Set BDG_GRADE2_CIF_LOOP_ALL to "yes" to write all CIF categories as
loops, even if they only contain a single item. Currently this only
affects category gphl_chem_comp_info which
by default is written using key-value pairs as this makes inspection easier.
All other CIF categories are written as loops anyway.
BDG_GRADE2_TEST_WEB¶
By default, the grade2_tests tool does not run tests that use external
online services, as these can be unavailable because of maintenance or
network issues. Set BDG_GRADE2_CIF_LOOP_ALL to "yes" to turn
on the tests involving external online services. This will enable testing
of the --pubchem_names and the
--lookup ID options.