.. oe:namespace:: OEChem

.. meta::
   :keywords: OECliqueSearch, CliqueSearch


.. _OEChem_OECliqueSearch:

.. oe:class:: OECliqueSearch

   .. oe:api::

      class OECliqueSearch

   This class represents `OECliqueSearch`.

   The :ref:`OECliqueSearch <OEChem_OECliqueSearch>` class performs bounded common
   substructure searches.
   It is a useful search method in cases where common substructures other than
   the maximum common substructure (:ref:`OEMCSSearch <OEChem_OEMCSSearch>`)
   need to be identified.

   .. seealso::

      .. oe:language:: c++

         * :ref:`section_patternmatch_clique` section
         * Example program :ref:`cliquealign.cpp<section_example_oechem_cliquealign>`

      .. oe:language:: python

         * :ref:`section_patternmatch_clique` section
         * Example program :ref:`cliquealign.py<section_example_oechem_cliquealign>`

      .. oe:language:: java

         * :ref:`section_patternmatch_clique` section
         * Example program :ref:`CliqueAlign.java<section_example_oechem_cliquealign>`

      .. oe:language:: csharp

         * :ref:`section_patternmatch_clique` section
         * Example program :ref:`CliqueAlign.cs<section_example_oechem_cliquealign>`

   .. oe:method:: Constructors

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

         .. oe:api::

            OECliqueSearch(unsigned int type = OEMCSType::Default)

      .. oe:language:: python

         .. oe:api:: python

            OECliqueSearch(type: int) -> OECliqueSearch

      Default constructor.

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

         .. oe:api::

            OECliqueSearch(const OECliqueSearch &)

      .. oe:language:: python

         .. oe:api:: python

            OECliqueSearch(arg2: OECliqueSearch) -> OECliqueSearch

      Copy constructor.

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

         .. oe:api::

            OECliqueSearch(const char* smarts,
                           unsigned int type = OEMCSType::Default)

      .. oe:language:: python

         .. oe:api:: python

            OECliqueSearch(arg2: str, type: int) -> OECliqueSearch

      Constructs an :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object using a 'smarts' pattern.
      The :term:`SMARTS` pattern is parsed into a query molecule
      (:ref:`OEQMolBase <OEChem_OEQMolBase>`).
      The valid types of the :ref:`OECliqueSearch <OEChem_OECliqueSearch>` are defined
      in the :oe:constns:`OEChem::OEMCSType` namespace.

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

         .. oe:api::

            OECliqueSearch(const OEQMolBase &, bool perception = true,
                           unsigned int type = OEMCSType::Default)

      .. oe:language:: python

         .. oe:api:: python

            OECliqueSearch(arg2: OEQMol, makeCopy: bool = True, type: int) -> OECliqueSearch

      Constructs an :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object using a query molecule
      (:ref:`OEQMolBase <OEChem_OEQMolBase>`).

      *qmol*
        The query molecule of the MCS search.

      *type*
        The type of the :ref:`OECliqueSearch <OEChem_OECliqueSearch>` from the
        :oe:constns:`OEChem::OEMCSType` namespace.

      *perception*
         If ``true``, then ring perception is performed on the query molecule.

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

         .. oe:api::

            OECliqueSearch(const OEMolBase &, unsigned int atomexpr,
                           unsigned int bondexpr,
                           unsigned int type = OEMCSType::Default)

      .. oe:language:: python

         .. oe:api:: python

            OECliqueSearch(arg2: Union[OEGraphMol,OEMol,OEQMol], arg3: int,
                           arg4: int, type: int) -> OECliqueSearch

      Constructs an :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object using a molecule and expression options.
      The atom and bond expression options passed as the second and
      third arguments to the method are defined in the
      :oe:constns:`OEChem::OEExprOpts` namespace.
      The expression options are used to convert the atom and bond
      data into expression trees which are used during the common
      subgraph search.

   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OECliqueSearch &operator=(const OECliqueSearch &rhs)

      Assignment operator that copies the data of the 'rhs' :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object
      into the right-hand side :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object.

      Assignment operator.


   .. oe:method:: operator bool

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

         .. oe:api::

            operator bool() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool

      Test for successful initialization of an
      :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object.
      If initialization was attempted with an invalid :term:`SMARTS`
      pattern or query molecule (:ref:`OEQMolBase <OEChem_OEQMolBase>`) then
      this method will return ``false``.
      If initialization was completed successfully this method will
      return ``true``.
      An :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object is considered to be
      uninitialized when constructed with the default constructor.

   .. oe:method:: AddConstraint

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

         .. oe:api::

            bool AddConstraint(const OEMatchPair<OEAtomBase> &)
            bool AddConstraint(const OEMatchPair<OEBondBase> &)

      .. oe:language:: python

         .. oe:api:: python

            AddConstraint(arg2: OEMatchPairAtom) -> bool
            AddConstraint(arg2: OEMatchPairBond) -> bool

      The search space of a common subgraph determination can
      be restricted by constraining pairs of nodes or edges (atoms or
      bonds) to be mapped onto one another in all subgraph solutions.
      Failure to satisfy atom or bond pairwise constraints will prevent
      any subgraph solutions from being identified.
      Constraints are considered satisfied in subgraphs which do not
      contain any constrained atoms or bonds in either the pattern or
      target molecules.

      Both :oe:meth:`OEChem::OECliqueSearch::AddConstraint` methods return
      ``true`` if a constraint is added successfully.
      If the pattern atom or bond in the :ref:`OEMatchPair <OEChem_OEMatchPair>`
      does not exist as part of the query molecule created in the
      initialization of the :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object then
      :oe:meth:`OEChem::OECliqueSearch::AddConstraint` will return
      ``false``.
      Multiple calls to :oe:meth:`OEChem::OECliqueSearch::AddConstraint`
      using the same pattern atom or bond will cause previously stored
      constraints to be overwritten as constraints are mutually
      exclusive.
      It is impossible to satisfy multiple simultaneous constraints
      for a single pattern atom or bond, hence the exclusivity.

   .. oe:method:: ClearConstraints

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

         .. oe:api::

            void ClearConstraints()

      .. oe:language:: python

         .. oe:api:: python

            ClearConstraints() -> None

      Clears all prior match constraints set with the
      :oe:meth:`OEChem::OECliqueSearch::AddConstraint` methods.

   .. oe:method:: GetMaxMatches

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

         .. oe:api::

            unsigned int GetMaxMatches() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxMatches() -> int

      Returns the maximum number of subgraphs
      that the :ref:`OECliqueSearch <OEChem_OECliqueSearch>` will identify
      before terminating the search.
      A value of zero indicates that no arbitrary limit has been set
      on the total number of subgraphs to be identified.
      By default, the maximum number of matches is set to ``1024``
      This value can be set using the
      :oe:meth:`OEChem::OECliqueSearch::SetMaxMatches` method.

   .. oe:method:: GetMinAtoms

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

         .. oe:api::

            unsigned int GetMinAtoms() const

      .. oe:language:: python

         .. oe:api:: python

            GetMinAtoms() -> int

      Returns the minimum number of atoms of a subgraph that
      can be returned as a common subgraph.
      This value can be set using the
      :oe:meth:`OEChem::OECliqueSearch::SetMinAtoms` method.

   .. oe:method:: GetPattern

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

         .. oe:api::

            const OEQMolBase& GetPattern() const

      .. oe:language:: python

         .. oe:api:: python

            GetPattern() -> OEQMol

      Returns a read-only reference to the query molecule
      (:ref:`OEQMolBase <OEChem_OEQMolBase>`) of :ref:`OECliqueSearch <OEChem_OECliqueSearch>`.
      Const :ref:`OEQMolBase <OEChem_OEQMolBase>` methods can be used on the
      returned :ref:`OEQMolBase <OEChem_OEQMolBase>` reference.
      If the :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object has not been
      initialized, a reference to an empty molecule will be returned.

   .. oe:method:: GetSaveRange

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

         .. oe:api::

            unsigned int GetSaveRange() const

      .. oe:language:: python

         .. oe:api:: python

            GetSaveRange() -> int

      This value can be set using the :oe:meth:`OEChem::OECliqueSearch::SetSaveRange` method.
      Any subgraphs found by the MCS function used by the search are discarded that have a smaller scoring value than
      the maximum score minus this ‘range’. See :ref:`OEMCSSearch <OEChem_OEMCSSearch>` for more details.

   .. oe:method:: Init

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

         .. oe:api::

            bool Init(const char* smarts)

      .. oe:language:: python

         .. oe:api:: python

            Init(arg2: str) -> bool

      (Re)initializes an :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object using a
      'smarts' pattern.
      The :term:`SMARTS` pattern is parsed to create a query molecule
      available for subgraph matching.
      The method will return ``true`` if initialization completes
      successfully, and ``false`` upon failure.

      .. note::

         Prior state information is cleared before initialization, and
         is lost even if the method fails to initialize properly.

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

         .. oe:api::

            bool Init(const OEQMolBase& qmol, bool perception = true)

      .. oe:language:: python

         .. oe:api:: python

            Init(arg2: OEQMol, makeCopy: bool = True) -> bool

      (Re)initializes an :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object using a
      query molecule (:ref:`OEQMolBase <OEChem_OEQMolBase>`) reference.
      The method will return ``true`` if initialization completes
      successfully, and ``false`` upon failure.

      *qmol*
        The query molecule of the MCS search.

      *perception*
         If ``true``, then ring perception is performed on the query molecule.

      .. note::

         Prior state information is cleared before initialization, and
         is lost even if the method fails to initialize properly.

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

         .. oe:api::

            bool Init(const OEMolBase& mol, unsigned int atomexpr,
                      unsigned int bondexpr)

      .. oe:language:: python

         .. oe:api:: python

            Init(arg2: Union[OEGraphMol,OEMol,OEQMol], arg3: int, arg4: int) -> bool

      (Re)initializes an :ref:`OECliqueSearch <OEChem_OECliqueSearch>`
      object using a molecule (:ref:`OEMolBase <OEChem_OEMolBase>`) and
      expression options used to convert the molecule into a query
      molecule (:ref:`OEQMolBase <OEChem_OEQMolBase>`).
      The atom and bond expression options passed as the second and
      third arguments to the method are defined in the
      :oe:constns:`OEChem::OEExprOpts` namespace.
      Expression options are used to convert the atom and bond data
      into expression trees which are used during the common subgraph
      search.
      The method will return ``true`` if initialization completes
      successfully, and ``false`` upon failure.

      .. note::

         Prior state information is cleared before initialization, and
         is lost even if the method fails to initialize properly.

   .. oe:method:: Match

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

         .. oe:api::

            OESystem::OEIterBase<OEMatchBase>* Match(const OEMolBase &)

      .. oe:language:: python

         .. oe:api:: python

            Match(arg2: Union[OEGraphMol,OEMol]) -> Iterable[OEMatchBase]

      Performs search in order to identify common subgraphs (cliques)
      shared between the passed :ref:`OEMolBase <OEChem_OEMolBase>` and the
      query molecule which the :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object was
      initialized.
      It returns an iterator pointer (:ref:`OEIterBase <OESystem_OEIterBase>`)
      over graph matches (:ref:`OEMatchBase <OEChem_OEMatchBase>`), and should be
      assigned to an :ref:`OEIter <OESystem_OEIter>` < :ref:`OEMatchBase <OEChem_OEMatchBase>` >
      in order to prevent memory leaks.

      If the 'uniquematch'  argument passed to the methods is ``true`` then
      only the unique matches will be returned  in the iterator over the matches.
      By definition, a match or subgraph is considered unique if it differs
      from all other subgraphs found previously by at least one atom or
      bond.
      Additionally, it is also considered unique if the query subgraph
      is mapped to a different part of the target
      (See example in the :ref:`section_patternmatch_mcss` section)

      .. oe:api:  IGNORED - NOT IMPLEMENTED YET

         OESystem::OEIterBase<OEMatchBase> *Match(const OEQMolBase &)

   .. oe:method:: SetMCSFunc

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

         .. oe:api::

            bool SetMCSFunc(const OEMCSFunc &)

      .. oe:language:: python

         .. oe:api:: python

            SetMCSFunc(arg2: OEMCSFunc) -> bool

      Stores a copy of the passed :ref:`OEMCSFunc <OEChem_OEMCSFunc>` functor
      in the :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object.
      The functor is then used to evaluate and order subgraphs found
      during a common subgraph search.

      .. seealso::

         * :ref:`OEMCSFunc <OEChem_OEMCSFunc>`
         * :ref:`OEMCSMaxAtoms <OEChem_OEMCSMaxAtoms>`
         * :ref:`OEMCSMaxBonds <OEChem_OEMCSMaxBonds>`
         * :ref:`OEMCSMaxAtomsCompleteCycles <OEChem_OEMCSMaxAtomsCompleteCycles>`
         * :ref:`OEMCSMaxBondsCompleteCycles <OEChem_OEMCSMaxBondsCompleteCycles>`

   .. oe:method:: SetMaxMatches

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

         .. oe:api::

            bool SetMaxMatches(unsigned int)

      .. oe:language:: python

         .. oe:api:: python

            SetMaxMatches(arg2: int) -> bool

      Sets the maximum number of common subgraph (clique) matches that
      will be returned by the :oe:meth:`OEChem::OECliqueSearch::Match`
      method.
      The default limit set upon construction of an
      :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object is ``1024`` matches.
      This value can be retrieved
      using the :oe:meth:`OEChem::OECliqueSearch::GetMaxMatches` method.

   .. oe:method:: SetMinAtoms

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

         .. oe:api::

            bool SetMinAtoms(unsigned int)

      .. oe:language:: python

         .. oe:api:: python

            SetMinAtoms(arg2: int) -> bool

      Sets the minimum number of atoms required of a subgraph match to
      be returned a solution by a clique search.
      A single atom can be a perfectly valid common subgraph,
      however, for many applications such a small subgraph may not be
      considered useful.
      Setting the minimum number of atoms to an appropriate size
      prevents unproductive subgraph matches from being returned by
      the :oe:meth:`OEChem::OECliqueSearch::Match` method.
      The default value for the minimum number of atoms in a subgraph
      match is set to ``1`` upon construction of an
      :ref:`OECliqueSearch <OEChem_OECliqueSearch>` object.
      This value can be retrieved using the
      :oe:meth:`OEChem::OECliqueSearch::GetMinAtoms` method.

   .. oe:method:: SetSaveRange

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

         .. oe:api::

            bool SetSaveRange(unsigned int)

      .. oe:language:: python

         .. oe:api:: python

            SetSaveRange(arg2: int) -> bool

      Sets the range of the clique search.
      This value can be retrieved using the
      :oe:meth:`OEChem::OECliqueSearch::GetSaveRange` method.

   .. oe:method: SingleMatch  IGNORED - NOT IMPLEMENTED YET

      .. oe:api::

         bool SingleMatch(const OEMolBase &)

      .. oe:api::

         bool SingleMatch(const OEQMolBase &)

