.. _chapter_overlap:

********************************************************************************
Fingerprint Overlap
********************************************************************************

The :oe:func:`OEGraphSim::OEGetFPOverlap` function provides access to the
fragments of two molecules that are considered equivalent based on a specific
fingerprint type.
This means that the returned fragment-pairs set the same bit "on" when
fingerprints are generated.
The following example shows how to retrieve the common five bond-length
patterns of two molecules.

.. oe:source:: FPOverlap.py
   :language: python
   :refnum:   18
   :caption:  Example of accessing common patterns based on a fingerprint
   :frag:     SNIPPET-FPOVERLAP

..    oe:language:: python

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



.. oe:source:: FPOverlap.cpp
   :language: c++
   :refnum:   18
   :caption:  Example of accessing common patterns based on a fingerprint
   :frag:     SNIPPET-FPOVERLAP

.. oe:source:: FPOverlap.java
   :language: java
   :refnum:   18
   :caption:  Example of accessing common patterns based on a fingerprint
   :frag:     SNIPPET-FPOVERLAP

.. oe:source:: FPOverlap.cs
   :language: csharp
   :refnum:   18
   :caption:  Example of accessing common patterns based on a fingerprint
   :frag:     SNIPPET-FPOVERLAP

The first three matches returned by the :oe:src:`Listing 18<SNIPPET-FPOVERLAP-FPOverlap>` are
depicted in the next table.
The output of code  is the following:

::

   match  1: 3C-2C  9C-11C  4C-3C  8C-10C  7C-7C  11C-8C
   match  2: 3C-2C  4C-3C  5C-4C  6C-6C  7C-7C  8C-8C
   match  3: 3C-2C  4C-3C  5C-4C  6C-6C  7C-7C  8C-10C
   match  4: 3C-2C  4C-3C  5C-4C  6C-6C  7C-7C  11C-8C
   match  5: 3C-2C  4C-3C  5C-4C  6C-6C  7C-7C  11C-10C
   match  6: 3C-2C  9C-11C  4C-3C  6C-6C  7C-7C  11C-8C

   ... truncated  ...

.. list-table:: **Example of matches returned by the OEGetFPOverlap function.** The numbers depicted next to the atoms are the atom indices.
   :widths: 300
   :header-rows: 0

   * - .. image:: images/FPOverlap-01.*
          :scale:  100
          :align:  center
   * - .. image:: images/FPOverlap-02.*
          :scale:  100
          :align:  center
   * - .. image:: images/FPOverlap-03.*
          :scale:  100
          :align:  center


.. warning::

   Even though the :oe:func:`OEGraphSim::OEGetFPOverlap` function returns
   an iterator of :ref:`OEMatchBase <OEChem_OEMatchBase>` objects, they are not
   matches in the traditional sense, i.e. the atom-pair and bond-pair
   correspondences between the pattern and the target atoms and
   bonds are not guaranteed. See example depicted below.

.. figure:: images/FPOverlap-NonPair-01.*
   :align:  center

   **The two highlighted patterns set the same bit when fingerprints
   are generated, but the returned match is not pairwise**.
   The numbers depicted next to the atoms are the atom indices.

.. seealso::

   * :oe:func:`OEGraphSim::OEGetFPCoverage` function
   * :ref:`chapter_coverage` chapter


.. hint::

   The :oe:func:`OEGraphSim::OEGetFPOverlap` can be used to visualize molecule similarity based on
   a given fingerprint type. See more details in:

   * :ref:`oegraphsim_section_visualizing_molecule_similarity` section
   * `Depicting Molecule Similarity section in
     OpenEye Python Cookbook <http://docs.eyesopen.com/python_modules/cookbook/depiction/simcalc.html>`_
