.. oe:namespace:: OEChem



.. meta::
   :keywords: OEMCSFunc, MCSFunc


.. _OEChem_OEMCSFunc:

.. oe:class:: OEMCSFunc

   .. oe:api::


      class OEMCSFunc

   The :ref:`OEMCSFunc <OEChem_OEMCSFunc>` is an abstract base class that
   defines the API used for scoring subgraph matches.

   The scores generated by implementations of
   :ref:`OEMCSFunc <OEChem_OEMCSFunc>` influence the sorting and retention of
   maximum common subgraph matches generated by the
   :ref:`OEMCSSearch <OEChem_OEMCSSearch>` and the :ref:`OECliqueSearch <OEChem_OECliqueSearch>`
   classes.

   The following classes derive from this class:
    * :ref:`OEMCSMaxAtoms <OEChem_OEMCSMaxAtoms>`
    * :ref:`OEMCSMaxAtomsCompleteCycles <OEChem_OEMCSMaxAtomsCompleteCycles>`
    * :ref:`OEMCSMaxBonds <OEChem_OEMCSMaxBonds>`
    * :ref:`OEMCSMaxBondsCompleteCycles <OEChem_OEMCSMaxBondsCompleteCycles>`

   .. seealso::

      * :oe:meth:`OEChem::OEMCSSearch::SetMCSFunc` method
      * :oe:meth:`OEChem::OECliqueSearch::SetMCSFunc` method

   .. note::

      Custom implementation of :ref:`OEMCSFunc <OEChem_OEMCSFunc>` can be done by deriving
      from the :ref:`OEMCSFunc <OEChem_OEMCSFunc>` class and implementing all of the methods
      listed below.

   .. oe:source:: CustomMCSFunc.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-CUSTOM-MCSFUNC
      :caption:  Example of using custom scoring function

   .. oe:source:: CustomMCSFunc.py
      :language: python
      :noindent:
      :frag:     SNIPPET-CUSTOM-MCSFUNC
      :caption:  Example of using custom scoring function

   .. oe:method:: operator()

      .. oe:language:: c++ java csharp

         .. oe:api::

            double operator()(const OEMolBase& pattern, const OEMolBase& target, OEAtomBase** amap, OEBondBase** bmap)=0

      .. oe:language:: python

         .. oe:api:: python

            __call__(pattern: Union[OEGraphMol,OEMol,OEQMol],
                     target: Union[OEGraphMol,OEMol,OEQMol], amap: OEAtomBase,
                     bmap: OEBondBase) -> float

      This method is called automatically by the
      :ref:`OEMCSSearch <OEChem_OEMCSSearch>` and :ref:`OECliqueSearch <OEChem_OECliqueSearch>`
      classes when a common subgraph of two molecules is identified.

      The 'pattern' (query) molecule and 'target' molecule currently
      being matched are passed as the first and second arguments to
      the function.
      The arrays of pointers to atoms ('amap') and bonds ('bmap') hold
      the atom and bond correspondences between the pattern and
      target.
      The arrays are the length of the maximum atom and bond indices
      of the pattern molecule.
      The indices of the atoms and bonds in the pattern molecule can
      be used to look up the corresponding atoms and bonds in the
      target molecule.
      Subgraphs may not include all pattern atoms. Array positions for
      unmatched atoms and bonds are assigned to the NULL pointer.

      The integer part of the floating point value returned by the
      method is used to determine maximal common subgraphs.

      All integer part scores which are smaller than the maximum
      computed value for any subgraph are discarded by
      :ref:`OEMCSSearch <OEChem_OEMCSSearch>`.
      In case of :ref:`OECliqueSearch <OEChem_OECliqueSearch>` the any subgraph are
      discarded that has a smaller scoring value than the maximum
      score minus the 'range' set by
      :oe:meth:`OEChem::OECliqueSearch::SetSaveRange`.

      The decimal part of the floating point value returned by the
      method is used to sort the matches found by
      :ref:`OEMCSSearch <OEChem_OEMCSSearch>` or :ref:`OECliqueSearch <OEChem_OECliqueSearch>`
      For example, by scoring matches using the function

      :math:`num.\ of\ mapped\ atoms + \frac{num.\ of\ mapped\ bonds}{100}`

      all matches which have the same number of subgraph atoms would
      be retained but the matches would be returned in order of
      decreasing number of bonds matched.

   .. oe:method:: CreateCopy

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEMCSFunc* CreateCopy() const = 0

      .. oe:language:: python

         .. oe:api:: python

            CreateCopy() -> OEMCSFunc

      Deep copy constructor that returns a copy of the object.
      The memory for the returned :ref:`OEMCSFunc <OEChem_OEMCSFunc>` object
      is dynamically allocated  and owned by the caller.

      .. oe:language:: c++

         The returned copy should be deallocated using C++
         delete operator in order to prevent a memory leak.

