.. include:: ../substitutions
.. include:: ../../apps-substitutions

.. _chapter_watercolor:

********************************************************************************
WaterColor VIDA Extension
********************************************************************************

The *WaterColor* extension is used to set-up :ref:`chapter_szmap`
and :ref:`chapter_gameplan` output in *VIDA*.

For :ref:`chapter_szmap` grids, it alters the contour surface display properties.
It sets up a standard color scheme for grids, sets some grids to solid surfaces
while leaving others wire-mesh,
sets up any difference grids to show both positive (yellow) and negative (purple) contours,
and sets the contour levels to "reasonable" default values. Feel free to change any of
the properties afterwards.
It also restricts the display of protein atoms to just those that surround the ligand
and turns on the display of both the protein and the ligand. And protein molecular surface
is added to the protein, but not displayed by default.

For :ref:`chapter_gameplan` results, the extension makes the annotation visible. It also
restricts the protein and ligand display and generates a molecular surface as described for grids.

This extension is not required to analyze ``-at_coords`` results but if engaged,
will set the protein and ligand display as above, along with the molecular surface.

See :ref:`chapter_installextensions` for information on installing this extension.

Viewing Results Grids
---------------------

   .. _figure_vida1:

   .. figure:: ../images/vida1-browse.png
      :width: 1000
      :align:  center

      **Browse View**

* Step 1
   Open *VIDA* and make sure the 3D viewer, the *list* panel
   and the *style* panel are available. If not, select the *Browsing* view
   (figure :ref:`Browse View<figure_vida1>`) to setup your display.
   You can move the *list* and *style* panels to as needed---here, we
   have stacked them on top of one another to save space.

   .. _figure_vida2:

   .. figure:: ../images/vida2-select-arrow.png
      :width: 1000
      :align:  center

      **List Panel**

* Step 2
   Select *File >> Open* and choose the *.oeb.gz* or *.oeb* file containing
   your :ref:`chapter_szmap` grid results.
   The file should show up in the :ref:`List Panel<figure_vida2>`
   and the structure should show in the 3D viewer.

   .. _figure_vida3:

   .. figure:: ../images/vida3-show+resize.png
      :width: 1000
      :align:  center

      **Showing Grids**

   Click on the > triangle beside the molecule name to show the contents and expand
   the list panel to show the full contents
   (figure :ref:`Showing Grids<figure_vida3>`).

   .. _figure_vida4:

   .. figure:: ../images/vida4-contour1.png
      :width: 1000
      :align:  center

      **Select Grid**

* Step 3
   Clicking on the grid name will show that grid
   (figure :ref:`Select Grid<figure_vida4>`) but
   the molecule is now deselected and just the grid
   contour is shown.

   .. _figure_vida9:

   .. figure:: ../images/vida9-isolevel.png
      :scale:  75
      :align:  center

      **Isolevel**

   You may
   have to change the contour level slider in the style
   panel to see the contour
   (figure :ref:`Isolevel<figure_vida9>`).

   .. _figure_vida4b:

   .. figure:: ../images/vida4b-watercolor.png
      :width: 1000
      :align:  center

      **WaterColor Extension**

* Step 4
   Run the *WaterColor* extension
   (figure :ref:`WaterColor Extension<figure_vida4b>`),
   to set the contour levels to better
   starting values and also change the colors and
   rendering styles so that the various grids are
   easily distinguish.
   These settings can be modified using the style panel.
   It also hides all protein atoms that are not near to the
   binding site.
   Finally, it generates a molecular surface associated with the protein
   that shows the boundary of the binding
   site. This surface can be selected and displayed in the same way as a grid.

   .. _figure_vida5:

   .. figure:: ../images/vida5-contour+mol.png
      :width: 1000
      :align:  center

      **Molecule and Grid**

* Step 5
   After *WaterColor* runs, the ligand and protein should have a green dot in the visibility column.
   If it is not visible, click on the *neut_diff_apo_free_energy* list item to show
   that grid in the context of the input molecules
   (figure :ref:`Molecule and Grid<figure_vida5>`).

* Step 6
   The scene can be scaled (or zoomed) by holding down the
   Middle mouse button by itself, the Left and Right mouse
   buttons together, or by using the mouse wheel. The scene can
   also be scaled using the W and S keys on the keyboard.


   .. _figure_vida6:

   .. figure:: ../images/vida6-center.png
      :scale:  75
      :align:  center

      **Center**

   .. _figure_vida7:

   .. figure:: ../images/vida7-lightning.png
      :scale:  75
      :align:  center

      **Select**

   You may also need to recenter by clicking on the center button
   to the left of the 3D viewer (figure :ref:`Center<figure_vida6>`).

   Click on the lightning bolt to
   get out of centering mode and back to selection mode
   (figure :ref:`Select<figure_vida7>`).

   You can pan by holding down the shift key as you drag the mouse.

   If you need to adjust the clipping planes, use the + and -
   buttons in the Graphics style panel
   (figure :ref:`Clipping<figure_vida11>`).

   .. _figure_vida11:

   .. figure:: ../images/vida11-clipping.png
      :scale:  75
      :align:  center

      **Clipping**

   .. _figure_vida8:

   .. figure:: ../images/vida8-surf-color.png
      :scale:  75
      :align:  center

      **Surface Style**

* Step 7
   You can change the color of the grid and switch between wireframe
   lines, solid surface, and point clouds (select the ^ button above the surface 
   icon at the bottom of the 3D display
   figure :ref:`Surface Style<figure_vida8>`;
   points have jitter added).

   .. _figure_vida10:

   .. figure:: ../images/vida10-transparency.png
      :scale:  75
      :align:  center

      **Transparency**

   When using a solid surface,
   it can be useful to set the surface transparency in the style
   menu to, say, 70% (figure :ref:`Transparency<figure_vida10>`).

   .. _figure_vida13:

   .. figure:: ../images/vida13-add-contours.png
      :scale:  75
      :align:  center

      **Adding Contours**

   You can increase the number of contours for a given grid
   with the + button in the contour style panel
   (figure :ref:`Adding Contours<figure_vida13>`).

   .. _figure_vida12:

   .. figure:: ../images/vida12-multiple-contours.png
      :width: 1000
      :align:  center

      **Multiple Grids**

* Step 8
   Overlapping contours from different grids requires that you select
   all the grids in the list panel (figure :ref:`Multiple Grids<figure_vida12>`).
   This can be a little counter-intuitive;
   play with multiple selections until you get the hang of it.

   .. hint::

      Only select one grid at a time if you are trying to change
      the color or style or transparency to a value different
      from other grids.


   .. _figure_vida14:

   .. figure:: ../images/vida14-diffgrid.png
      :width: 1000
      :align:  center

      **Difference Grid**

* Step 9
   *Difference* grids represent the difference between standard water
   and uncharged water, a proxy for hydrophobic atoms in the ligand.
   The *WaterColor* extension configures them as
   a pair of contours: negative in yellow representing
   areas where standard water has lower values---for :math:`\Delta G` 
   and :math:`\Delta H`
   standard water is more favorable here---and positive in purple
   representing areas where uncharged water has lower values
   (figure :ref:`Difference Grid<figure_vida14>`).
   The hydrophobic/hydrophilic pattern within a site is matched
   by high-affinity ligands.

   .. _figure_vida15:

   .. figure:: ../images/vida15-vdwgrid.png
      :width: 1000
      :align:  center

      **VDW Grid**

   *Van der Waals* grids show a component of the energy
   that is not a part of the difference free energy (because it subtracts out).
   The default VDW (green) contours are -2 kcal/mol, containing the lowest 5% (approx.)
   of the negative VDW waters (figure :ref:`VDW Grid<figure_vida15>`). Low VDW regions
   are found in regions with weak polar interactions. Conversely, regions with
   strong polar interactions have positive VDW energy. The balance between
   Coulombic interactions and VDW interactions defines the masked, or nonclashing,
   region.

   .. _figure_vida16:

   .. figure:: ../images/vida16-ordergrid.png
      :width: 1000
      :align:  center

      **Order Grid**

   *Order* grids (light blue mesh) show the fraction of water entropy lost due to electrostatic
   interactions (figure :ref:`Order Grid<figure_vida16>`).
   A value of 1.0 means the site is highly ordered and displacing water from there will
   liberate almost all this rotational entropy (approximately 2.4 kcal/mol). A value of 0.0 means
   the water orientation is completely degenerate and displacing it will not liberate any
   rotational entropy. The energy gained by displacing water is primarily entropic,
   enthalpy mainly serves as a filter that discriminates between different ligands.

   .. _figure_vida17:

   .. figure:: ../images/vida17-maskgrid.png
      :width: 1000
      :align:  center

      **Mask Grid**

   *Mask* grids (gray mesh) are an accurate description of the *solvent accessible surface*,
   calculated as regions where the minimum *Coulombic interaction* + *VDW* energy is below a threshold
   (figure :ref:`Mask Grid<figure_vida17>`). Examining the mask grid clarifies where water
   fits and where it clashes. The displaced region of the *apo* pocket contains the volume
   of the *apo* mask minus that of the complex mask. To speed up ligand calculations
   during a stabilization run, the ligand analysis is limited to the region within
   the complex mask, by default. In "at_coords" calculations, points that are not
   in the mask are labeled "CLASH".

   .. _figure_vida18:

   .. figure:: ../images/vida18-stblgrid.png
      :width: 1000
      :align:  center

      **Stabilization Grid**

   *Stabilization* grids
   are special kinds of difference grids (*complex - apo - ligand*),
   showing how water is stabilized
   or destabilized upon binding (figure :ref:`Stabilization Grid<figure_vida18>`).
   They provide information about the possible
   effects of modifying the ligand.

   If you have calculated *displacement* grids---with *apo* data in regions where water has
   been displaced---these will be found at the end of the list of items in the results.
   Examining them can clarify how far a ligand's reach extends.

   Other grids can be produced but these capture the main elements required to understand solvation.

* Step 10
   **Explore!**

Viewing Gameplan Results
------------------------

   .. _figure_vida21:

   .. figure:: ../images/vida1-browse.png
      :width: 1000
      :align:  center

      **Browse View**

* Step 1
   Open *VIDA* and make sure the 3D viewer, the list panel
   and the style panel are available. If not, select the *Browsing* view
   (figure :ref:`Browse View<figure_vida21>`) to setup your display.

   .. _figure_vida22:

   .. figure:: ../images/vida_gameplan_list_window.png
      :scale:  75
      :align:  center

      **Gameplan List Window**

* Step 2
   Select *File >> Open* and choose the *.oeb.gz* or *.oeb* file
   containing your :ref:`chapter_gameplan` results.
   The file should show up in the list panel
   (figure :ref:`Gameplan List Window<figure_vida22>`;
   the blue bar identifies the active entry)
   and the ligand structure should show in the 3D viewer.

   .. _figure_vida23a:

   .. figure:: ../images/vida-pref-bkgd.png
      :width: 1000
      :align:  center

      **Changing Background**

.. note::

   The figures shown here have a white background which is recommended for
   presentations and publications. You can change the background color in
   *VIDA* by bringing up the *Edit >> Preferences* window
   (*Vida >> Preferences* on Mac OS X),
   selecting *3D Display* and then clicking on the *OpenGL* tab
   (figure :ref:`Changing Background<figure_vida23a>`).

* Step 3
   Run the *WaterColor* extension to activate the display of annotation
   explaining the various ligand modification hypotheses.
   It also adds a surface that shows the boundary of the binding
   site, and hides all protein atoms that are not near to the
   binding site. These settings can be modified using the style
   panel.

   .. _figure_vida23:

   .. figure:: ../images/vida23-gp-ligand.png
      :width: 1000
      :align:  center

      **Ligand Compared to apo Binding Site**

* Step 4
   The first entry analyzes how the ligand
   (figure :ref:`Ligand Compared to apo Binding Site<figure_vida23>`)
   Yellow mesh spheres show polar sites, green mesh spheres are van der Waals sites,
   translucent green spheres are non-polar sites, and purple diamonds indicate
   a mismatch, where the ligand is either much more or much less polar than the binding site.
   See chapter :ref:`chapter_gameplan` for a complete description of the
   annotation symbols.

   .. _figure_vida24:

   .. figure:: ../images/vida24-gp-polar.png
      :width: 1000
      :align:  center

      **Hypothesis for a Polar Substituent**

   .. _figure_vida25:

   .. figure:: ../images/vida25-gp-nonpolar.png
      :width: 1000
      :align:  center

      **Hypothesis for a Nonpolar/VDW Substituent**

* Step 5
   Next comes the *apo*-protein, then a series of
   hypotheses for ligand modification.

   Scarlet colored bonds indicate a proposed modification
   to the ligand. Gameplan tries to explore a wide
   range of possible ways to improve the ligand, and has an
   option that permits the hybridization to differ from
   that in the original ligand. See the 
   ``-sample_hybridization`` option in chapter :ref:`chapter_gameplan`
   for details.

   Using the arrow keys to step between the different
   hypotheses, you will
   see yellow cages around atoms where water makes good polar
   interactions (figure :ref:`Hypothesis for a Polar Substituent<figure_vida24>`),
   green cages around atoms
   where water has good van der Waals energy,
   and translucent green balls around atoms
   where a fluorine or methyl group may be a good fit
   (figure :ref:`Hypothesis for a Nonpolar/VDW Substituent<figure_vida25>`).

   The same substituent may show up with different
   conformations or under different categories.

   .. _figure_vida26:

   .. figure:: ../images/vida26-gp-stbl.png
      :width: 1000
      :align:  center

      **Stabilizing Site**

* Step 6
   Finally points where
   water is stabilizing (green) or destabilizing (red) the complex are enumerated
   (figure :ref:`Stabilizing Site<figure_vida26>`).
   Destabilizing points may be good candidates for displacement, while
   stabilizing points can be left in place. But if a stabilizing site
   contains highly ordered water in the complex, careful replacement
   of this water with a substituent that makes the same number of interactions
   can liberate as much as 2 kcal/mol of rotational entropy.
