.. include:: ../toolkit-substitutions

.. _chapter_aromaticity:

********************************************************************************
Aromaticity Perception
********************************************************************************

.. _section_aromaticity_huckel:

Aromaticity and  |Huckel|'s rule
================================================================================

.. index: aromaticity models

**OEChem TK**'s aromaticity perception routines are based around the |Huckel|'s
rule that defines cyclic conjugated systems with :math:`(4N+2)` number of
:math:`\pi` electrons as aromatic (where :math:`N` is zero or any positive integer).

Aromaticity can be set using the
:oe:func:`OEAssignAromaticFlags<OEChem::OEAssignAromaticFlags>` function,
which takes an :oe:cls:`OEMolBase<OEChem::OEMolBase>` argument.
The :oe:func:`OEAssignAromaticFlags<OEChem::OEAssignAromaticFlags>` sets
the aromaticity flags on atoms and bonds using an aromaticity model.
(For the list of available aromaticity models in *OEChem TK** see
section :ref:`section_aromaticity_models`. )


.. oe:source:: PerceiveAromaticity.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-AROM-PERCEIVE

..  oe:language:: python

    .. oe:source:: PerceiveAromaticity.py
       :language: python
       :noindent:
       :frag:     SNIPPET-AROM-PERCEIVE

.. oe:source:: PerceiveAromaticity.py
   :language: python
   :caption:  Complete Code for PerceiveAromaticity.py

..  oe:language:: python

    ..  admonition:: Download PerceiveAromaticity.py

        :download:`PerceiveAromaticity.py <../../../../wrappers/python/docexamples/oechem/PerceiveAromaticity.py>`

.. oe:source:: PerceiveAromaticity.java
   :language: java
   :noindent:
   :frag:     SNIPPET-AROM-PERCEIVE

.. oe:source:: PerceiveAromaticity.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-AROM-PERCEIVE

.. hint::

   The :oe:func:`OEChem::OESmilesToMol` function automatically perceives
   the aromaticity of the molecule  using the *default*
   :oe:const:`OEChem::OEAroModel::OpenEye` aromaticity model.

The following two code snippets demonstrate how to loop over aromatic atoms
using the :oe:cls:`OEIsAromaticAtom<OEChem::OEIsAromaticAtom>` functor and
the :oe:meth:`IsAromatic<OEChem::OEAtomBase::IsAromatic>` method of
the :oe:cls:`OEAtomBase<OEChem::OEAtomBase>` class.

.. oe:source:: PerceiveAromaticity.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-AROM-LOOP1

.. oe:source:: PerceiveAromaticity.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-AROM-LOOP2

.. oe:source:: PerceiveAromaticity.py
   :language: python
   :noindent:
   :frag:     SNIPPET-AROM-LOOP1

.. oe:source:: PerceiveAromaticity.py
   :language: python
   :noindent:
   :frag:     SNIPPET-AROM-LOOP2

.. oe:source:: PerceiveAromaticity.java
   :language: java
   :noindent:
   :frag:     SNIPPET-AROM-LOOP1

.. oe:source:: PerceiveAromaticity.java
   :language: java
   :noindent:
   :frag:     SNIPPET-AROM-LOOP2

.. oe:source:: PerceiveAromaticity.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-AROM-LOOP1

.. oe:source:: PerceiveAromaticity.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-AROM-LOOP2


The aromatic bonds of a molecule can similarly be accessed using the
:oe:cls:`OEIsAromaticBond<OEChem::OEIsAromaticBond>` functor and the
:oe:meth:`IsAromatic<OEChem::OEBondBase::IsAromatic>` method of the
:oe:cls:`OEBondBase<OEChem::OEBondBase>` class.
For more information about functors see chapter :ref:`chapter_predicates`.

The user can also set the atom and bond aromaticity flags manually using the
:oe:meth:`OEChem::OEAtomBase::SetAromatic` and
:oe:meth:`OEChem::OEBondBase::SetAromatic` methods.

.. _section_aromaticity_models:

Aromaticity Models in OEChem TK
================================================================================

The :oe:func:`OEAssignAromaticFlags<OEChem::OEAssignAromaticFlags>` function can
also take an aromaticity model constant as an argument to perceive various
aromaticity models.
The following aromaticity models are available in **OEChem TK**:

#. :oe:const:`OpenEye<OEChem::OEAroModel::OpenEye>` (default model)

#. :oe:const:`Daylight<OEChem::OEAroModel::Daylight>`

#. :oe:const:`Tripos<OEChem::OEAroModel::Tripos>`

#. :oe:const:`MDL<OEChem::OEAroModel::MDL>`

#. :oe:const:`MMFF<OEChem::OEAroModel::MMFF>`

The following table demonstrates the differences between the five available aromaticity models.

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

**Table footnotes:**

**[1]**
*Atomic elements such as Te, B, Se are not available in the  MMFF and Tripos
aromaticity models.*

**[2]**
*Only two out of the four five-membered rings are recognized as aromatic.*


..
   INTERNAL DOCUMENTATION! DO NOT PUBLISH OR EXPOSE VIA BETA-DOCS WITHOUT REVIEW/CONSENT FROM: KB, JH, BL

..
   The following table demonstrates the differences between the five available aromaticity
   models: each cell identifies the number of perceived aromatic bonds versus the total number of bonds from each model.

   **MDL classic** aromaticity is the legacy aromatic perception from MDL that identified alternating single and double 6-membered rings without regard for atom types.

   **MDL enhanced** aromaticity is an augmented perception from MDL that identified alternating single and double 6-membered rings, and added 5-membered hetero- or C-anion rings, and the perimeter ring of azulene.  Atom types were generally not considered except for the 5-ring case.

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

   **Table footnotes:**

   **[1]**
   *Atomic elements such as Te, B, Se are not available in the  MMFF and Tripos
   aromaticity models.*

   **[2]**
   *Correct for MDL classic aromaticity*

   **[3]**
   *Incorrect for MDL classic aromaticity*

   **[4]**
   *Correct for MDL enhanced aromaticity*

   **[5]**
   *Incorrect for MDL enhanced aromaticity*

   **[6]**
   *Partially correct: MDL enhanced aromaticity - only one pyrrole ring would have been perceived as aromatic; MDL classic aromaticity - no bonds would have been considered aromatic*


The code in :oe:src:`Listing 1<SNIPPET-Aromaticity>` demonstrates how to perceive aromaticity
with these available models.

.. oe:source:: Aromaticity.cpp
   :language: c++
   :refnum:   1
   :caption:  Aromaticity perception with various models
   :frag:     SNIPPET

.. oe:source:: Aromaticity.py
   :language: python
   :refnum:   1
   :caption:  Aromaticity perception with various models
   :frag:     SNIPPET

.. oe:language:: python

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



.. oe:source:: Aromaticity.java
   :language: java
   :refnum:   1
   :caption:  Aromaticity perception with various models
   :frag:     SNIPPET

.. oe:source:: Aromaticity.cs
   :language: csharp
   :refnum:   1
   :caption:  Aromaticity perception with various models
   :frag:     SNIPPET


Since these models define aromaticity rules differently, the generated :term:`canonical SMILES`
depend on the applied aromaticity models.
The output of :oe:src:`Listing 1<SNIPPET-Aromaticity>` is the following:

.. code-block:: bash

   OEAroModel::OpenEye  : c1c[nH]c(cc1=O)c2cocc2c3cncnc3
   OEAroModel::Daylight : c1c[nH]c(cc1=O)c2cocc2c3cncnc3
   OEAroModel::Tripos   : c1c(cncn1)C2=COC=C2C3=CC(=O)C=CN3
   OEAroModel::MMFF     : c1c(cncn1)c2cocc2C3=CC(=O)C=CN3
   OEAroModel::MDL      : c1c(cncn1)C2=COC=C2C3=CC(=O)C=CN3

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

   *Example of aromaticity perception with different models*


.. _section_aromaticity_clearing:

Clearing Aromaticity
================================================================================

.. index:: Kekule SMILES

The aromatic property of all atoms and bonds in a molecule, can conveniently be
cleared (*i.e.* set to value false) by calling the
:oe:func:`OEClearAromaticFlags<OEChem::OEClearAromaticFlags>` function.
This is useful when  writing the |Kekule| form of a SMILES string, which can be done
by calling :oe:func:`OEClearAromaticFlags<OEChem::OEClearAromaticFlags>` before
calling :oe:func:`OEKekulize<OEChem::OEKekulize>` and
:oe:func:`OECreateSmiString<OEChem::OECreateSmiString>` functions.

.. oe:source:: ClearAromaticity.cpp
   :language: c++
   :refnum:   2
   :caption:  Clearing aromaticity
   :frag:     SNIPPET

.. oe:source:: ClearAromaticity.py
   :language: python
   :refnum:   2
   :caption:  Clearing aromaticity
   :frag:     SNIPPET

.. oe:language:: python

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



.. oe:source:: ClearAromaticity.java
   :language: java
   :refnum:   2
   :caption:  Clearing aromaticity
   :frag:     SNIPPET

.. oe:source:: ClearAromaticity.cs
   :language: csharp
   :refnum:   2
   :caption:  Clearing aromaticity
   :frag:     SNIPPET


The output of :oe:src:`Listing 2<SNIPPET-ClearAromaticity>` is the following:

.. code-block:: bash

   Canonical smiles : c1cnccn1
   Kekule smiles    : C1=CN=CC=N1

.. _section_aromaticity_readwrite:

Input/Output Aromaticity
================================================================================

Since :oe:func:`OEParseSmiles<OEChem::OEParseSmiles>` preserves the aromaticity
present (or absent) in the input SMILES string,
the :oe:func:`OEChem::OEClearAromaticFlags` or
the :oe:func:`OEChem::OEAssignAromaticFlags` have to be explicitly
called to remove or perceive aromaticity in a molecule, respectively.
(See examples in :oe:src:`Listing 1<SNIPPET-Aromaticity>` and :oe:src:`Listing 2<SNIPPET-ClearAromaticity>`)

However, when a molecule is imported from a file with a high-level
:oe:func:`OEReadMolecule<OEChem::OEReadMolecule>` function,
atom and bond aromaticity is automatically perceived using the default
:oe:const:`OEAroModelOpenEye<OEChem::OEAroModel::OpenEye>` model.

As mentioned before (in section :ref:`section_molreadwrite_proppreserv`), the
high-level :oe:func:`OEWriteMolecule`<OEChem::OEWriteMolecule>` writer function
may automatically update atom and bond properties (including aromaticity)
in order to standardize the exported molecules.
The following table shows the aromaticity models associated with various file
formats.

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

   * - File Format
     - Default Output Aromaticity Models

   * - :oe:const:`OEChem::OEFormat::CAN`
     - :oe:const:`OEChem::OEAroModel::OpenEye`

   * - :oe:const:`OEChem::OEFormat::CDX`
     - :oe:const:`OEChem::OEAroModel::OpenEye`

   * - :oe:const:`OEChem::OEFormat::CSV`
     - :oe:const:`OEChem::OEAroModel::OpenEye`

   * - :oe:const:`OEChem::OEFormat::FASTA`
     -  [1]

   * - :oe:const:`OEChem::OEFormat::ISM`
     - :oe:const:`OEChem::OEAroModel::OpenEye`

   * - :oe:const:`OEChem::OEFormat::MDL`
     - :oe:func:`OEChem::OEClearAromaticFlags`

   * - :oe:const:`OEChem::OEFormat::MF`
     - [1]

   * - :oe:const:`OEChem::OEFormat::MMOD`
     - [1]

   * - :oe:const:`OEChem::OEFormat::MOL2`
     - :oe:const:`OEChem::OEAroModel`

   * - :oe:const:`OEChem::OEFormat::MOL2H`
     - :oe:const:`OEChem::OEAroModel::Tripos`

   * - :oe:const:`OEChem::OEFormat::MOPAC`
     - [1]

   * - :oe:const:`OEChem::OEFormat::OEB`
     - [1]

   * - :oe:const:`OEChem::OEFormat::PDB`
     - [1]

   * - :oe:const:`OEChem::OEFormat::SDF`
     - :oe:func:`OEChem::OEClearAromaticFlags`

   * - :oe:const:`OEChem::OEFormat::SLN`
     - :oe:const:`OEChem::OEAroModel::Tripos`

   * - :oe:const:`OEChem::OEFormat::SMI`
     - :oe:const:`OEChem::OEAroModel::OpenEye`

   * - :oe:const:`OEChem::OEFormat::XYZ`
     - [1]

   * - :oe:const:`OEChem::OEFormat::INCHI`
     - [1]

   * - :oe:const:`OEChem::OEFormat::INCHIKEY`
     - [1]

**Table footnote:**

**[1]** *The aromaticity model is not changed by the associated molecule writer.*


The following snippet shows how to overwrite the default aromaticity model
of a specific file format.

.. oe:source:: ChangeAromaticityFlavor.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-AROM-CHANGEFLAVOR

.. oe:source:: ChangeAromaticityFlavor.py
   :language: python
   :noindent:
   :frag:     SNIPPET-AROM-CHANGEFLAVOR

.. oe:source:: ChangeAromaticityFlavor.java
   :language: java
   :noindent:
   :frag:     SNIPPET-AROM-CHANGEFLAVOR

.. oe:source:: ChangeAromaticityFlavor.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-AROM-CHANGEFLAVOR

This will produce the following output:

.. code-block:: bash

   c1c[nH]cc1CO
   C1=CNC=C1CO

.. seealso::

   * [Lloyd-1996]_
