.. include:: ../common/cookbook/cookbook-hyperlinks

.. _chapter_interactions:

********************************************************************************
Interaction Perception
********************************************************************************

**OEBio TK** provides the following APIs to perceive protein-ligand interactions:

   :oe:func:`OEBio::OEPerceiveInteractionHints`
      The function that perceives protein-ligand interactions.

   :ref:`OEPerceiveInteractionOptions <OEBio_OEPerceiveInteractionOptions>`
      The class that stores the parameters that control the interaction perception.

      The default geometric parameters have been set based on literature data
      ([Kumar-2002]_, [Cavallo-2016]_, [Bissantz-2010]_, and [Marcou-2007]_ ).

Interaction Hint Container
================================================================================

Interactions perceived by the :oe:func:`OEBio::OEPerceiveInteractionHints` function are stored
in an :ref:`OEInteractionHintContainer <OEBio_OEInteractionHintContainer>` object.
The architecture of the :ref:`OEInteractionHintContainer <OEBio_OEInteractionHintContainer>` class is depicted
in :ref:`figure_OEInteractionHintContainer`.

.. only:: oehtml

   .. _figure_OEInteractionHintContainer:

   .. figure::  ./images/interactionhint.svg
      :align:  center
      :width:  800 pt

      **Schematic representation of interaction hint container**

   :ref:`OEInteractionHintContainer <OEBio_OEInteractionHintContainer>`
     This is the main container that stores typed molecules (:ref:`OEMolBase <OEChem_OEMolBase>`), fragments of those
     molecules (:ref:`OEInteractionHintFragment <OEBio_OEInteractionHintFragment>`) and typed interactions (:ref:`OEInteractionHint <OEBio_OEInteractionHint>`)
     between the fragments.

   :ref:`OEInteractionHintComponentTypeBase <OEBio_OEInteractionHintComponentTypeBase>`
     The abstract class that enables to type molecules stored in the interaction container.
     Each molecule added to the container has to have a specific type.
     Currently, there are two built-in component types available:

     * :ref:`OELigandInteractionHintComponent <OEBio_OELigandInteractionHintComponent>`  -- component type that classifies a molecule as a 'ligand'
     * :ref:`OEProteinInteractionHintComponent <OEBio_OEProteinInteractionHintComponent>` -- component type that classifies a molecule as a 'protein'

   :ref:`OEInteractionHintFragment <OEBio_OEInteractionHintFragment>`
     Set of atoms of a molecule that is stored in the interaction container. These are the
     atoms that are contribute to an interaction (:ref:`OEInteractionHint <OEBio_OEInteractionHint>`).
     Some interactions, such as hydrogen bonds, are between two atoms; other ones define
     interactions between set of atoms.
     For example, a stacking interaction is between atoms of two aromatic ring systems.

   :ref:`OEInteractionHint <OEBio_OEInteractionHint>`
     An iteration is defined between two fragments (:ref:`OEInteractionHintFragment <OEBio_OEInteractionHintFragment>`) stored in the
     container. An interaction can be either inter (:oe:meth:`OEBio::OEInteractionHint::IsInter`) or intra
     (:oe:meth:`OEBio::OEInteractionHint::IsIntra`) molecular. Each interaction has a specific type that is
     derived from the :ref:`OEInteractionHintTypeBase <OEBio_OEInteractionHintTypeBase>` class.

   :ref:`OEInteractionHintTypeBase <OEBio_OEInteractionHintTypeBase>`
     The abstract class that enables to type interactions stored in the interaction container.
     The table below shows the specific interaction types currently available in **OEBio TK**.
     Some interaction classes are also associated with namespaces that enable to
     *subtype* the main interaction types.
     For example, the stacking interaction has the following subtypes:

     * Pi-stacking -- :ref:`OEStackingInteractionHint <OEBio_OEStackingInteractionHint>` ( :oe:const:`OEBio::OEStackingInteractionHintType::Pi` )
     * T-stacking  -- :ref:`OEStackingInteractionHint <OEBio_OEStackingInteractionHint>` ( :oe:const:`OEBio::OEStackingInteractionHintType::T` )
     * Intra-molecular Pi-stacking (ligand)  -- :ref:`OEStackingInteractionHint <OEBio_OEStackingInteractionHint>` ( :oe:const:`OEBio::OEStackingInteractionHintType::IntramolecularLigandPi` )
     * Intra-molecular T-stacking (ligand)   -- :ref:`OEStackingInteractionHint <OEBio_OEStackingInteractionHint>` ( :oe:const:`OEBio::OEStackingInteractionHintType::IntramolecularLigandT` )
     * Intra-molecular Pi-stacking (protein) -- :ref:`OEStackingInteractionHint <OEBio_OEStackingInteractionHint>` ( :oe:const:`OEBio::OEStackingInteractionHintType::IntramolecularProteinPi` )
     * Intra-molecular T-stacking (protein)  -- :ref:`OEStackingInteractionHint <OEBio_OEStackingInteractionHint>` ( :oe:const:`OEBio::OEStackingInteractionHintType::IntramolecularProteinT` )

     Similarly, the cation-pi interaction has the following subtypes:

     * Cation-Pi (ligand pi)              -- :ref:`OECationPiInteractionHint <OEBio_OECationPiInteractionHint>` ( :oe:const:`OEBio::OECationPiInteractionHintType::LigandPi` )
     * Cation-Pi (protein pi)             -- :ref:`OECationPiInteractionHint <OEBio_OECationPiInteractionHint>` ( :oe:const:`OEBio::OECationPiInteractionHintType::ProteinPi` )
     * Intra-molecular cation-Pi (ligand)  -- :ref:`OECationPiInteractionHint <OEBio_OECationPiInteractionHint>` ( :oe:const:`OEBio::OECationPiInteractionHintType::IntramolecularLigand` )
     * Intra-molecular cation-Pi (protein) -- :ref:`OECationPiInteractionHint <OEBio_OECationPiInteractionHint>` ( :oe:const:`OEBio::OECationPiInteractionHintType::IntramolecularProtein` )

     .. list-table:: **Interaction types currently available in OEBio TK**
        :header-rows: 1
        :widths: 300 500 500

        * - name
          - corresponding interaction class
          - corresponding interaction type namespace

        * - cation-pi
          - :ref:`OECationPiInteractionHint <OEBio_OECationPiInteractionHint>`
          - :ref:`OECationPiInteractionHintType <OEBio_OECationPiInteractionHintType>`

        * - chelator
          - :ref:`OEChelatorInteractionHint <OEBio_OEChelatorInteractionHint>`
          - :ref:`OEChelatorInteractionHintType <OEBio_OEChelatorInteractionHintType>`

        * - clash
          - :ref:`OEClashInteractionHint <OEBio_OEClashInteractionHint>`
          - None

        * - contact
          - :ref:`OEContactInteractionHint <OEBio_OEContactInteractionHint>`
          -  None

        * - covalent
          - :ref:`OECovalentInteractionHint <OEBio_OECovalentInteractionHint>`
          -  None

        * - halogen bond
          - :ref:`OEHalogenBondInteractionHint <OEBio_OEHalogenBondInteractionHint>`
          - :ref:`OEHalogenBondInteractionHintType <OEBio_OEHalogenBondInteractionHintType>`

        * - hydrogen bond
          - :ref:`OEHBondInteractionHint <OEBio_OEHBondInteractionHint>`
          - :ref:`OEHBondInteractionHintType <OEBio_OEHBondInteractionHintType>`

        * - salt-bridge
          - :ref:`OESaltBridgeInteractionHint <OEBio_OESaltBridgeInteractionHint>`
          - :ref:`OESaltBridgeInteractionHintType <OEBio_OESaltBridgeInteractionHintType>`

        * - stacking (T and Pi)
          - :ref:`OEStackingInteractionHint <OEBio_OEStackingInteractionHint>`
          - :ref:`OEStackingInteractionHintType <OEBio_OEStackingInteractionHintType>`

Other related APIs:

   :ref:`OEIsValidActiveSite <OEBio_OEIsValidActiveSite>`
      This function checks whether the interaction container initialized correctly as
      **active site** i.e. containing two molecules: one typed as *ligand* and one typed as *protein*.

   :ref:`OEGetActiveSiteInteractionHintTypes <OEBio_OEGetActiveSiteInteractionHintTypes>`
      This function iterates over all interaction types (including subtypes) that are
      perceived by the :ref:`OEPerceiveInteractionHints <OEBio_OEPerceiveInteractionHints>` function.

.. admonition:: Code Examples

   * :ref:`section_example_oebio_printinteractions` **OEChem TK** example
   * :ref:`section_examples_summary_complex2img` **Grapheme TK** example

   **OpenEye Python Cookbook** recipes:

   * `Accessing Interaction Hint Information`_
   * `Print Protein-Ligand Interactions to Console`_
   * `Print the Summary of Protein-Ligand Interactions for a Set of Molecules`_

Interaction Hint Predicates
================================================================================

The table below list all interaction predicates that are currently available in
**OEBio TK**.

.. table:: **OEBio TK interaction predicates**

   ========================================= ===========================================================
   Access interactions                       Functor Name
   ========================================= ===========================================================
   with given interaction type               :ref:`OEHasInteractionHintType <OEBio_OEHasInteractionHintType>`
   with given atom                           :ref:`OEHasInteractionHint <OEBio_OEHasInteractionHint>`
   with given residue                        :ref:`OEHasResidueInteractionHint <OEBio_OEHasResidueInteractionHint>`
   contact                                   :ref:`OEIsContactInteractionHint <OEBio_OEIsContactInteractionHint>`
   hydrogen bond                             :ref:`OEIsHBondInteractionHint <OEBio_OEIsHBondInteractionHint>`
   inter-molecular hydrogen bond             :ref:`OEIsIntermolecularHBondInteractionHint <OEBio_OEIsIntermolecularHBondInteractionHint>`
   intra-molecular hydrogen bond             :ref:`OEIsIntramolecularHBondInteractionHint <OEBio_OEIsIntramolecularHBondInteractionHint>`
   chelator                                  :ref:`OEIsChelatorInteractionHint <OEBio_OEIsChelatorInteractionHint>`
   inter-molecular chelator                  :ref:`OEIsIntermolecularChelatorInteractionHint <OEBio_OEIsIntermolecularChelatorInteractionHint>`
   intra-molecular chelator                  :ref:`OEIsIntramolecularChelatorInteractionHint <OEBio_OEIsIntramolecularChelatorInteractionHint>`
   covalent                                  :ref:`OEIsCovalentInteractionHint <OEBio_OEIsCovalentInteractionHint>`
   clash                                     :ref:`OEIsClashInteractionHint <OEBio_OEIsClashInteractionHint>`
   clashing hydrogen bond                    :ref:`OEIsClashingHBondInteractionHint <OEBio_OEIsClashingHBondInteractionHint>`
   salt-bridge                               :ref:`OEIsSaltBridgeInteractionHint <OEBio_OEIsSaltBridgeInteractionHint>`
   inter-molecular salt-bridge               :ref:`OEIsIntermolecularSaltBridgeInteractionHint <OEBio_OEIsIntermolecularSaltBridgeInteractionHint>`
   intra-molecular salt-bridge               :ref:`OEIsIntramolecularSaltBridgeInteractionHint <OEBio_OEIsIntramolecularSaltBridgeInteractionHint>`
   T and Pi-stacking                         :ref:`OEIsStackingInteractionHint <OEBio_OEIsStackingInteractionHint>`
   inter-molecular stacking                  :ref:`OEIsIntermolecularStackingInteractionHint <OEBio_OEIsIntermolecularStackingInteractionHint>`
   intra-molecular stacking                  :ref:`OEIsIntramolecularStackingInteractionHint <OEBio_OEIsIntramolecularStackingInteractionHint>`
   cation-Pi                                 :ref:`OEIsCationPiInteractionHint <OEBio_OEIsCationPiInteractionHint>`
   inter-molecular cation-Pi                 :ref:`OEIsIntermolecularCationPiInteractionHint <OEBio_OEIsIntermolecularCationPiInteractionHint>`
   intra-molecular cation-Pi                 :ref:`OEIsIntramolecularCationPiInteractionHint <OEBio_OEIsIntramolecularCationPiInteractionHint>`
   halogen bond                              :ref:`OEIsHalogenBondInteractionHint <OEBio_OEIsHalogenBondInteractionHint>`
   inter-molecular halogen bond              :ref:`OEIsIntermolecularHalogenBondInteractionHint <OEBio_OEIsIntermolecularHalogenBondInteractionHint>`
   intra-molecular halogen bond              :ref:`OEIsIntramolecularHalogenBondInteractionHint <OEBio_OEIsIntramolecularHalogenBondInteractionHint>`
   inter-molecular                           :ref:`OEIsInterInteractionHint <OEBio_OEIsInterInteractionHint>`
   intra-molecular                           :ref:`OEIsIntraInteractionHint <OEBio_OEIsIntraInteractionHint>`
   non-ideal hydrogen bond                   :ref:`OEIsNonIdealHBondInteractionHint <OEBio_OEIsNonIdealHBondInteractionHint>`
   unpaired (hbond or salt-bridge)           :ref:`OEIsUnpairedInteractionHint <OEBio_OEIsUnpairedInteractionHint>`
   unpaired ligand                           :ref:`OEIsUnpairedLigandInteractionHint <OEBio_OEIsUnpairedLigandInteractionHint>`
   unpaired protein                          :ref:`OEIsUnpairedProteinInteractionHint <OEBio_OEIsUnpairedProteinInteractionHint>`
   ========================================= ===========================================================

The following logical operations allow to combine both the built-in and the
user defined interaction predicates.

.. oe:language:: c++

   .. table:: **Interaction Composite Functors**

      ===================================== ========================================
      Composite Functor                     Description
      ===================================== ========================================
      :oe:cls:`OENot<OESystem::OENot>`      logical not
      :oe:cls:`OEOr<OESystem::OEOr>`        logical or
      :oe:cls:`OEAnd<OESystem::OEAnd>`      logical and
      ===================================== ========================================


.. oe:language:: python java csharp

   .. table:: **Interaction Composite Functors**

      ================================================ ========================================
      Composite Functor                                Description
      ================================================ ========================================
      :oe:cls:`OENotInteractionHint<OESystem::OENot>`  logical not
      :oe:cls:`OEOrInteractionHint<OESystem::OEOr>`    logical or
      :oe:cls:`OEAndInteractionHint<OESystem::OEAnd>`  logical and
      ================================================ ========================================

.. _chapter_interactions_geometry:

Accessing Calculated Interaction Hint Geometries
================================================================================

When interaction hints are perceived using the :oe:func:`OEBio::OEPerceiveInteractionHints`
function, various geometries (such as distances and angles) are calculated
that are checked against the geometric constraints stored in the given
:ref:`OEPerceiveInteractionOptions <OEBio_OEPerceiveInteractionOptions>` class.

The following code snippet shows how to access these calculated geometries:

.. oe:source:: InteractionGeometry.py
   :language: python
   :noindent:
   :frag:     SNIPPET-INTER

.. oe:source:: InteractionGeometry.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-INTER

.. oe:source:: InteractionGeometry.java
   :language: java
   :noindent:
   :frag:     SNIPPET-INTER

.. oe:source:: InteractionGeometry.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-INTER

For the :oe:const:`OEBio::OEHBondInteractionHintType::LigandDonates` hydrogen bond
interaction type, three geometries are calculated:

* the distance between the acceptor and the donor heavy atoms
  (see also the :oe:meth:`OEBio::OEPerceiveInteractionOptions::SetMaxHBondDistance` method)
* the acceptor angle (see also the :oe:meth:`OEBio::OEPerceiveInteractionOptions::SetMaxAcceptorAngle` method)
* the donor angle (see also the :oe:meth:`OEBio::OEPerceiveInteractionOptions::SetMaxDonorAngle` method)

The "distance" values are always given in Angstroms and the "angle" values
are always given in radians.
The output of the code snippet above might look like this:

.. code-block:: console

   Calculated geometries for 'bio:active-site:hbond:ligand2protein' interaction type:
   bio:interaction:distance       : 2.722
   bio:intaraction:acceptor-angle : 0.155
   bio:interaction:donor-angle    : 0.241

For different interactions, different geometries are calculated.
The following snippet shows how to access the names of the geometries that are
available for a given interaction type using the :oe:func:`OEBio::OEGetCalculatedInteractionGeometries` function:

.. oe:source:: InteractionGeometry.py
   :language: python
   :noindent:
   :frag:     SNIPPET-INTER-TYPE

.. oe:source:: InteractionGeometry.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-INTER-TYPE

.. oe:source:: InteractionGeometry.java
   :language: java
   :noindent:
   :frag:     SNIPPET-INTER-TYPE

.. oe:source:: InteractionGeometry.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-INTER-TYPE

All interaction geometry names start with the ``bio:interaction:`` prefix.
However, both the :oe:meth:`OEBio::OEInteractionHint::HasCalculatedGeometry` and
:oe:meth:`OEBio::OEInteractionHint::GetCalculatedGeometry` methods accept
names with or without the ``bio:interaction:`` prefix.

The following code snippet shows how to access the calculated geometries directly:

.. oe:source:: InteractionGeometry.py
   :language: python
   :noindent:
   :frag:     SNIPPET-HAS-GEOMETRY

.. oe:source:: InteractionGeometry.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-HAS-GEOMETRY

.. oe:source:: InteractionGeometry.java
   :language: java
   :noindent:
   :frag:     SNIPPET-HAS-GEOMETRY

.. oe:source:: InteractionGeometry.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-HAS-GEOMETRY

The output of the code snippet above might look like this:

.. code-block:: console

   distance: 2.722  Angstrom(s)
   acceptor angle: 8.863 degree(s)

.. hint::

   It is a good practice to call :oe:meth:`OEBio::OEInteractionHint::HasCalculatedGeometry`
   prior to invoking the :oe:meth:`OEBio::OEInteractionHint::GetCalculatedGeometry`
   method to check whether the interaction hint has a geometry with a given name.

Currently, the following names are used for the interaction geometries:

* ``bio:interaction:distance``
* ``bio:interaction:angle``
* ``bio:interaction:acceptor-angle``
* ``bio:interaction:donor-angle``

For most interactions (except the unpaired ones), the calculated distance
is available by using the ``bio:interaction:distance`` name.
None of the unpaired interactions have any calculated geometries since
they only "suggest" how they could contribute to the binding but are not
actually formed in the complex.

A calculated geometry, such as a distance, can have different meanings based on
the interaction type.
For example, in a hydrogen bond interaction it means the distance between
the acceptor and donor heavy atoms. For a pi-staking interaction,
it means the distance between the center of the two ring systems.
The following table shows the correspondence between the calculated
geometries and the geometric constraints.

.. list-table::
   :widths: 100 100 100

   * - Set method
     - Interaction type
     - Associated geometry name

   * - :oe:meth:`SetMaxHBondDistance<OEBio::OEPerceiveInteractionOptions::SetMaxHBondDistance>`
     - hbond
     - ``bio:interaction:distance``

   * - :oe:meth:`SetMaxChargeAidedHBondDistance<OEBio::OEPerceiveInteractionOptions::SetMaxChargeAidedHBondDistance>`
     - hbond (charged)
     - ``bio:interaction:distance``

   * - :oe:meth:`SetMaxNonIdealHBondDistance<OEBio::OEPerceiveInteractionOptions::SetMaxNonIdealHBondDistance>`
     - non-ideal hbond
     - ``bio:interaction:distance``

   * - :oe:meth:`SetMaxAcceptorAngle<OEBio::OEPerceiveInteractionOptions::SetMaxAcceptorAngle>`
     - hbond
     - ``bio:interaction:acceptor-angle``

   * - :oe:meth:`SetMaxDonorAngle<OEBio::OEPerceiveInteractionOptions::SetMaxDonorAngle>`
     - hbond
     - ``bio:interaction:donor-angle``

   * - :oe:meth:`SetMaxNonIdealAcceptorAngle<OEBio::OEPerceiveInteractionOptions::SetMaxNonIdealAcceptorAngle>`
     - non-ideal hbond
     - ``bio:interaction:acceptor-angle``

   * - :oe:meth:`SetMaxNonIdealDonorAngle<OEBio::OEPerceiveInteractionOptions::SetMaxNonIdealDonorAngle>`
     - non-ideal hbond
     - ``bio:interaction:donor-angle``

   * - :oe:meth:`SetMaxMetalBondDistance<OEBio::OEPerceiveInteractionOptions::SetMaxMetalBondDistance>`
     - chelator
     - ``bio:interaction:distance``

   * - :oe:meth:`SetMaxSaltBridgeDistance<OEBio::OEPerceiveInteractionOptions::SetMaxSaltBridgeDistance>`
     - salt bridge
     - ``bio:interaction:distance``

   * - :oe:meth:`SetMaxCationPiDistance<OEBio::OEPerceiveInteractionOptions::SetMaxCationPiDistance>`
     - cation-Pi
     - ``bio:interaction:distance``

   * - :oe:meth:`SetMaxCationPiAngle<OEBio::OEPerceiveInteractionOptions::SetMaxCationPiAngle>`
     - cation-Pi
     - ``bio:interaction:angle``

   * - :oe:meth:`SetMaxPiStackDistance<OEBio::OEPerceiveInteractionOptions::SetMaxPiStackDistance>`
     - Pi-stacking
     - ``bio:interaction:distance``

   * - :oe:meth:`SetMaxPiStackAngle<OEBio::OEPerceiveInteractionOptions::SetMaxPiStackAngle>`
     - Pi-stacking
     - ``bio:interaction:angle``

   * - :oe:meth:`SetMaxTStackDistance<OEBio::OEPerceiveInteractionOptions::SetMaxTStackDistance>`
     - T-stacking
     - ``bio:interaction:distance``

   * - :oe:meth:`SetMaxTStackAngle<OEBio::OEPerceiveInteractionOptions::SetMaxTStackAngle>`
     - T-stacking
     - ``bio:interaction:angle``

   * - :oe:meth:`SetMinStackOffset<OEBio::OEPerceiveInteractionOptions::SetMinStackOffset>`
     - Pi-stacking and T-stacking
     - (no geometry — acts as a filter)

   * - :oe:meth:`SetMaxHalogenBondDistance<OEBio::OEPerceiveInteractionOptions::SetMaxHalogenBondDistance>`
     - halogen bond
     - ``bio:interaction:distance``

   * - :oe:meth:`SetMaxHalogenAngle<OEBio::OEPerceiveInteractionOptions::SetMaxHalogenAngle>`
     - halogen bond
     - ``bio:interaction:angle``
