.. _chapter_storage:

********************************************************************************
Storage and Retrieval
********************************************************************************

The :ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` does not store any reference to
the molecule from which it was generated.
The user has to keep track of which fingerprint corresponds to which
molecule.
One way to do this is to attach the fingerprint, as generic data, to
the molecule.
:oe:src:`Listing 3<SNIPPET-FPDATA-FPData>` shows how store and retrieve  fingerprints
as generic data.

.. oe:source:: FPData.cpp
   :language: c++
   :refnum:   3
   :caption:  Storing and retrieving fingerprint as generic data
   :frag:     SNIPPET-FPDATA

.. oe:source:: FPData.py
   :language: python
   :refnum:   3
   :caption:  Storing and retrieving fingerprint as generic data
   :frag:     SNIPPET-FPDATA

.. oe:language:: python

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

.. oe:source:: FPData.java
   :language: java
   :refnum:   3
   :caption:  Storing and retrieving fingerprint as generic data
   :frag:     SNIPPET-FPDATA

.. oe:source:: FPData.cs
   :language: csharp
   :refnum:   3
   :caption:  Storing and retrieving fingerprint as generic data
   :frag:     SNIPPET-FPDATA


.. oe:language:: python java csharp

   It is good practice to check the validity of the fingerprint after
   retrieving it.
   The :oe:meth:`OEGraphSim::OEFingerPrint::IsValid<OEGraphSim::OEFingerPrint::operator bool>`
   method returns true if the fingerprint was successfully initialized.

.. If no :ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` object was attached to the ``obj``
   object with the ``tag`` identifier, then
   :oe:func:`OEGraphSim::OEGetFP` function will return a default
   :ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` instance.

.. oe:language:: c++

   It is good practice to check the validity of the fingerprint after
   retrieving it.
   The :oe:meth:`OEGraphSim::OEFingerPrint::operator bool`
   method returns true if the fingerprint was successfully initialized.


:oe:src:`Listing 4<SNIPPET-FP2OEB-FP2OEB>` demonstrates how to create an
:file:`OEB` binary  file that stores molecules along with their fingerprints.
When reading the :file:`OEB` file that was generated by this program, the
pre-calculated fingerprints can be accessed rapidly with the ``PATH_FP``
tag.
This eliminates the `on-the-fly` generation of the fingerprints.

.. seealso::

  Additional examples in :oe:src:`Listing 10<SNIPPET-SIM-CALC-FROM-OEB-SimCalcFromOEB>` and
  :oe:src:`Listing 12<SNIPPET-DB-SIM-CALC-FROM-OEB-DBSimCalcFromOEB>` of the :ref:`chapter_database`
  chapter.

.. oe:source:: FP2OEB.cpp
   :language: c++
   :refnum:   4
   :caption:  Fingerprint generation and storage in OEB
   :frag:     SNIPPET-FP2OEB

.. oe:source:: FP2OEB.py
   :language: python
   :refnum:   4
   :caption:  Fingerprint generation and storage in OEB
   :frag:     SNIPPET-FP2OEB

.. oe:language:: python

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

.. oe:source:: FP2OEB.java
   :language: java
   :refnum:   4
   :caption:  Fingerprint generation and storage in OEB
   :frag:     SNIPPET-FP2OEB

.. oe:source:: FP2OEB.cs
   :language: csharp
   :refnum:   4
   :caption:  Fingerprint generation and storage in OEB
   :frag:     SNIPPET-FP2OEB

The following code snippets shows how to generate
a bitstring from an :ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` object.

.. oe:source:: FPBitString.cpp
   :language: c++
   :refnum:   5
   :caption:  Accessing a fingerprint as a bitstring
   :frag:     SNIPPET-BIT-STRING

.. oe:source:: FPBitString.py
   :language: python
   :refnum:   5
   :caption:  Accessing a fingerprint as a bitstring
   :frag:     SNIPPET-BIT-STRING


.. oe:language:: python

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

.. oe:source:: FPBitString.java
   :language: java
   :refnum:   5
   :caption:  Accessing a fingerprint as a bitstring
   :frag:     SNIPPET-BIT-STRING

.. oe:source:: FPBitString.cs
   :language: csharp
   :refnum:   5
   :caption:  Accessing a fingerprint as a bitstring
   :frag:     SNIPPET-BIT-STRING

.. seealso::

   * :ref:`OEBitVector <OESystem_OEBitVector>` class

.. warning::

   Even though the **GraphSim TK** library provides a fingerprint API for the
   :term:`LINGO` similarity search method, it is not implemented as a *real*
   :term:`fingerprint`, so bitstrings that are generated from
   LINGO fingerprints are meaningless.


Fingerprints can also be stored in :file:`SDF` files.
The :oe:src:`Listing 6<SNIPPET-FP2SDF-FP2SDF>` demonstrates how to create an
:file:`SDF` and store fingerprints as hexadecimal strings.

After the fingerprint is generated, it is attached to the molecule
as an SD data tag. The identifier of the fingerprint in the :file:`SDF`
file will be the string representation of the fingerprint type.
The bitvector of the fingerprint is converted to a hexadecimal
string with the :oe:meth:`OESystem::OEBitVector::ToHexString`
method.

.. oe:source:: FP2SDF.py
   :language: python
   :refnum:   6
   :caption:  Storing fingerprint in SDF
   :frag:     SNIPPET-FP2SDF

.. oe:language:: python

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

.. oe:source:: FP2SDF.cpp
   :language: c++
   :refnum:   6
   :caption:  Storing fingerprint in SDF
   :frag:     SNIPPET-FP2SDF

.. oe:source:: FP2SDF.java
   :language: java
   :refnum:   6
   :caption:  Storing fingerprint in SDF
   :frag:     SNIPPET-FP2SDF

.. oe:source:: FP2SDF.cs
   :language: csharp
   :refnum:   6
   :caption:  Storing fingerprint in SDF
   :frag:     SNIPPET-FP2SDF


The following example (:oe:src:`Listing 7<SNIPPET-SDF2FP-SDF2FP>`) shows how to
retrieve fingerprints from an :file:`SDF` file.
When looping over the SD data the :oe:func:`OEGraphSim::OEIsValidFPTypeString`
functions can be used to identify SD data that stores
a fingerprint.
The tag of the data is the string representation of the fingerprint type.
This string representation can be used to generate the
corresponding :ref:`OEFPTypeBase <OEGraphSim_OEFPTypeBase>` object by using
the :oe:func:`OEGraphSim::OEGetFPType` function.
The type of the :ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` object then has to
be set by the :oe:meth:`OEGraphSim::OEFingerPrint::SetFPTypeBase`
method.
Finally, the bitvector of the fingerprint then can be initialized from the
hexadecimal string by using the
:oe:meth:`OESystem::OEBitVector::FromHexString` method.

.. oe:source:: SDF2FP.py
   :language: python
   :refnum:   7
   :caption:  Retrieving fingerprint from SDF
   :frag:     SNIPPET-SDF2FP

.. oe:language:: python

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

.. oe:source:: SDF2FP.cpp
   :language: c++
   :refnum:   7
   :caption:  Retrieving fingerprint from SDF
   :frag:     SNIPPET-SDF2FP

.. oe:source:: SDF2FP.java
   :language: java
   :refnum:   7
   :caption:  Retrieving fingerprint from SDF
   :frag:     SNIPPET-SDF2FP

.. oe:source:: SDF2FP.cs
   :language: csharp
   :refnum:   7
   :caption:  Retrieving fingerprint from SDF
   :frag:     SNIPPET-SDF2FP

.. seealso::

   * :oe:meth:`OEGraphSim::OEFPTypeBase::GetFPTypeString` method
   * :ref:`OEBitVector <OESystem_OEBitVector>` class
   * **SD Tagged Data Manipulation** chapter in the **OEChem TK** manual
