.. _chapter_draw_prop_map:

********************************************************************************
Depicting Property Maps
********************************************************************************

The previous chapters give examples about how to depict atom
properties either by using glyphs (see :ref:`chapter_annotation`
chapter) or projecting them into a 2D molecule surface (see
:ref:`chapter_draw_surface` chapter).
**Grapheme TK** can also map atom properties into a 2D grid, called
a property map, using a Gaussian function.
After the grid is generated, colors are rendered to each cell using
the :ref:`OELinearColorGradient <OESystem_OELinearColorGradient>` class that interpolates
colors between a specified range.

The following :oe:src:`Listing 1<SNIPPET-2DPROPMAP-PCHARGE-Draw2DPropMapPartialCharge>` example
demonstrates  how to depict partial charges using the property map.
After constructing the molecule and preparing it for depiction, the MMFF
partial charges are calculated. 
These partial charges are attached to the corresponding atom as
generic data with a specific *tagname*.
A :ref:`OE2DPropMap <OEGrapheme_OE2DPropMap>` object is then generated by
specifying three colors:

* the background color of the property map
* one that represents negative values (in this case charges), and
* the color that represents positive values in the property map

When the :oe:meth:`OEGrapheme::OE2DPropMap::Render` method is called
with the *tagname*, the properties that were attached to the atoms as
generic data are retrieved and a 2D grid is generated along with an
:ref:`OELinearColorGradient <OESystem_OELinearColorGradient>`
object that is used to assign colors to the *cells* of the grid.
The colored grid is then rendered into the *below* layer of the
:ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object, *i.e.*, it appears underneath
the molecular diagram.
The image created by :oe:src:`Listing 1<SNIPPET-2DPROPMAP-PCHARGE-Draw2DPropMapPartialCharge>` is
shown in :ref:`Figure: Example of depicting a property map<figure_draw_propmap_partial_charge>`.


.. oe:source:: Draw2DPropMapPartialCharge.py
   :language: python
   :refnum:   1
   :frag:     SNIPPET-2DPROPMAP-PCHARGE
   :caption:  Depicting partial charges using property map

.. oe:source:: Draw2DPropMapPartialCharge.cpp
   :language: c++
   :refnum:   1
   :frag:     SNIPPET-2DPROPMAP-PCHARGE
   :caption:  Depicting partial charges using property map

.. oe:source:: Draw2DPropMapPartialCharge.java
   :language: java
   :refnum:   1
   :frag:     SNIPPET-2DPROPMAP-PCHARGE
   :caption:  Depicting partial charges using property map

.. oe:source:: Draw2DPropMapPartialCharge.cs
   :language: csharp
   :refnum:   1
   :frag:     SNIPPET-2DPROPMAP-PCHARGE
   :caption:  Depicting partial charges using property map

.. _figure_draw_propmap_partial_charge:


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

   **Example of depicting a property map**

.. seealso::

   * `Generic Data` chapter in the **OEChem TK** manual.

When the :oe:meth:`OEGrapheme::OE2DPropMap::Render` method is called,
the color gradient is initialized by searching for the minimum and
maximum values by the given *tagname*.
This means that when more than one molecule is depicted,
each depiction will have its own independent value range.
(See :ref:`Figure: Example of depicting a property map<figure_draw_prop_map_multi_no_range>`).

.. _figure_draw_prop_map_multi_no_range:

.. figure:: images/Draw2DPropMapPartialChargeMulti-NoRange.*
   :align:  center

   **Example of depicting multiple property maps**

In the :oe:src:`Listing 2<SNIPPET-2DPROPMAP-PCHARGE-MULTI-Draw2DPropMapPChargeMulti>` example,
the value range of the property map is pre-set by identifying the minimum
and maximum atom partial charges for a whole molecule set.
See the result in 
:ref:`Figure: Example of depicting property maps in the same value range<figure_draw_prop_map_multi>`.
Each black box around the color gradient legend indicates the
range of the atom partial charges for the corresponding molecule.

.. oe:source:: Draw2DPropMapPChargeMulti.py
   :language: python
   :refnum:   2
   :frag:     SNIPPET-2DPROPMAP-PCHARGE-MULTI
   :caption:  Depicting multiple molecules using property map

.. oe:source:: Draw2DPropMapPChargeMulti.cpp
   :language: c++
   :refnum:   2
   :frag:     SNIPPET-2DPROPMAP-PCHARGE-MULTI
   :caption:  Depicting multiple molecules using property map

.. oe:source:: Draw2DPropMapPChargeMulti.cs
   :language: csharp
   :refnum:   2
   :frag:     SNIPPET-2DPROPMAP-PCHARGE-MULTI
   :caption:  Depicting multiple molecules using property map

.. oe:source:: Draw2DPropMapPChargeMulti.java
   :language: java
   :refnum:   2
   :frag:     SNIPPET-2DPROPMAP-PCHARGE-MULTI
   :caption:  Depicting multiple molecules using property map

.. _figure_draw_prop_map_multi:

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

   **Example of depicting a property maps in the same value range**

.. seealso::

   * :ref:`OEImageGrid <OEDepict_OEImageGrid>` class in the **OEDepict TK** manual


.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   %
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The above examples show how to project atom properties (such as partial charges)
into the property map.
However, the :ref:`OE2DPropMap <OEGrapheme_OE2DPropMap>` class can also be used to visualize
bond properties by attaching a value to each bond as a generic data using a *tagname*.
When the :oe:meth:`OEGrapheme::OE2DPropMap::Render` method is called
with the same *tagname*, the property that was attached to a bond is retrieved and
projected at the middle of that bond before applying a Gaussian function to blur
out the 2D grid underneath the molecular graph.
The :ref:`Table: Depicting atom or/and bond properties<table_draw_prop_map_atom_bond>`
table shows the differences between visualizing atom or/and bond properties using the
:ref:`OE2DPropMap <OEGrapheme_OE2DPropMap>` class.

.. _table_draw_prop_map_atom_bond:

.. list-table:: **Depicting atom or/and bond properties**
   :widths: 150 150 150
   :header-rows: 0

   * - .. image:: images/OE2DPropMap_AtomProperties.*
          :align:  center
     - .. image:: images/OE2DPropMap_AtomAndBondProperties.*
          :align:  center
     - .. image:: images/OE2DPropMap_BondProperties.*
          :align:  center

   * - only atom
     - both atom and bond
     - only bond
