.. include:: ../../toolkit-substitutions

.. oe:namespace:: OEChem


.. _OEChem_OESubSearchResult:

.. oe:class:: OESubSearchResult

   .. attention::

      |TWOLANGUAGE|

   .. oe:api::

      class OESubSearchResult

   The :ref:`OESubSearchResult <OEChem_OESubSearchResult>` class is used to store the results
   of a substructure search along with reporting the progress of the search
   (:oe:meth:`OEChem::OESubSearchDatabase::Search`).
   The :ref:`OESubSearchResult <OEChem_OESubSearchResult>` class provides progress with updating the
   following counters:

   .. list-table::
      :widths: 100 100
      :header-rows: 1

      * - Counter
        - Description

      * - :oe:meth:`NumTargets<OEChem::OESubSearchResult::NumTargets>`
        - number of molecules in the database

      * - :oe:meth:`NumScreened<OEChem::OESubSearchResult::NumScreened>`
        - number of molecules eliminated by their screen

      * - :oe:meth:`NumSearched<OEChem::OESubSearchResult::NumSearched>`
        - number of molecules searched

      * - :oe:meth:`NumTotalMatches<OEChem::OESubSearchResult::NumTotalMatches>`
        - total number of matches identified

      * - :oe:meth:`NumMatches<OEChem::OESubSearchResult::NumMatches>`
        - total number of matches kept

   If the search is not canceled at the end of the search:

   .. math::

       number\ of\ targets = number\ of\ screened + number\ of\ searched

   The success of the screen (in percentages) is defined as:

   .. math::

      \frac{number\ of\ screened + number\ of\ total\ matches}{number\ of\ targets} * 100.0

   Where ``100.0%`` means that no false positive was detected i.e. each molecule that passed
   the screening phase was a real match.

   .. seealso::

      * :oe:meth:`OEChem::OESubSearchDatabase::Search` method

   .. admonition:: Code Example

      * :ref:`section_example_oechem_searchfastss` example

   .. oe:method:: Constructors

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

         .. oe:api::

            OESubSearchResult()

      .. oe:language:: python

         .. oe:api:: python

            OESubSearchResult() -> OESubSearchResult

      Default constructor that creates an empty result object.

   .. oe:method:: Cancel

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

         .. oe:api::

            void Cancel()

      .. oe:language:: python

         .. oe:api:: python

            Cancel() -> None

      Cancels the ongoing substructure search. The search might not be immediately
      terminated, but no new molecules will be submitted for substructure search.
      The status of the search will be
      :oe:const:`OEChem::OESubSearchStatus::Canceled`.

   .. oe:method:: GetMatchIndices

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

         .. oe:api::

            OESystem::OEIterBase<size_t>* GetMatchIndices() const

      .. oe:language:: python

         .. oe:api:: python

            GetMatchIndices() -> Iterable[int]

      Returns the indices of the matched molecules. The matched molecules
      can be retried from the database by using the
      :oe:meth:`OEChem::OESubSearchDatabase::GetMolecule` method.

   .. oe:method:: GetSearchStatus

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

         .. oe:api::

            unsigned GetSearchStatus() const

      .. oe:language:: python

         .. oe:api:: python

            GetSearchStatus() -> int

      Returns the status of the substructure search defined in
      the :oe:constns:`OEChem::OESubSearchStatus` namespace.

   .. oe:method:: IsValid

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

         .. oe:api::

            bool IsValid() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool

      Returns whether the :ref:`OESubSearchResult <OEChem_OESubSearchResult>` object is valid.

   .. oe:method:: NumMatches

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

         .. oe:api::

            size_t NumMatches() const

      .. oe:language:: python

         .. oe:api:: python

            NumMatches() -> int

      Returns the number of kept matches which can be retrieved via
      the :oe:meth:`OEChem::OESubSearchResult::GetMatchIndices` method.
      After the search limit is reached
      (defined by :oe:cls:`GetMaxMatches<OEChem::OESubSearchQuery::GetMaxMatches>`), only
      the :oe:meth:`NumTotalMatches<OEChem::OESubSearchResult::NumTotalMatches>`
      counter will be updated.

      .. seealso::

         * :oe:meth:`OEChem::OESubSearchResult::NumTotalMatches` method

   .. oe:method:: NumScreened

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

         .. oe:api::

            size_t NumScreened() const

      .. oe:language:: python

         .. oe:api:: python

            NumScreened() -> int

      Returns the number of molecules that could be eliminated by their
      screens.

      .. seealso::

         * :oe:func:`OEChem::OEScreen` function

   .. oe:method:: NumSearched

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

         .. oe:api::

            size_t NumSearched() const

      .. oe:language:: python

         .. oe:api:: python

            NumSearched() -> int

      Returns the number of molecules that have to be searched i.e.
      the number of times :ref:`OESubSearch <OEChem_OESubSearch>` has to be used.

   .. oe:method:: NumTargets

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

         .. oe:api::

            size_t NumTargets() const

      .. oe:language:: python

         .. oe:api:: python

            NumTargets() -> int

      Returns the number of target molecules i.e the number of molecules
      in the database.

   .. oe:method:: NumTotalMatches

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

         .. oe:api::

            size_t NumTotalMatches() const

      .. oe:language:: python

         .. oe:api:: python

            NumTotalMatches() -> int

      Returns the total number of matches in the database.

      .. seealso::

         * :oe:meth:`OEChem::OESubSearchResult::NumMatches` method
