.. _chapter_genericdata:

********************************************************************************
Generic Data
********************************************************************************

Previous chapters :ref:`chapter_molproperties`, :ref:`chapter_atomproperties`,
:ref:`chapter_bondproperties` have described how common global properties 
of molecule, atoms, and bonds can be modified and accessed.
There are applications, however, when associating arbitrary
data with objects such as molecules, atoms and bonds is necessary.
**OEChem TK** provides a framework to solve this problem by allowing to attach
**generic data** to an object by association either with an integer or
character string, called **tag** identifier.

The following two snippets demonstrate how generic data (for example
molecule weight) can be attached to a molecule:

.. oe:source:: GenericData.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SET-DATA-INTEGER

.. oe:source:: GenericData.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SET-DATA-STRING

.. oe:source:: GenericData.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SET-DATA-INTEGER

.. oe:source:: GenericData.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SET-DATA-STRING

.. oe:source:: GenericData.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SET-DATA-INTEGER

.. oe:source:: GenericData.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SET-DATA-STRING

.. oe:source:: GenericData.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SET-DATA-INTEGER

.. oe:source:: GenericData.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SET-DATA-STRING


After annotation, the data can be accessed with the same integer or character string
identifier:

.. oe:source:: GenericData.py
  :language: python
  :noindent:
  :frag:     SNIPPET-GET-DATA-INTEGER

.. oe:source:: GenericData.py
  :language: python
  :noindent:
  :frag:     SNIPPET-GET-DATA-STRING

.. oe:source:: GenericData.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-GET-DATA-INTEGER

.. oe:source:: GenericData.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-GET-DATA-STRING

.. oe:source:: GenericData.java
   :language: java
   :noindent:
   :frag:     SNIPPET-GET-DATA-INTEGER

.. oe:source:: GenericData.java
   :language: java
   :noindent:
   :frag:     SNIPPET-GET-DATA-STRING

.. oe:source:: GenericData.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-GET-DATA-INTEGER

.. oe:source:: GenericData.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-GET-DATA-STRING

.. warning::

   The integer tag of a generic data should always be allocated
   using the :oe:func:`OESystem::OEGetTag` function.

The following table shows the basic methods of the
:ref:`OEBase <OESystem_OEBase>` class that allow the manipulation of generic
data.

.. list-table:: **Methods to manipulate generic data**
   :widths: 15 40
   :header-rows: 1

   * - Method
     - Description

   * - :oe:meth:`OESystem::OEBase::SetData`
     - sets a generic data associating it with the given tag

   * - :oe:meth:`OESystem::OEBase::AddData`
     -  adds a generic data associating it with the given tag

   * - :oe:meth:`OESystem::OEBase::HasData`
     - determines whether a molecule has any generic data with a given tag

   * - :oe:meth:`OESystem::OEBase::GetData`
     - returns the generic data associated with the given tag

   * - :oe:meth:`OESystem::OEBase::DeleteData`
     - deletes all generic data  with the given tag

   * - :oe:meth:`OESystem::OEBase::Clear`
     - clears all stored generic data


The main difference between the :oe:meth:`OESystem::OEBase::SetData`
method and the :oe:meth:`OESystem::OEBase::AddData` method is that if a
data with the same identifier is already attached to an object then:

* by using :oe:meth:`OESystem::OEBase::SetData`, the data is replaced
* by using :oe:meth:`OESystem::OEBase::AddData`, the data is appended


Furthermore, :oe:meth:`OESystem::OEBase::SetData` does not allow
replacing an existing tag with a different data type:

.. oe:source:: GenericDataTypeMismatch.py
   :language: python
   :noindent:
   :frag:     SNIPPET-TYPE-MISMATCH

.. oe:source:: GenericDataTypeMismatch.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-TYPE-MISMATCH

.. oe:source:: GenericDataTypeMismatch.java
   :language: java
   :noindent:
   :frag:     SNIPPET-TYPE-MISMATCH

.. oe:source:: GenericDataTypeMismatch.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-TYPE-MISMATCH

The above code will throw the following warning:

::

   Warning: data type mismatch found when using generic data

.. _section_attaching_plain_old_data:

Attaching plain old data
================================================================================

The following simple code demonstrate how data calculated and attached
to a molecule in one function can be accessed later on through the tag
identifier.

.. oe:source:: GenericDataMolWeight.py
   :language: python
   :refnum:   1
   :caption:  Example of using generic data
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-GenericDataMolWeight.py>`



.. oe:source:: GenericDataMolWeight.cpp
   :language: c++
   :refnum:   1
   :caption:  Example of using generic data
   :frag:     SNIPPET

.. oe:source:: GenericDataMolWeight.java
   :language: java
   :refnum:   1
   :caption:  Example of using generic data
   :frag:     SNIPPET

.. oe:source:: GenericDataMolWeight.cs
   :language: csharp
   :refnum:   1
   :caption:  Example of using generic data
   :frag:     SNIPPET

.. note::

   It is a good programming practice to call :oe:meth:`OESystem::OEBase::HasData`
   in order to check whether or not a data exists before trying to access it by
   the :oe:meth:`OESystem::OEBase::GetData` method.

.. oe:language:: c++ python

   The :oe:meth:`OESystem::OEBase::GetData` method returns only the first
   instance of data stored previously with the associated data tag.  Data
   can also be accessed by using the
   :oe:meth:`OESystem::OEBase::GetDataIter` method that returns an
   iterator over all data stored.

   .. oe:source:: GenericDataIter.py
      :language: python
      :noindent:
      :frag:     SNIPPET-DATA-ITER

   .. oe:source:: GenericDataIter.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-DATA-ITER

   The output of code snippet above is the following:

   ::

      activity antiarthritic
      activity antiinflammatory
      weight 128.16898

   The :oe:meth:`OESystem::OEBase::GetDataIter` method can also take a
   tag identifier. In this case it iterates over only data associated
   with the given tag.
   For example, the following code will only prints out the two piece of
   'activity' data.

   .. oe:source:: GenericDataIter.py
      :language: python
      :noindent:
      :frag:     SNIPPET-DATA-ITER-WITH-TAG

   .. oe:source:: GenericDataIter.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-DATA-ITER-WITH-TAG

.. _section_attaching_data_to_atoms:

Attaching data to atoms
================================================================================

Generic data can be attached to any object that derives
from the :ref:`OEBase <OESystem_OEBase>` class.
The following program shows an example where hydrogen bonding donor
property is attached as a bool value to the corresponding :ref:`OEAtomBase <OEChem_OEAtomBase>`
object.

.. oe:source:: GenericDataToAtom.py
   :language: python
   :refnum:   2
   :caption:  Example of attaching generic data to atoms
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-GenericDataToAtom.py>`



.. oe:source:: GenericDataToAtom.cpp
   :language: c++
   :refnum:   2
   :caption:  Example of attaching generic data to atoms
   :frag:     SNIPPET

.. oe:source:: GenericDataToAtom.java
   :language: java
   :refnum:   2
   :caption:  Example of attaching generic data to atoms
   :frag:     SNIPPET

.. oe:source:: GenericDataToAtom.cs
   :language: csharp
   :refnum:   2
   :caption:  Example of attaching generic data to atoms
   :frag:     SNIPPET

.. seealso::

   * :ref:`OEBase <OESystem_OEBase>` class in the :ref:`chapter_oesystemclasses`
     chapter for the full list of derived classes.

.. _section_attaching_other_objects:

Attaching other objects
================================================================================

The type of the generic data is not restricted to fundamental data
types of the programming language.  High-level **OEChem TK** objects such as
:ref:`OEMolBase <OEChem_OEMolBase>`, :ref:`OEAtomBase <OEChem_OEAtomBase>`,
:ref:`OEBondBase <OEChem_OEBondBase>` :ref:`OEScalarGrid <OESystem_OEScalarGrid>`,
:ref:`OESkewGrid <OESystem_OESkewGrid>` and :ref:`OESurface <OESpicoli_OESurface>` can
also be stored through this mechanism. The following program
demonstrates how to attach a subset of a molecule to the original
molecule as generic data.

.. oe:source:: GenericDataMol.py
   :language: python
   :refnum:   3
   :caption:  Example of attaching a molecule as generic data
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-GenericDataMol.py>`



.. oe:source:: GenericDataMol.cpp
   :language: c++
   :refnum:   3
   :caption:  Example of attaching a molecule as generic data
   :frag:     SNIPPET

.. oe:source:: GenericDataMol.java
   :language: java
   :refnum:   3
   :caption:  Example of attaching a molecule as generic data
   :frag:     SNIPPET

.. oe:source:: GenericDataMol.cs
   :language: csharp
   :refnum:   3
   :caption:  Example of attaching a molecule as generic data
   :frag:     SNIPPET

.. oe:language:: c++ python

   Sequences of objects can be stored as well. The following example
   shows how to attach a sequence of atoms into an
   :ref:`OEAtomBase <OEChem_OEAtomBase>` object.

   .. oe:source:: GenericDataContainer.py
      :language: python
      :refnum:   4
      :caption:  Example of attaching list of atoms as generic data
      :frag:     SNIPPET

   .. oe:source:: GenericDataContainer.cpp
      :language: c++
      :refnum:   4
      :caption:  Example of attaching vector of atoms as generic data
      :frag:     SNIPPET

   .. seealso::

      * Example in :ref:`section_grids_genericdata` section that shows how to
        attach grids to molecules

.. note::

   Generic data attached to a molecule or any of its atoms or bonds is automatically
   saved when the molecule is written into an :file:`.oeb` file.

.. seealso::

   * :ref:`section_moltaggeddata_SD` section
   * :ref:`section_moltaggeddata_PDB` section
