.. _chapter_docking:

********************************************************************************
Docking
********************************************************************************

Docking is the process of determining the structure of a ligand bound in the
active site of a target protein.  In the *Docking Toolkit* this is done with
the :ref:`OEDock <OEDocking_OEDock>` class that takes a multiconformer representation
of a ligand and returns the top scoring pose (or poses if desired) within the
active site.  Docking is done using an exhaustive search algorithm, followed
by optimization of the best poses from the exhaustive search
(see :ref:`section_docking_algorithm` section).

:ref:`section_examples_docking` is an example program that uses the
:ref:`OEDock <OEDocking_OEDock>` class to dock, score and annotate multiconformer
molecules.

.. _section_docking_construction:

Scoring Functions and Search Resolution
================================================================================

The resolution of the exhaustive search and scoring functions are required inputs
when constructing a :ref:`OEDock <OEDocking_OEDock>` object.

*dockMethod* is an unsigned int constant from the 
:oe:constns:`OEDocking::OEDockMethod` namespace, that specifies the combination
of scoring functions (or method) :ref:`OEDock <OEDocking_OEDock>` uses for the
exhaustive search and optimization.  The available scoring methods are:

   ================================================= ================================= =================================
   **Method**                                        **Exhaustive Search Scoring**     **Optimization Scoring**         
   ================================================= ================================= =================================
   :oe:const:`OEDocking::OEDockMethod::Shapegauss`   :ref:`section_scoring_shapegauss` :ref:`section_scoring_shapegauss`
   :oe:const:`OEDocking::OEDockMethod::PLP`          :ref:`section_scoring_plp`        :ref:`section_scoring_plp`       
   :oe:const:`OEDocking::OEDockMethod::Chemgauss3`   :ref:`section_scoring_chemgauss3` :ref:`section_scoring_chemgauss3`
   :oe:const:`OEDocking::OEDockMethod::Chemgauss4`   :ref:`section_scoring_chemgauss3` :ref:`section_scoring_chemgauss4`
   :oe:const:`OEDocking::OEDockMethod::Chemscore`    :ref:`section_scoring_chemgauss3` :ref:`section_scoring_chemscore` 
   :oe:const:`OEDocking::OEDockMethod::Hybrid1`      :ref:`section_scoring_cgo`        :ref:`section_scoring_chemgauss3`
   :oe:const:`OEDocking::OEDockMethod::Hybrid`       :ref:`section_scoring_cgo`        :ref:`section_scoring_chemgauss4`
   ================================================= ================================= =================================

*dockResolution* is an unsigned int constant from the 
:oe:constns:`OEDocking::OESearchResolution` namespace, that specifies the docking
resolution to use.  The docking resolution is the rotational and translational
stepsize used during the exhaustive search and optimization (the rotational
stepsize is the furthest distance any heavy atom of the ligand will move in
a single rotational step).  The following resolutions are supported

   ============================================================ ============================ =========================
   **Resolution**                                               **Exhaustive Translational** **Exhaustive Rotational**
   ============================================================ ============================ =========================
   :oe:const:`OEDocking::OESearchResolution::High`              1.0                          1.0                      
   :oe:const:`OEDocking::OESearchResolution::Standard`          1.0                          1.5                      
   :oe:const:`OEDocking::OESearchResolution::Low`               1.5                          2.0                      
   ============================================================ ============================ =========================


   ============================================================  ==============================  ===========================
   **Resolution**                                                **Optimization Translational**  **Optimization Rotational**
   ============================================================  ==============================  ===========================
   :oe:const:`OEDocking::OESearchResolution::High`                  0.5                             0.5
   :oe:const:`OEDocking::OESearchResolution::Standard`              0.5                             0.75
   :oe:const:`OEDocking::OESearchResolution::Low`                   0.75                            1.0
   ============================================================  ==============================  ===========================

All resolutions are in Angstroms.

.. seealso::

   Section :ref:`section_docking_algorithm` for more information docking 
   algorithm.

.. _section_docking_hybrid:

Hybrid Method
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The hybrid (:oe:const:`OEDocking::OEDockMethod::Hybrid2`) docking method is 
distinguished from other docking methods because it uses information present in
the structure of a bound ligand to enhance docking performance.

The bound ligand information is used during the exhaustive search stage of the
docking process (see :ref:`section_docking_algorithm` section) by using the
:ref:`section_scoring_cgo` scoring function, which scores poses based on how
well a docked pose overlays the shape of the bound ligand and mimics the same
hydrogen bonding and interactions the bound ligand makes.  After the exhaustive
search, optimization is performed with :ref:`section_scoring_chemgauss4` which
is a standard structure based scoring function.

The final score a ligand receives using the hybrid docking method is based
only on its interactions with the protein.  Ligand information is used only
to guide the selection of poses during the exhaustive search.

.. note::

   In order to use the hybrid docking
   method the receptor :ref:`OEDesignUnit <OEBio_OEDesignUnit>` must have a bound ligand (see
   :oe:meth:`OEDesignUnit::HasLigand<OEBio::OEDesignUnit::HasLigand>`).


.. _section_docking_initialization:

Initialization
================================================================================

An :ref:`OEDock <OEDocking_OEDock>` object must be initialized with a receptor object,
prior to docking, scoring or annotating any molecules.  This is done by passing
a :ref:`OEDesignUnit <OEBio_OEDesignUnit>` containing a receptor (see :ref:`Receptors <chapter_receptor>`)
to the :oe:meth:`OEDocking::OEDock::Initialize` method.


.. _section_docking_molecules:

Docking Molecules
================================================================================

Once the :ref:`OEDock <OEDocking_OEDock>` object has been initialized molecules are
docked using the :oe:meth:`OEDocking::OEDock::DockMultiConformerMolecule` method.

Docking requires a multiconformer representation of the molecule as input. Docking
selects the top scoring docked pose from the provided ensemble of conformers.  The 
score of the docked molecule can be obtained by calling
the :oe:meth:`OEChem::OEMolBase::GetEnergy` method of *pose*.

:ref:`OEDock <OEDocking_OEDock>` can also return alternate as well as top scoring
poses of the docked molecule.

.. _section_docking_methods:

Scoring Molecules
================================================================================

The final score of a molecule (using the optimization scoring function) docked
with the :oe:meth:`OEDocking::OEDock::DockMultiConformerMolecule` method can
be obtained by calling the :oe:meth:`OEChem::OEMolBase::GetEnergy`.

:ref:`OEDock <OEDocking_OEDock>` can also recalculate a score of a pose (using
the optimization scoring function), and calculate the contribution for each
individual component of the score as in the following example.


.. _section_docking_algorithm:

Docking Algorithm
================================================================================

:ref:`OEDock <OEDocking_OEDock>` docks multiconformer molecules using an exhaustive
search that systematically searches rotations and translations of each conformer
of the ligand within the active site.  Following the exhaustive search the
top scoring poses are optimized and assigned a final score.  These two steps
are described in more detail below

*Exhaustive Search*

  #. Enumerates, to given resolution, every possible rotation and translation
     of each conformer of the ligand being docked within a box enclosing the
     active site. The resolution of the exhaustive search is determined by
     the overall resolution setting of :ref:`OEDock <OEDocking_OEDock>`
     (see :ref:`section_docking_construction` section).

  #. Discard out poses that either clash with the protein or extend to far
     from the binding site using the receptor's negative image outer contour
     (see :ref:`section_receptor_negative_image` section).  

  #. If the negative image inner contour is enabled discard any poses that
     do not have at least one heavy atom that falls within the inner contour.
     (see :ref:`section_receptor_negative_image` section).  

  #. Discard any poses that do no match any user specified constraints.
     (see :ref:`section_receptor_constraints` section).

  #. Score all remaining poses.  The scoring function used here depends
     on what scoring method is being used (see :ref:`section_docking_construction`
     section).

  #. Sort poses by score and pass the top scoring poses to optimization.
     The number of posses passed to optimization depends on the search
     resolution (see :oe:constns:`OEDocking::OESearchResolution` constant
     namespace).

*Optimization*

  #. Each pose moved to 729 nearby positions, scored and the top scoring
     position become the new optimized pose.  The positions
     are generated by having the initial pose take one positive and one
     negative step for each translational and rotational degree of freedom.
     The resolution of these steps is half that of the exhaustive search,
     and is determined by the overall resolution setting of 
     :ref:`OEDock <OEDocking_OEDock>`
     (see :ref:`section_docking_construction` section).

  #. The best scoring pose of the 729 tests poses is selected as the final
     docked structure (and score) for the ligand.


