.. _examples:


********
Examples
********

From SMILES string
==================

To produce restraints for a given `SMILES`_ string then
run ``grade2``  on the command-line followed by the SMILES
surrounded by single quotes: ``grade2 'SMILES'``, for example:

::

    $ grade2 'Oc1ccccc1'

Please note that the dollar symbol ``$`` above represents the command prompt.
This will produce  CIF-format restraint dictionary
``LIG.restraints.cif`` with the default PDB chemical component id
(aka residue name or 3-letter code) of ``LIG``. To set the
3-letter code use the command-line option :ref:`--resname <resname>`, for
instance if you wanted the 3-letter residue name ``DRG``:

::

    $ grade2 'Oc1ccccc1' --resname LIG

In this case the output files will be called ``LIG.restraints.cif``.

In practice, it is important to look at the :ref:`terminal output <terminal output>`
produced as you will be warned that there is already a wwPDB compound
definition for this SMILES  string:
it is phenol ``IPH`` https://www.rcsb.org/ligand/IPH "phenol". So
in this case it would be much better to follow the next section
and produce a restraint dictionary for ``IPH``.
Please see the :ref:`Outputs` chapter for more details.


.. _VIA_restraints:

Producing restraints for an existing PDB ligand
===============================================

To produce a restraint dictionary for a compound that already exists
in the PDB it is best to use the :ref:`--PDB_ligand <PDB_ligand>` option.
For example, to produce a restraint dictionary for Sildenafil_
that has the PDB chemical component ID ``VIA`` run:

 ::

    $ grade2 --PDB_ligand VIA

This will produce output using the
`wwPDB Chemical Component Dictionary`_
(CCD) compound record for ``VIA`` (see https://www.rcsb.org/ligand/VIA
for an overview).
Grade2 will download the wwPDB CCD CIF file for the compound from either
PDBeChem: https://www.ebi.ac.uk/pdbe-srv/pdbechem/ or from
Ligand Expo: http://ligand-expo.rcsb.org/.
The output restraint dictionary will be called ``VIA.restraints.cif`` and
other files will be named ``VIA.*``, see the
:ref:`outputs` chapter. In practice, it is important to look at the
:ref:`terminal output` produced as you will be warned that there is
a nitrogen atom that has been charged by adding a proton to it.
If instead you wanted results for the original uncharged molecule then
use the  :ref:`--no_charging <no_charging>` option:

 ::

    $ grade2 --PDB_ligand VIA --force_overwrite --no_charging

The  :ref:`--force_overwrite <force_overwrite>` option
allows Grade2 to overwrite any existing ``VIA.*`` grade2 files.
If you prefer less typing, as each of the options used has a short single-character
alternative so the above command is equivalent to:

 ::

    $ grade2 -P VIA -f -N

In all cases, the output restraint dictionary will be called ``VIA.restraints.cif``
and other files will be named ``VIA.*``, see the
:ref:`outputs` chapter for more details.



Producing restraints for a compound from a chemical database
============================================================

Suppose you want to produce restraints for a compound from a chemical database
(either public or corporate). Let us take Sildenafil_
as an example case. The PubChem entry
for Sildenafil is https://pubchem.ncbi.nlm.nih.gov/compound/135398744.
Given that PubChem provides reliable model 3D coordinates for its
compounds it is most sensible to use the 3D SDF coordinates download
option to download Conformer3D_CID_135398744.sdf_.
``grade2`` can be run for the downloaded SDF file, using the :ref:`--in <in>` option:

::

    $ grade2 --in Conformer3D_CID_135398744.sdf

This command will result in outputs with the default PDB chemical component id
(aka residue name or 3-letter code) of ``LIG``. It is normally best to
use the command-line option :ref:`--resname <resname>` to set the 3-letter
code, for instance here to ``S_L``.

::

    $ grade2 --in Conformer3D_CID_135398744.sdf --resname S_L

This will result in output files whose names starting ``S_L.``.
Suppose you wanted the output files to be named ``135398744.*``,
this can be achieved using the :ref:`--out <out>` option:

::

    $ grade2 --in Conformer3D_CID_135398744.sdf --resname S_L \
      --out 135398744

Furthermore, as in this case we know both an appropriate name for the compound
and a database ID, it is a good idea to set these, using the
:ref:`--resname <resname>` and  :ref:`--database_id <database_id>` options:

::

    $ grade2 --in Conformer3D_CID_135398744.sdf --resname S_L \
      --out 135398744 --name Sildenafil --database_id "CID 135398744"

If you prefer less typing each of the options used has a short single-character
alternative so the above command is equivalent to:

::

    $ grade2 -i Conformer3D_CID_135398744.sdf -r S_L \
      -o 135398744 -n Sildenafil -d "CID 135398744"


.. _check_sidlenafil_from_pubchem:


In practice, it is important to look at the :ref:`terminal output <terminal output>`
produced as you will be warned that there is already a wwPDB compound
definition for Sildenafil in output lines:

::

    $ grade2 -i Conformer3D_CID_135398744.sdf -r S_L \
      -o 135398744 -n Sildenafil -d "CID 135398744"
     ############################################################################
     ##   [grade2] ligand restraint dictionary generation
     ############################################################################
     ... (output abbreviated)
     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"
     ... (output abbreviated)

So it is best to use a restraint dictionary for the PDB chemical component ``VIA``
to ensure compatibility. Please see the :ref:`previous section <VIA_restraints>` that explains
how to generate a restraint dictionary for ``VIA``.


.. _`SMILES`: https://en.wikipedia.org/wiki/Simplified_molecular-input_line-entry_system.
.. _`wwPDB Chemical Component Dictionary`: https://www.wwpdb.org/data/ccd
.. _Sildenafil: https://en.wikipedia.org/wiki/Sildenafil
.. _Conformer3D_CID_135398744.sdf: https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/CID/135398744/record/SDF/?record_type=3d&response_type=save&response_basename=Conformer3D_CID_135398744