.. _chapter_coverage:

********************************************************************************
Fingerprint Coverage
********************************************************************************

Fingerprints are usually generated by enumerating various fragments (patterns)
of a molecule and then hashing them into a fixed-length bitvector.
The :oe:func:`OEGraphSim::OEGetFPCoverage` function provides access to these
fragments by returning an iterator over :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` objects,
each of which storing the atoms and bonds of a specific fragment.

.. seealso::

   * :ref:`chapter_patterns` chapter that shows how to access more information about
     the fragments enumerated during the fingerprint generation

The following example shows how the retrieve the unique fragments that
are enumerated when generating a path fingerprint.
The obtained fragments are depicted in
:ref:`Table: Example of path fragments<table_coverage_path_unique>`

..  oe:source:: FPCoverage.py
    :language: python
    :refnum:   17
    :caption:  Example of accessing patterns encoded into a fingerprint
    :frag:     SNIPPET-COVERAGE

..  oe:language:: python

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

.. oe:source:: FPCoverage.cpp
   :language: c++
   :refnum:   17
   :caption:  Example of accessing patterns encoded into a fingerprint
   :frag:     SNIPPET-COVERAGE

.. oe:source:: FPCoverage.java
   :language: java
   :refnum:   17
   :caption:  Example of accessing patterns encoded into a fingerprint
   :frag:     SNIPPET-COVERAGE

.. oe:source:: FPCoverage.cs
   :language: csharp
   :refnum:   17
   :caption:  Example of accessing patterns encoded into a fingerprint
   :frag:     SNIPPET-COVERAGE

The output of :oe:src:`Listing 17<SNIPPET-COVERAGE-FPCoverage>` is the following:

::

   1  0 C
   2  0 C  1 C
   3  0 C  1 C  2 N
   4  0 C  1 C  2 N  3 C
   5  0 C  1 C  2 N  3 C  4 C
   6  1 C
   7  1 C  2 N
   8  1 C  2 N  3 C
   9  1 C  2 N  3 C  4 C
  10  2 N

.. _table_coverage_path_unique:

.. list-table:: **Example of unique path fragments.** The numbers displayed next to atoms are the atom indices.
   :widths: 150 150 150
   :header-rows: 0

   * - .. image:: images/FPCoverage-01.*
          :align:  center
     - .. image:: images/FPCoverage-02.*
          :align:  center
     - .. image:: images/FPCoverage-03.*
          :align:  center
   * - .. image:: images/FPCoverage-04.*
          :align:  center
     - .. image:: images/FPCoverage-05.*
          :align:  center
     - .. image:: images/FPCoverage-06.*
          :align:  center
   * - .. image:: images/FPCoverage-07.*
          :align:  center
     - .. image:: images/FPCoverage-08.*
          :align:  center
     - .. image:: images/FPCoverage-09.*
          :align:  center
   * - .. image:: images/FPCoverage-10.*
          :align:  center
     -
     -

The :oe:func:`OEGraphSim::OEGetFPCoverage` function in the
:oe:src:`Listing 17<SNIPPET-COVERAGE-FPCoverage>` example is called with a unique options.
This means that it returns only unique fragments, where a fragment
(*i.e.* subgraph) is considered unique, if it differs from all other
subgraphs identified previously by at least one atom or bond.
For example, executing the same code with a non-unique option would
generate five additional paths depicted in
:ref:`Table:  Example of additional non-unique path fragments<table_coverage_path_non_unique>`

.. _table_coverage_path_non_unique:

.. list-table:: **Example of additional non-unique path fragments.** The numbers displayed next to atoms are the atom indices.
   :widths: 150 150 150
   :header-rows: 0

   * - .. image:: images/FPCoverage-NonUnique-11.*
          :align:  center
     - .. image:: images/FPCoverage-NonUnique-12.*
          :align:  center
     - .. image:: images/FPCoverage-NonUnique-13.*
          :align:  center
   * - .. image:: images/FPCoverage-NonUnique-14.*
          :align:  center
     - .. image:: images/FPCoverage-NonUnique-15.*
          :align:  center
     -

.. seealso::

   * :oe:func:`OEGraphSim::OEGetFPOverlap` function
   * :ref:`chapter_overlap` chapter
