.. _chapter_stereochemistry:

********************************************************************************
Stereochemistry Perception
********************************************************************************

**OEChem TK** has the ability to store and retrieve stereochemical information for
atoms and bonds independent of two or three dimensional coordinates.
The current version of **OEChem TK** supports stereochemistry definitions of *handedness*
around tetrahedral centers, and *cis*/*trans* configuration around bonds.

The table below lists the available **OEChem TK** functions related to stereochemical
information.

   .. list-table::
      :widths: 100 200
      :header-rows: 1

      * - Name
        - Description

      * - :oe:func:`OEChem::OE3DToAtomStereo`
        - Set the stereochemistry at the chiral atoms of a molecule, as specified 
          by the molecule’s 3D coordinates.

      * - :oe:func:`OEChem::OE3DToBondStereo`
        - Set the stereochemistry at the chiral bonds of a molecule, as specified 
          by the molecule’s 3D coordinates. 

      * - :oe:func:`OEChem::OE3DToInternalStereo`
        - Assigns the stereochemistry of a molecule from its 3D coordinates.

      * - :oe:func:`OEChem::OEMDLClearBondStereo`
        - Clears the bond stereo fields from all bonds of a molecule.

      * - :oe:func:`OEChem::OEMDLCorrectBondStereo`
        - Corrects the wedge/hash bond assignment of the 2D molecule.

      * - :oe:func:`OEChem::OEMDLHasIncorrectBondStereo`
        - Checks whether the wedge/hash bond assignment of the 2D molecule is 
          inconsistent or ambiguous.

      * - :oe:func:`OEChem::OEMDLPerceiveBondStereo`
        - Assigns wedge and hash bonds to a connection table from the **OEChem TK** 
          stereochemistry of each atom of the 2D molecule.

      * - :oe:func:`OEChem::OEMDLStereoFromBondStereo`
        - Sets the **OEChem TK** stereochemistry of each atom of the 2D molecule 
          from the wedge and hash bonds in the connection table. 

      * - :oe:func:`OEChem::OEMDLStereoFromParity`
        - Sets the **OEChem TK** stereochemistry for each atom from the 
          MDL stereo parity information.

      * - :oe:func:`OEChem::OEPerceiveCIPStereo`
        - Perceives the Cahn-Ingold-Prelog descriptor for the given atom.

      * - :oe:func:`OEChem::OESetCIPStereo`
        - Sets the internal **OEChem TK** stereochemistry from the given CIP 
          atom stereo descriptor. 


.. _section_stereochemistry_atom:

Atom Chirality
================================================================================

The following two code snippets demonstrate how to loop over :term:`chiral<chiral atom>`
atoms using the :oe:cls:`OEIsChiralAtom<OEChem::OEIsChiralAtom>` functor and
the :oe:meth:`IsChiral<OEChem::OEAtomBase::IsChiral>` method of
the :oe:cls:`OEAtomBase<OEChem::OEAtomBase>` class.

.. oe:source:: PerceiveChiral.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-CHIRAL-ATOM-LOOP1

.. oe:source:: PerceiveChiral.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-CHIRAL-ATOM-LOOP2

.. oe:source:: PerceiveChiral.py
   :language: python
   :noindent:
   :frag:     SNIPPET-CHIRAL-ATOM-LOOP1

.. oe:source:: PerceiveChiral.py
   :language: python
   :noindent:
   :frag:     SNIPPET-CHIRAL-ATOM-LOOP2

.. oe:source:: PerceiveChiral.java
   :language: java
   :noindent:
   :frag:     SNIPPET-CHIRAL-ATOM-LOOP1

.. oe:source:: PerceiveChiral.java
   :language: java
   :noindent:
   :frag:     SNIPPET-CHIRAL-ATOM-LOOP2

.. oe:source:: PerceiveChiral.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-CHIRAL-ATOM-LOOP1

.. oe:source:: PerceiveChiral.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-CHIRAL-ATOM-LOOP2


.. warning::

   When a molecule is imported from a file, its atom and bond chirality are not
   automatically perceived, the user has to call :oe:func:`OEPerceiveChiral<OEChem::OEPerceiveChiral>`
   explicitly.

Atom Stereochemistry
================================================================================

..  The definition *handedness* in **OEChem TK** is demonstrated pictorially
    in the following table:

    .. list-table::
       :widths: 40 40
       :header-rows: 1

       * -  R-configuration
         -  S-configuration
       * - .. image:: images/stereo-example-R.png
              :scale: 100
              :align: center
         - .. image:: images/stereo-example-S.png
          :scale: 100
          :align: center
       * - .. image:: images/OEAtomStereo_RightHanded.*
          :scale: 100
          :align: center
         - .. image:: images/OEAtomStereo_LeftHanded.*
          :scale:  100
          :align:  center
       * - :oe:const:`OEChem::OEAtomStereo::RightHanded` (clockwise)
         - :oe:const:`OEChem::OEAtomStereo::LeftHanded` (counter-clockwise)

    Looking down the bond between atom number one (hydrogen) and the central atom (carbon),
    *handedness* is defined as the direction of travel from atom number
    two (chlorine) to atom number three (bromine).
    The direction of travel must always be along the acute angle formed by atom two (chlorine),
    the central atom (carbon), and atom three (bromine).
    Right handed and left handed directions of travel can also be thought of as *clockwise*
    and *counterclockwise*, respectively.


Stereochemistry around atoms can be set and retrieved by the
:oe:meth:`OEChem::OEAtomBase::SetStereo` and :oe:meth:`OEChem::OEAtomBase::GetStereo`
methods, respectively.
The :oe:meth:`OEChem::OEAtomBase::HasStereoSpecified` method returns a boolean value
that indicates whether stereochemical information of a particular type has been
stored for an atom.
**OEChem TK** currently only supports :oe:const:`OEChem::OEAtomStereo::Tetrahedral`
atom stereochemistry class.

Note that the setting and retrieval of atom stereo requires
a vector containing pointers to the neighboring atoms as the first argument.
The *handedness* value returned from :oe:meth:`OEChem::OEAtomBase::GetStereo` will
depend on the order of the neighboring atoms as they appear in the
passed vector.

The first neighbor atom in the vector passed to :oe:meth:`OEChem::OEAtomBase::GetStereo`
is taken as atom number one for the determination of *handedness*.
Likewise, subsequent atoms in the neighbor atom vector are assigned
sequentially to positions in the *handedness* definition.
Although, three neighboring atoms are sufficient to determine the
*handedness* around a trigonal pyramidal or tetrahedral center, either three or four
atoms can be provided to the :oe:meth:`OEChem::OEAtomBase::GetStereo` function
when requesting a value for tetrahedral chirality.
The following table shows the return values of :oe:meth:`OEChem::OEAtomBase::GetStereo`
method by passing the neighbor atoms in different order.

======================== ================= =================
neighbor order           [C@@H](Cl)(Br)N   [C@H](Cl)(Br)N   
======================== ================= =================
H Cl Br N                right handed      left handed
H Br Cl N                left handed       right handed
H Cl N Br                left handed       right handed
...                      ...               ...
Cl Br N                  left handed       right handed
Br Cl N                  right handed      left handed
Cl N Br                  right handed      left handed
======================== ================= =================

.. note::

   The definition of *handedness* for tetrahedral stereochemistry
   does not imply :term:`chirality<chiral atom>` around a tetrahedral center, but rather
   indicates relative positions of neighboring atoms.

The following code sample demonstrates looping over atoms, testing for
atoms that have tetrahedral stereochemistry, and printing out the
value of the tetrahedral stereochemistry (either
:oe:const:`OEChem::OEAtomStereo::RightHanded`,
:oe:const:`OEChem::OEAtomStereo::LeftHanded`, or
:oe:const:`OEChem::OEAtomStereo::Undefined`).  See also the input
structure depicted in :ref:`Figure: Atom stereo<figure_stereo_atom>`.

.. oe:source:: PrintAtomStereo.cpp
   :language: c++
   :refnum:   1
   :caption:  Accessing atom stereo information
   :frag:     SNIPPET

.. oe:source:: PrintAtomStereo.py
   :language: python
   :refnum:   1
   :caption:  Accessing atom stereo information
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-PrintAtomStereo.py>`



.. oe:source:: PrintAtomStereo.java
   :language: java
   :refnum:   1
   :caption:  Accessing atom stereo information
   :frag:     SNIPPET

.. oe:source:: PrintAtomStereo.cs
   :language: csharp
   :refnum:   1
   :caption:  Accessing atom stereo information
   :frag:     SNIPPET

The output of the preceding program is the following:

.. oe:language:: c++

   .. code-block:: bash

      Atom: 1 chiral=0 stereo=left handed
      Atom: 4 chiral=1 stereo=right handed
      Atom: 7 chiral=1 stereo=undefined
      Atom: 10 chiral=0 stereo=left handed
      Atom: 14 chiral=0 stereo=right handed


.. oe:language:: python

   .. code-block:: bash

      Atom: 1 chiral= False stereo= left handed
      Atom: 4 chiral= True stereo= right handed
      Atom: 7 chiral= True stereo= undefined
      Atom: 10 chiral= False stereo= left handed
      Atom: 14 chiral= False stereo= right handed

.. oe:language:: java csharp

   .. code-block:: bash

      Atom: 1 chiral=false stereo=left handed
      Atom: 4 chiral=true stereo=right handed
      Atom: 7 chiral=true stereo=undefined
      Atom: 10 chiral=false stereo=left handed
      Atom: 14 chiral=false stereo=right handed

.. _figure_stereo_atom:

.. figure:: images/AtomStereo.*
   :scale:  100
   :align:  center

   **Atom stereo**

As mentioned before, tetrahedral stereochemistry (*i.e.* specified
atom stereo) does not imply chirality around a tetrahedral center.
For example atoms 1, 10 and 14 in :ref:`Figure: Atom
stereo<figure_stereo_atom>` have specified atom stereo, even though
they are non-chiral.  *Vice versa*, atom can be :term:`chiral<chiral atom>`
but with unspecified atom stereo configuration (such as atom 7
in :ref:`Figure: Atom stereo<figure_stereo_atom>` ).  Atoms 1 and 6
are non-chiral but they have atom stereo information and they are
relative to each other.

The following example shows how to manually set the atom stereo of atom 7 (chiral, undefined)
to *left* by the :oe:meth:`OEChem::OEAtomBase::SetStereo` method.

.. oe:source:: SetAtomStereo.cpp
   :language: c++
   :refnum:   2
   :caption:  Setting atom stereo information
   :frag:     SNIPPET

.. oe:source:: SetAtomStereo.py
   :language: python
   :refnum:   2
   :caption:  Setting atom stereo information
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-SetAtomStereo.py>`



.. oe:source:: SetAtomStereo.java
   :language: java
   :refnum:   2
   :caption:  Setting atom stereo information
   :frag:     SNIPPET

.. oe:source:: SetAtomStereo.cs
   :language: csharp
   :refnum:   2
   :caption:  Setting atom stereo information
   :frag:     SNIPPET

The output of the preceding program is the following:

.. code-block:: bash

   [H][C@@]1([C@@H](C[C@H](CN1)N)CO[C@H]2CC[C@@H](CC2)O)[H]

Just as in :oe:meth:`OEChem::OEAtomBase::GetStereo`, the vector of neighbor atoms provide
the references about which the *handedness* is defined.
The first of the integer arguments is the stereochemistry type
(*i.e.* :oe:const:`OEChem::OEAtomStereo::Tetrahedral` (or just  :oe:const:`OEChem::OEAtomStereo::Tetra`) ,
and the second is the associated value
(*i.e.* :oe:const:`OEChem::OEAtomStereo::Right` or  :oe:const:`OEChem::OEAtomStereo::Left`).

.. _section_chirality_bond:

Bond Chirality
================================================================================

The following two code snippets demonstrate how to loop over :term:`chiral<chiral bond>`
bonds using the :oe:cls:`OEIsChiralBond<OEChem::OEIsChiralBond>` functor and
the :oe:meth:`IsChiral<OEChem::OEBondBase::IsChiral>` method of
the :oe:cls:`OEBondBase<OEChem::OEBondBase>` class.

.. oe:source:: PerceiveChiral.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-CHIRAL-BOND-LOOP1

.. oe:source:: PerceiveChiral.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-CHIRAL-BOND-LOOP2

.. oe:source:: PerceiveChiral.py
   :language: python
   :noindent:
   :frag:     SNIPPET-CHIRAL-BOND-LOOP1

.. oe:source:: PerceiveChiral.py
   :language: python
   :noindent:
   :frag:     SNIPPET-CHIRAL-BOND-LOOP2

.. oe:source:: PerceiveChiral.java
   :language: java
   :noindent:
   :frag:     SNIPPET-CHIRAL-BOND-LOOP1

.. oe:source:: PerceiveChiral.java
   :language: java
   :noindent:
   :frag:     SNIPPET-CHIRAL-BOND-LOOP2

.. oe:source:: PerceiveChiral.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-CHIRAL-BOND-LOOP1

.. oe:source:: PerceiveChiral.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-CHIRAL-BOND-LOOP2

.. warning::

   When a molecule is imported from a file, its atom and bond chirality are not
   automatically perceived, the user has to call :oe:func:`OEPerceiveChiral<OEChem::OEPerceiveChiral>`
   explicitly.

.. _section_stereochemistry_bond:

Bond Stereochemistry
================================================================================

Stereochemistry around bonds can be specified in a similar fashion to
stereochemistry about atom centers.
The request for stereochemistry of a particular class can be made of an
:ref:`OEBondBase <OEChem_OEBondBase>` using the method :oe:meth:`OEChem::OEBondBase::HasStereoSpecified`.
**OEChem TK** currently only supports :oe:const:`OEChem::OEBondStereo::CisTrans`
bond stereochemistry class that defines whether the configuration
of two atoms around a non-rotatable bond is *cis* or *trans*.
If a bond has associated stereochemical data, it can be retrieved
using :oe:meth:`OEChem::OEBondBase::GetStereo` method.

The following code sample demonstrates a loop over bonds that tests for
bonds with associated stereochemistry, and retrieval of whether the
neighboring atoms are *cis* or *trans* relative to one another.  (See
also the input structure depicted in :ref:`Figure: Bond
stereo<figure_stereo_bond>`.

.. oe:source:: PrintBondStereo.cpp
   :language: c++
   :refnum:   3
   :caption:  Accessing bond stereo information
   :frag:     SNIPPET

.. oe:source:: PrintBondStereo.py
   :language: python
   :refnum:   3
   :caption:  Accessing bond stereo information
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-PrintBondStereo.py>`



.. oe:source:: PrintBondStereo.java
   :language: java
   :refnum:   3
   :caption:  Accessing bond stereo information
   :frag:     SNIPPET

.. oe:source:: PrintBondStereo.cs
   :language: csharp
   :refnum:   3
   :caption:  Accessing bond stereo information
   :frag:     SNIPPET


The output of the preceding program is the following:

.. code-block:: bash

   Atoms: 0 and 3 are trans
   Atoms: 2 and 5 are cis

.. _figure_stereo_bond:

.. figure:: images/BondStereo.*
   :scale:  100
   :align:  center

   **Bond stereo**


Note that even though the double bond defined by atoms 4--5--6--7
is depicted as *trans* (see :ref:`Figure: Bond stereo<figure_stereo_bond>`)
it is still considered undefined, since no stereo information is encoded for this bond
in the input SMILES.

The following example shows how to manually set this missing bond stereo to *trans*
by the :oe:meth:`OEChem::OEBondBase::SetStereo` method.

.. oe:source:: SetBondStereo.cpp
   :language: c++
   :refnum:   4
   :caption:  Setting bond stereo information
   :frag:     SNIPPET

.. oe:source:: SetBondStereo.py
   :language: python
   :refnum:   4
   :caption:  Setting bond stereo information
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-SetBondStereo.py>`



.. oe:source:: SetBondStereo.java
   :language: java
   :refnum:   4
   :caption:  Setting bond stereo information
   :frag:     SNIPPET

.. oe:source:: SetBondStereo.cs
   :language: csharp
   :refnum:   4
   :caption:  Setting bond stereo information
   :frag:     SNIPPET

The first integer argument of the method :oe:meth:`OEChem::OEBondBase::SetStereo`
is used to specify the type of stereochemistry (*i.e.*
:oe:const:`OEChem::OEBondStereo::CisTrans`).
The second integer argument specifies the bond stereo configuration (*i.e.*
:oe:const:`OEChem::OEBondStereo::Cis` or :oe:const:`OEChem::OEBondStereo::Trans`)

The output of the preceding program is the following:

::

   C/C=C/C=C\C=C\C

.. _section_stereochemistry_CIP:

CIP Stereo Perception
================================================================================

The following two examples demonstrate how to perceive CIP (Cahn–Ingold–Prelog)
atom and bond stereo information from the molecules created by the SMILES 
representation. If the input molecule has 3D coordinates, the :oe:func:`OEChem::OE3DToInternalStereo` 
function should be called.

.. _figure_cip_atom_stereo:

.. figure:: images/CIPAtomStereo.*
   :scale:  100
   :align:  center

   **CIP atom stereo**

.. oe:source:: PrintCIPAtomStereo.cpp
   :language: c++
   :refnum:   5
   :caption:  Perceiving CIP atom stereo information
   :frag:     SNIPPET

.. oe:source:: PrintCIPAtomStereo.py
   :language: python
   :refnum:   5
   :caption:  Perceiving CIP atom stereo information
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-PrintCIPAtomStereo.py>`



.. oe:source:: PrintCIPAtomStereo.java
   :language: java
   :refnum:   5
   :caption:  Perceiving CIP atom stereo information
   :frag:     SNIPPET

.. oe:source:: PrintCIPAtomStereo.cs
   :language: csharp
   :refnum:   5
   :caption:  Perceiving CIP atom stereo information
   :frag:     SNIPPET

The :oe:func:`OEChem::OEPerceiveCIPStereo` function detects the Cahn-Ingold-Prelog
descriptor of the given atom and returns a value from the
:oe:constns:`OEChem::OECIPAtomStereo` namespace.

The output of :oe:src:`Listing 5<SNIPPET-PrintCIPAtomStereo>` is the following:
(See also the input structure depicted in :ref:`Figure: CIP atom stereo<figure_cip_atom_stereo>`.

::

  atom 1 is R
  atom 4 is S
  atom 8 is a CIP stereo center without specified stereochemistry
  atom 12 is not a CIP stereo center
  atom 17 is not a CIP stereo center


.. _figure_cip_bond_stereo:

.. figure:: images/CIPBondStereo.*
   :scale:  100
   :align:  center

   **CIP bond stereo**

.. oe:source:: PrintCIPBondStereo.cpp
   :language: c++
   :refnum:   6
   :caption:  Perceiving CIP bond stereo information
   :frag:     SNIPPET

.. oe:source:: PrintCIPBondStereo.py
   :language: python
   :refnum:   6
   :caption:  Perceiving CIP bond stereo information
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-PrintCIPBondStereo.py>`



.. oe:source:: PrintCIPBondStereo.java
   :language: java
   :refnum:   6
   :caption:  Perceiving CIP bond stereo information
   :frag:     SNIPPET

.. oe:source:: PrintCIPBondStereo.cs
   :language: csharp
   :refnum:   6
   :caption:  Perceiving CIP bond stereo information
   :frag:     SNIPPET

The :oe:func:`OEChem::OEPerceiveCIPStereo` function detects the Cahn-Ingold-Prelog
descriptor of the given bond and returns a value from the
:oe:constns:`OEChem::OECIPBondStereo` namespace.

The output of :oe:src:`Listing 6<SNIPPET-PrintCIPBondStereo>` is the following:
(See also the input structure depicted in :ref:`Figure: CIP bond stereo<figure_cip_bond_stereo>`.

::

  bond 2 is not a CIP stereo center
  bond 7 is Z
  bond 12 is E
  bond 17 is a CIP stereo center without specified stereochemistry

