.. _chapter_complex_surface:

********************************************************************************
Drawing a Ligand-Protein Complex Surface
********************************************************************************

The previous chapter demonstrates how to draw and customize 2D
molecule surfaces.
**Grapheme TK** also provides a method that depicts a ligand-protein
complex in which the arcs of the 2D surface of the molecule are
annotated based on the distance between the accessible
surfaces of the ligand and the surrounding protein
(:oe:func:`OESpicoli::OEMakeAccessibleSurface`).
Based on this calculation, the atoms of the ligand are
divided into four categories which are then inherited by the
corresponding arcs when the 2D molecule surface of the ligand is
drawn.
These four types are the following:

#. **Solvent** (:ref:`OEDefaultSolventArcFxn <OEGrapheme_OEDefaultSolventArcFxn>`)

   A surface arc is depicted using the *solvent* style if the
   corresponding atom is accessible to a solvent.
   (See :ref:`Figure: Example of the 'solvent' arc style<figure_complex_surface_solvent>`)

   .. _figure_complex_surface_solvent:

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

      **Example of the 'solvent' arc style**

#. **Cavity** (:ref:`OEDefaultCavityArcFxn <OEGrapheme_OEDefaultCavityArcFxn>`)

   A surface arc is depicted using the *cavity* style if in the
   region of the corresponding atom, a cavity is detected between the
   ligand and the receptor molecule surfaces.
   The cavity is large enough to allow expanding the ligand in this
   region without bumping into the receptor.
   (See :ref:`Figure: Example of the cavity arc style<figure_complex_surface_cavity>`)

   .. _figure_complex_surface_cavity:

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

      **Example of the 'cavity' arc style**

#. **Void**  (:ref:`OEDefaultVoidArcFxn <OEGrapheme_OEDefaultVoidArcFxn>`)

   A surface arc is depicted using the *void* style, if in the
   region of the corresponding atom a small interstice is detected
   between the ligand and the receptor molecule surfaces.
   (See :ref:`Figure: OEDefaultBuriedArcFxn<figure_complex_surface_void>`)

   .. _figure_complex_surface_void:

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

      **Example of the 'void' arc style**

#. **Buried** (:ref:`OEDefaultBuriedArcFxn <OEGrapheme_OEDefaultBuriedArcFxn>`)

   A surface arc is depicted using the *buried* style, if in the
   region of the corresponding atom the ligand is tightly fit to the
   receptor.
   (See :ref:`Figure: Example of the buried arc style<figure_complex_surface_buried>`)

   .. _figure_complex_surface_buried:

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

      **Example of the 'buried' arc style**

.. note::

   Even though, **Spicoli TK** is used to generate the accessible surfaces of
   the ligand and the receptor, no **Spicoli TK** license is required to call
   the :oe:func:`OEGrapheme::OEAddComplexSurfaceArcs` function.

.. #########################################################################

The following :oe:src:`Listing 1<SNIPPET-DRAW-COMPLEX-SURFACE-DrawComplexSurface>` example show how
to display the surface of the ligand-protein complex.
After importing the ligand and the receptor structures, the
:oe:func:`OEGrapheme::OEAddComplexSurfaceArcs` function is called to
generate the accessible molecule surfaces (using **Spicoli TK**) and assign
the surface drawing styles (*solvent*, *buried*, *void*, or *cavity*)
for the atoms of the ligand.
These styles are the used to draw the arcs of the molecule surface
when the :oe:func:`OEGrapheme::OEDraw2DSurface` function is invoked.
The :oe:func:`OEGrapheme::OEGetMoleculeSurfaceScale` function is used
to reduce the scaling of the molecule in order to be able to fit
both the molecule diagram and the molecule surface into the image.

.. oe:source:: DrawComplexSurface.py
   :language: python
   :refnum:   1
   :frag:     SNIPPET-DRAW-COMPLEX-SURFACE
   :caption:  Example of complex surface drawing

.. oe:source:: DrawComplexSurface.cpp
   :language: c++
   :refnum:   1
   :frag:     SNIPPET-DRAW-COMPLEX-SURFACE
   :caption:  Example of complex surface drawing

.. oe:source:: DrawComplexSurface.java
   :language: java
   :refnum:   1
   :frag:     SNIPPET-DRAW-COMPLEX-SURFACE
   :caption:  Example of complex surface drawing

.. oe:source:: DrawComplexSurface.cs
   :language: csharp
   :refnum:   1
   :frag:     SNIPPET-DRAW-COMPLEX-SURFACE
   :caption:  Example of complex surface drawing


The following snapshot (:ref:`Figure: Dihydrofolate reductase<figure_draw_complex_surface_vida>`)
displays the ligand of the *2w3a* PDB complex in VIDA
with the accessible surface of the protein.
The image shown in the :ref:`Figure: The Grapheme representation of the 2w3a complex<figure_draw_complex_surface_grapheme>`
is created by :oe:src:`Listing 1<SNIPPET-DRAW-COMPLEX-SURFACE-DrawComplexSurface>` code for the same
ligand-protein complex.


.. _figure_draw_complex_surface_vida:

.. figure:: images/DrawComplexSurface-VIDA.png
   :align:  center

   **Dihydrofolate reductase complexed with trimethoprim in VIDA (PDB 2w3a)**

.. _figure_draw_complex_surface_grapheme:

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

   **The Grapheme representation of the 2w3a complex**


User-defined *solvent* and *buried* surface drawing styles can be
implemented by deriving from the
:ref:`OESurfaceArcFxnBase <OEGrapheme_OESurfaceArcFxnBase>` base class.
Similarly, user-defined *cavity* and *void* surface drawing styles can be
implemented by deriving from the
:ref:`OEComplexSurfaceArcFxnBase <OEGrapheme_OEComplexSurfaceArcFxnBase>` base class.
This later abstract class also stores the relative distance calculated
between the ligand and the receptor.
The following code snippet shows how to use this *depth* to emphasize 
the volume of the cavity by adjusting the size of the *spikes* when
drawing the surface arcs using the :oe:func:`OEGrapheme::OEDrawSunSurfaceArc`
function.

.. #########################################################################

.. oe:source:: DrawComplexSurfaceUserDef.py
   :language: python
   :noindent:
   :frag:     SNIPPET-COMPLEX-SURFACE-ARC-DEFINITIONS

.. oe:source:: DrawComplexSurfaceUserDef.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-COMPLEX-SURFACE-ARC-DEFINITIONS

.. oe:source:: DrawComplexSurfaceUserDef.java
   :language: java
   :noindent:
   :frag:     SNIPPET-COMPLEX-SURFACE-ARC-DEFINITIONS

.. oe:source:: DrawComplexSurfaceUserDef.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-COMPLEX-SURFACE-ARC-DEFINITIONS


These arc drawing predicates then can be used to draw the surface of
the ligand-protein complex when calling the
:oe:func:`OEGrapheme::OEAddComplexSurfaceArcs` function.
The image created is shown in
:ref:`Figure: Example of user-defined surface drawing<figure_draw_complex_surface_user_defined>`.

.. oe:source:: DrawComplexSurfaceUserDef.py
   :language: python
   :noindent:
   :frag:     SNIPPET-COMPLEX-SURFACE-ARC-USAGE

.. oe:source:: DrawComplexSurfaceUserDef.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-COMPLEX-SURFACE-ARC-USAGE

.. oe:source:: DrawComplexSurfaceUserDef.java
   :language: java
   :noindent:
   :frag:     SNIPPET-COMPLEX-SURFACE-ARC-USAGE

.. oe:source:: DrawComplexSurfaceUserDef.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-COMPLEX-SURFACE-ARC-USAGE
 

.. _figure_draw_complex_surface_user_defined:

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

   **Example of user-defined surface drawing**


.. seealso::

   * :ref:`spicoli_generation` chapter in the  **Spicoli TK** manual

