.. _chapter_fptype:

********************************************************************************
Fingerprint Types
********************************************************************************

A fingerprint is a bitvector.
To reflect this the :ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` class derives
from the :ref:`OEBitVector <OESystem_OEBitVector>` class.
The difference is that :ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` has a type
that represents how the fingerprint is generated.
Fingerprints may only be compared if they are generated in the same way.
Therefore, the following restriction is introduced:

.. warning::

   When two fingerprints are subjected to similarity calculation their
   type has to be identical.

:oe:src:`Listing 1<SNIPPET-FPTYPE-FPType>` shows how to create different fingerprint
objects (:ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>`) and identify or
compare their types.

.. oe:source:: FPType.cpp
   :language: c++
   :refnum:   1
   :caption:  Fingerprint type
   :frag:     SNIPPET-FPTYPE

.. oe:source:: FPType.py
   :language: python 
   :refnum:   1
   :caption:  Fingerprint type
   :frag:     SNIPPET-FPTYPE

..    oe:language:: python

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


.. oe:source:: FPType.java
   :language: java
   :refnum:   1
   :caption:  Fingerprint type
   :frag:     SNIPPET-FPTYPE

.. oe:source:: FPType.cs
   :language: csharp
   :refnum:   1
   :caption:  Fingerprint type
   :frag:     SNIPPET-FPTYPE

The output of :oe:src:`Listing 1<SNIPPET-FPTYPE-FPType>` is the following:

::

   uninitialized fingerprint
   Path
   different fingerprint types


Two fingerprints are considered to be equivalent only if they have 
the same fingerprint type (:ref:`OEFPTypeBase <OEGraphSim_OEFPTypeBase>`)
and have identical bit-vectors (:ref:`OEBitVector <OESystem_OEBitVector>`).
The following code snippet shows how to compare two 
:ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` objects.

.. oe:source:: FPCompare.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-FP-COMPARE

.. oe:source:: FPCompare.py
   :language: python
   :noindent:
   :frag:     SNIPPET-FP-COMPARE

..    oe:language:: python

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


.. oe:source:: FPCompare.java
   :language: java
   :noindent:
   :frag:     SNIPPET-FP-COMPARE

.. oe:source:: FPCompare.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-FP-COMPARE


The following code snippet shows how to initialize a
:ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` object by
using the type of another fingerprint. 
The type of a fingerprint is accessed by the
:oe:meth:`OEGraphSim::OEFingerPrint::GetFPTypeBase` method.

.. oe:source:: MakeFP.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-MAKE-FP

.. oe:source:: MakeFP.py
   :language: python
   :noindent:
   :frag:     SNIPPET-MAKE-FP

..    oe:language:: python

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


.. oe:source:: MakeFP.java
   :language: java
   :noindent:
   :frag:     SNIPPET-MAKE-FP

.. oe:source:: MakeFP.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-MAKE-FP

.. _section_fptype_parameters:

Fingerprint parameters
================================================================================

The :ref:`chapter_user_defined` chapter gives examples of how user defined
fingerprints can be generated by defining, for example, the atom and
bond properties that will be encoded into the fingerprints.

In order to ensure that only equivalent fingerprints can be compared,
the fingerprint type stores the parameters being used in the
generation process.
The :oe:meth:`OEGraphSim::OEFPTypeBase::GetFPTypeString` method returns
the string representation of the fingerprint type that includes
information about the parameters being used.

.. oe:source:: FPTypeString.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-FP-TYPE-STRING

.. oe:source:: FPTypeString.py
   :language: python
   :noindent:
   :frag:     SNIPPET-FP-TYPE-STRING

..    oe:language:: python

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


.. oe:source:: FPTypeString.java
   :language: java
   :noindent:
   :frag:     SNIPPET-FP-TYPE-STRING

.. oe:source:: FPTypeString.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-FP-TYPE-STRING

The output of the preceding snippet is the following:

::

   Path,ver=2.0.0,size=4096,bonds=0-5,atype=AtmNum|Arom|Chiral|FCharge|HvyDeg|Hyb|EqHalo,
   btype=Order|Chiral


.. note::

   The returned string does not include newline characters, the string was broken
   into two separate lines here only for better readability.


The following :oe:src:`Listing 2<SNIPPET-FPTYPE-PARAMS-FPTypeParams>` shows how to extract
the parameters of a fingerprint from a string representation by
using the :ref:`OEFPTypeParams <OEGraphSim_OEFPTypeParams>` class.

.. oe:source:: FPTypeParams.cpp
   :language: c++
   :refnum:   2
   :caption:  Fingerprint parameters
   :frag:     SNIPPET-FPTYPE-PARAMS

.. oe:source:: FPTypeParams.py
   :language: python 
   :refnum:   2
   :caption:  Fingerprint parameters
   :frag:     SNIPPET-FPTYPE-PARAMS

..    oe:language:: python

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


.. oe:source:: FPTypeParams.java
   :language: java
   :refnum:   2
   :caption:  Fingerprint parameters
   :frag:     SNIPPET-FPTYPE-PARAMS

.. oe:source:: FPTypeParams.cs
   :language: csharp
   :refnum:   2
   :caption:  Fingerprint parameters
   :frag:     SNIPPET-FPTYPE-PARAMS


The output of :oe:src:`Listing 2<SNIPPET-FPTYPE-PARAMS-FPTypeParams>` is the following:

::

  version = 2.0.0
  number of bits = 4096
  min bonds = 0
  max bonds = 5
  atom types = AtmNum|Arom|Chiral|FCharge|HvyDeg|Hyb|EqHalo
  bond types = Order|Chiral


.. seealso::

   * :ref:`chapter_user_defined` chapter  
   * :oe:func:`OEGraphSim::OEIsValidFPTypeString` function 
   * :oe:func:`OEGraphSim::OEGetFPType` function 
   * :oe:constns:`OEGraphSim::OEFPAtomType` namespace  
   * :oe:func:`OEGraphSim::OEGetFPAtomType` function
   * :oe:constns:`OEGraphSim::OEFPBondType` namespace  
   * :oe:func:`OEGraphSim::OEGetFPBondType` function

.. _section_fptype_version_number:

Fingerprint version number
================================================================================

Each fingerprint type additionally has a version number. Version
numbers are introduced in order to keep track of changes in the
fingerprint generation algorithm itself.
The :oe:meth:`OEGraphSim::OEFPTypeBase::GetFPVersionString` method
returns the string representation of the fingerprint version.

.. oe:source:: FPTypeString.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-FP-VERSION

.. oe:source:: FPTypeString.py
   :language: python
   :noindent:
   :frag:     SNIPPET-FP-VERSION

..    oe:language:: python

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


.. oe:source:: FPTypeString.java
   :language: java
   :noindent:
   :frag:     SNIPPET-FP-VERSION

.. oe:source:: FPTypeString.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-FP-VERSION

The output of  the preceding snippet is the following:

::

  2.0.0

.. warning::

   The version number of the fingerprints will not be changed with each
   release. It will be incremented only if modifications or bug fixes
   to the corresponding algorithm would result in generating a different
   bit-vector for the same molecules.

   Fingerprints with an old version number will be still readable and
   comparable with each other but not with fingerprints which have
   different version number.
