.. _chapter_molalign:

*******************************************************************************
Molecule Alignment
*******************************************************************************

The following three code examples demonstrate how to align molecules either based
on:

* maximum common substructure (:oe:src:`Listing 1<SNIPPET-MCS-ALIGN-MCSAlign>`),
* substructure matches (:oe:src:`Listing 2<SNIPPET-SUB-SEARCH-ALIGN-SubSearchAlign>`), or
* molecular similarity (:oe:src:`Listing 3<SNIPPET-FINGERPRINT-ALIGN-FPAlign>`).

Molecule Alignment Based on MCS
================================================================================

The :ref:`Figure: Example of depiction without alignment<figure_mcss_no_alignment>`
is generated by highlighting the maximum common substructure of two molecules (MCS),
but keeping the original orientation of the compounds.

.. _figure_mcss_no_alignment:

.. figure:: images/MCSNoAlignment.*
   :align:  center

   **Example of depiction without alignment**

The :oe:src:`Listing 1<SNIPPET-MCS-ALIGN-MCSAlign>` code example shows how to align these
two molecules by their maximum common substructures (*i.e.* by the
highlighted atoms and bonds in
:ref:`Figure: Example of depiction without alignment<figure_mcss_no_alignment>`).

* First, two molecules are initialized from SMILES string and
  prepared for depiction.

* A :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object is initialized with the
  *reference* 2D molecule onto which the *fit* molecule will be aligned.

* An :ref:`OEImageGrid <OEDepict_OEImageGrid>` object is constructed that allows
  to render the two molecules in a grid next to each other.

* The *fit* molecule is then aligned to the *reference* by
  calling the :oe:func:`OEDepict::OEPrepareAlignedDepiction`
  function that performs MCS search and then aligns the *fit* molecule
  to the *reference* based on the detected common substructure(s).

* An :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` object is initialized that
  stores the properties determine how the molecules are rendered.
  In order to render the molecules in equal size the smallest
  depiction scaling factor is calculated.

* If the molecule alignment was successful
  (*i.e* :oe:meth:`OEDepict::OEAlignmentResult::IsValid` is *true*),
  then the correspondence between the two molecules stored in the
  :ref:`OEAlignmentResult <OEDepict_OEAlignmentResult>` returned by the
  :oe:func:`OEDepict::OEPrepareAlignedDepiction` function.
  This :ref:`OEAlignmentResult <OEDepict_OEAlignmentResult>` object can be used
  to highlight the matched common substructure by invoking the
  :oe:func:`OEDepict::OEAddHighlighting` function.

* After both molecules are rendered into the separate cells of the
  grid layout, the image is written into a :file:`png` file.

After initializing the two molecules and the :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object,
the :oe:meth:`OEChem::OEMCSSearch::Match` method is called to perform the
search and return an iterator over the identified maximum common
substructures.
The first match is then utilized to call the
:oe:func:`OEDepict::OEPrepareAlignedDepiction` function that aligns one molecule
to the other based on the given match.
After the alignment, the common atoms and bonds are highlighted by
invoking the :oe:func:`OEDepict::OEAddHighlighting` function.
The image created by :oe:src:`Listing 1<SNIPPET-MCS-ALIGN-MCSAlign>` is shown in
:ref:`Figure: Example of depiction with alignment based on MCS<figure_mcss_align>`.

.. oe:source:: MCSAlign.py
   :language: python
   :refnum:   1
   :caption:  Example of molecule alignment based on MCS
   :frag:     SNIPPET-MCS-ALIGN

.. oe:source:: MCSAlign.cpp
   :language: c++
   :refnum:   1
   :caption:  Example of molecule alignment based on MCS
   :frag:     SNIPPET-MCS-ALIGN

.. oe:source:: MCSAlign.java
   :language: java
   :refnum:   1
   :caption:  Example of molecule alignment based on MCS
   :frag:     SNIPPET-MCS-ALIGN

.. oe:source:: MCSAlign.cs
   :language: csharp
   :refnum:   1
   :caption:  Example of molecule alignment based on MCS
   :frag:     SNIPPET-MCS-ALIGN

.. _figure_mcss_align:

.. figure:: images/MCSAlign.*
   :align:  center

   **Example of depiction with alignment based on maximum common substructure**

.. seealso::

   * :ref:`OEMCSSearch <OEChem_OEMCSSearch>` class in the **OEChem TK** manual
   * :ref:`OEImageGrid <OEDepict_OEImageGrid>` class
   * :oe:func:`OEDepict::OEAddHighlighting` function
   * :oe:func:`OEDepict::OERenderMolecule` function
   * :oe:func:`OEDepict::OEWriteImage` function
   * :ref:`section_examples_summary_mcsalign2D` example


Molecule Alignment Based on Substructure Search
================================================================================

The :ref:`Figure: Example of depiction without alignment<figure_ss_no_alignment>`
is generated by highlighting the "O=C(O)C(N)" substructures in four amino acids,
but keeping the original orientation of the compounds.

.. _figure_ss_no_alignment:

.. figure:: images/SubSearchNoAlignment.*
   :align:  center

   **Example of depiction without alignment**


The :oe:src:`Listing 2<SNIPPET-SUB-SEARCH-ALIGN-SubSearchAlign>` code example shows how to align these
molecules by their matched substructures (*i.e.* by the highlighted atoms and bonds
in :ref:`Figure: Example of depiction without alignment<figure_ss_no_alignment>`).

* First, the :ref:`OESubSearch <OEChem_OESubSearch>` object is initialized with the
  *reference* 2D molecule onto which all amino acid structures will be
  aligned.

* Each amino acids structure is initialized from a SMILES string and
  prepared for depiction.

* An :ref:`OEImageGrid <OEDepict_OEImageGrid>` object is constructed that allows
  to render the molecules into a grid layout.

* An :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` object is initialized that
  stores the properties determine how the molecules are rendered.
  In order to render the molecules in equal size the smallest
  depiction scaling factor is calculated.

* Looping over the amino acids:

  * Each molecule is aligned to the
    reference molecule by calling the :oe:func:`OEDepict::OEPrepareAlignedDepiction`
    function that performs the alignment based on the
    detected substructure search match(es).

  * If the molecule alignment was successful
    (*i.e* :oe:meth:`OEDepict::OEAlignmentResult::IsValid` is *true*),
    then the correspondence between the two molecules stored in the
    :ref:`OEAlignmentResult <OEDepict_OEAlignmentResult>` returned by the
    :oe:func:`OEDepict::OEPrepareAlignedDepiction` function.
    This :ref:`OEAlignmentResult <OEDepict_OEAlignmentResult>` object can be used
    to highlight the matched substructure by invoking the
    :oe:func:`OEDepict::OEAddHighlighting` function.

  * The aligned (and highlighted) molecule is then rendered to a
    next cell of the :ref:`OEImageGrid <OEDepict_OEImageGrid>` object.

* Finally, the image is written into a :file:`png` file.

The image created by :oe:src:`Listing 2<SNIPPET-SUB-SEARCH-ALIGN-SubSearchAlign>` is shown in
:ref:`Figure: Example of depiction with alignment based on substructure search<figure_ss_align>`.

.. oe:source:: SubSearchAlign.py
   :language: python
   :refnum:   2
   :caption:  Example of molecule alignment based on substructure search
   :frag:     SNIPPET-SUB-SEARCH-ALIGN

.. oe:source:: SubSearchAlign.cpp
   :language: c++
   :refnum:   2
   :caption:  Example of molecule alignment based on substructure search
   :frag:     SNIPPET-SUB-SEARCH-ALIGN

.. oe:source:: SubSearchAlign.java
   :language: java
   :refnum:   2
   :caption:  Example of molecule alignment based on substructure search
   :frag:     SNIPPET-SUB-SEARCH-ALIGN

.. oe:source:: SubSearchAlign.cs
   :language: csharp
   :refnum:   2
   :caption:  Example of molecule alignment based on substructure search
   :frag:     SNIPPET-SUB-SEARCH-ALIGN


.. _figure_ss_align:

.. figure:: images/SubSearchAlign.*
   :align:  center

   **Example of depiction with alignment based on substructure match**

.. seealso::

   * :ref:`OESubSearch <OEChem_OESubSearch>` class in the **OEChem TK** manual
   * :ref:`OEImageGrid <OEDepict_OEImageGrid>` class
   * :oe:func:`OEDepict::OEAddHighlighting` function
   * :oe:func:`OEDepict::OERenderMolecule` function
   * :oe:func:`OEDepict::OEWriteImage` function
   * :ref:`section_examples_summary_smartsalign2D` example

.. _section_molalign_molsim:

Molecule Alignment Based on Molecular Similarity
================================================================================

The :ref:`Figure: Example of depiction without alignment<figure_fp_no_alignment>`
is generated by keeping the original orientation of the compounds.

.. _figure_fp_no_alignment:

.. figure:: images/FPNoAlignment.*
   :align:  center

   **Example of depiction without alignment**

The :oe:src:`Listing 3<SNIPPET-FINGERPRINT-ALIGN-FPAlign>` code example shows how to align these
molecules based on their molecular similarity.

* First, two molecules are initialized from SMILES string and
  prepared for depiction.

* An :ref:`OEImageGrid <OEDepict_OEImageGrid>` object is constructed that allows
  to render the two molecules in a grid next to each other.

* The *fit* molecule is then aligned to the *reference*.
  The :oe:func:`OEGraphSim::OEGetFPOverlap` function is utilized to return all common fragments
  found between two molecules based on a given fingerprint type.
  These common fragments reveal the similar parts of the two molecules being compared that are
  used by the :oe:func:`OEDepict::OEPrepareMultiAlignedDepiction` function to find
  the best alignment between the molecules.
  See more fingerprint types in the :ref:`chapter_fptype` chapter of the  **GraphSim TK**
  manual.

* An :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` object is initialized that
  stores the properties determine how the molecules are rendered.
  In order to render the molecules in equal size the smallest
  depiction scaling factor is calculated.

* Then both molecules are rendered into the separate cells of the
  grid layout, the image is written into a :file:`png` file.

The image created by :oe:src:`Listing 3<SNIPPET-FINGERPRINT-ALIGN-FPAlign>` is shown in
:ref:`Figure: Example of depiction with alignment based on molecular similarity<figure_fp_align>`.

.. note::

   **GraphSim TK** license in **not** required to run the :oe:src:`Listing 3<SNIPPET-FINGERPRINT-ALIGN-FPAlign>` example.

.. oe:source:: FPAlign.py
   :language: python
   :refnum:   3
   :caption:  Example of molecule alignment based on molecular similarity
   :frag:     SNIPPET-FINGERPRINT-ALIGN

.. oe:source:: FPAlign.cpp
   :language: c++
   :refnum:   3
   :caption:  Example of molecule alignment based on molecular similarity
   :frag:     SNIPPET-FINGERPRINT-ALIGN

.. oe:source:: FPAlign.java
   :language: java
   :refnum:   3
   :caption:  Example of molecule alignment based on molecular similarity
   :frag:     SNIPPET-FINGERPRINT-ALIGN

.. oe:source:: FPAlign.cs
   :language: csharp
   :refnum:   3
   :caption:  Example of molecule alignment based on molecular similarity
   :frag:     SNIPPET-FINGERPRINT-ALIGN

.. _figure_fp_align:

.. figure:: images/FPAlign.*
   :align:  center

   **Example of depiction with alignment based on molecule similarity**

.. seealso::

   * :ref:`OEImageGrid <OEDepict_OEImageGrid>` class
   * :oe:func:`OEDepict::OERenderMolecule` function
   * :oe:func:`OEDepict::OEWriteImage` function

.. seealso::

   .. figure:: images/OEPrepareMultiAlignedDepictionVisualize.*
      :align:  center

   The Python script that visualizes molecule similarity based on fingerprints
   can be downloaded from the
   `OpenEye Python Cookbook <http://docs.eyesopen.com/python_modules/cookbook/depiction/simcalc.html>`_
