.. _tutorial_alternative_starts_introduction_section:

Introduction
================================================================================

In this tutorial you will learn how to make use of the alternative starts
functionality in **FastROCS TK**. This functionality was introduced in the
**OpenEye Toolkits v2017.Feb** release of
:ref:`section_fastrocs-tk-1-8-1`.

.. note::
   The data used in this tutorial is **not** provided.

Alternative starting points refer to the starting orientations of the
query-conformer
pair when optimizing their overlap in space. The default method is
:oe:meth:`OEFastROCS::OEFastROCSOrientation::Inertial`. In this method, the
molecules are centered and set to an inertial frame of reference. The database
molecule is then rotated about its inertial axes, creating up to a possible 8
starting points at which overlays are then optimized.

The default optimizes the first
4 inertial starts only. This can be changed via the
:oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetNumInertialStarts` method.
The figure below shows the inertial starting points of caffeine.

.. _alternative_starts_figure_1:

.. figure:: ../../images/Tutorial_1_Figure_1.png
   :align: center

   **Inertial Starting Points of Caffeine**

For some molecular structures these inertial starting positions may not lead to
adequate sampling of the molecular volume overlap space, resulting in poor
overlap/scores. Making use of alternative starts can solve this problem by
creating additional starting positions at which to perform the inertial
optimizations.  One example of this is the alignment of 4TMN and 3TMN
ligands of Thrombin [Grant-1996]_.


The figure below shows the 2D molecular structure of these ligands and their
x-ray alignment. The x-ray alignment shows a good overlap between
3TMN and the side chain of 4TMN.

.. _alternative_starts_figure_2:

.. figure:: ../../images/Tutorial_1_Figure_2.png
   :align: center

   **Alternative Starts Use Case**

   4TMN ligand, 3TMN ligand, and their x-ray alignment.

The figure below shows the resultant overlays in **FastROCS TK**
when using default starting points compared to
:oe:meth:`OEFastROCS::OEFastROCSOrientation::InertialAtHeavyAtoms`
starting points.

.. _alternative_starts_figure_3:

.. figure:: ../../images/Tutorial_1_Figure_3.png
   :align: center

   **Overlap Comparison**

   Overlay generated from performing a default search (left) compared
   with ”InertialAtHeavyAtoms” search (right).

The default search results in poor overlap between the two molecules (left).
When the new
:oe:meth:`OEFastROCS::OEFastROCSOrientation::InertialAtHeavyAtoms`
orientation option is used, the resultant overlap is much more
favorable (right) and correlates well with the x-ray alignment
from :ref:`alternative_starts_figure_2`.

There are 5 methods currently implemented in **FastROCS TK** that allow
different starting orientations to be experimented with. They are:

* :oe:meth:`OEFastROCS::OEFastROCSOrientation::Inertial`
* :oe:meth:`OEFastROCS::OEFastROCSOrientation::InertialAtHeavyAtoms`
* :oe:meth:`OEFastROCS::OEFastROCSOrientation::InertialAtColorAtoms`
* :oe:meth:`OEFastROCS::OEFastROCSOrientation::UserInertialStarts`
* :oe:meth:`OEFastROCS::OEFastROCSOrientation::AsIs`

A description of these can be found in the
:oe:constns:`OEFastROCS::OEFastROCSOrientation` section of the docs.

This tutorial will focus on 3 alternative starts methods:

* :oe:meth:`OEFastROCS::OEFastROCSOrientation::InertialAtHeavyAtoms`
* :oe:meth:`OEFastROCS::OEFastROCSOrientation::UserInertialStarts`
* :oe:meth:`OEFastROCS::OEFastROCSOrientation::AsIs`

The methodology described can be adapted to the remaining starting point
options that are not described in this tutorial. For example, the use case for
:oe:meth:`OEFastROCS::OEFastROCSOrientation::InertialAtColorAtoms`
is almost identical to
:oe:meth:`OEFastROCS::OEFastROCSOrientation::InertialAtHeavyAtoms` except for
the constant passed in to
:oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetInitialOrientation`
and the use of
:oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetNumColorAtomStarts` instead of
:oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetNumHeavyAtomStarts`
to retrieve the number of starts.
