
.. oe:namespace:: OEMedChem

.. meta::
   :keywords: OEMCSFragDatabase, MCSFragDatabase


.. _OEMedChem_OEMCSFragDatabase:

.. oe:class:: OEMCSFragDatabase

   .. oe:api::

      class OEMCSFragDatabase

   Performs a fragmentation indexing on an input set of structures to enable
   MCS-based similarity searching for compounds with common cores.

   .. seealso::

      * :ref:`OEMCSFragDatabaseOptions <OEMedChem_OEMCSFragDatabaseOptions>` class

   .. oe:method:: Constructors

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

         .. oe:api::

            OEMCSFragDatabase(const OEMCSFragDatabaseOptions& opts = OEMCSFragDatabaseOptions())

      .. oe:language:: python

         .. oe:api:: python

            OEMCSFragDatabase(opts: OEMCSFragDatabaseOptions = OEMCSFragDatabaseOptions()) -> OEMCSFragDatabase

      Default constructor that initializes the fragment database with the default options defined by
      :ref:`OEMCSFragDatabaseOptions <OEMedChem_OEMCSFragDatabaseOptions>`.

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

         .. oe:api::

            OEMCSFragDatabase(const OEMCSFragDatabaseOptions& opts = OEMCSFragDatabaseOptions())

      .. oe:language:: python

         .. oe:api:: python

            OEMCSFragDatabase(opts: OEMCSFragDatabaseOptions = OEMCSFragDatabaseOptions()) -> OEMCSFragDatabase

      Constructor that initializes the fragment database with the options defined by
      the :ref:`OEMCSFragDatabaseOptions <OEMedChem_OEMCSFragDatabaseOptions>` argument.

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

      .. oe:api::

         OEMCSFragDatabase & operator=(const OEMCSFragDatabase & rhs)

      Assignment operator.


   .. oe:method:: AddConstMol

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

         .. oe:api::

            int AddConstMol(const OEChem::OEMolBase& inmol, int recordID = (-1))

      .. oe:language:: python

         .. oe:api:: python

            AddConstMol(inmol: Union[OEGraphMol,OEMol,OEQMol], recID: int = -1) -> int

      Adds the molecule to the index and returns the 0-based recordID
      if the structure was successfully added, or a negative index if the structure
      was unable to be indexed. Negative values can be used to retrieve
      status information for indexing failures. The optional user-defined
      recordID is provided to allow indexed fragments to be referenced
      to externally maintained data structures.  If the provided recordID is
      less than zero, an autogenerated index is returned which is
      an index greater than all ids seen so far.

   .. seealso::

      * :oe:constns:`OEMedChem::OEMatchedPairIndexStatus`
      * :oe:func:`OEMedChem::OEMatchedPairIndexStatusName`

   .. oe:method:: AddMol

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

         .. oe:api::

            int AddMol(OEChem::OEMolBase& inmol, int recordID = (-1))

      .. oe:language:: python

         .. oe:api:: python

            AddMol(inmol: Union[OEGraphMol,OEMol,OEQMol], recID: int = -1) -> int

      A high performance version of :oe:meth:`OEMedChem::OEMCSFragDatabase::AddConstMol`
      that eliminates molecule copy activities and modifies the passed molecule directly.
      The state of the returned structure after indexing activities is *undefined* and
      should generally be discarded or reinstantiated from the original source for
      any subsequent activities.

   .. oe:method:: ClearIndexedMols

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

         .. oe:api::

            void ClearIndexedMols()

      .. oe:language:: python

         .. oe:api:: python

            ClearIndexedMols() -> None

      This method discards the current index contents and frees internal memory in
      preparation for subsequent reindexing.

   .. oe:method:: CoreToMolecules

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

         .. oe:api::

            OESystem::OEIterBase<unsigned int>*CoreToMolecules(const std::string& core) const

      .. oe:language:: python

         .. oe:api:: python

            CoreToMolecules(core: str) -> Iterable[int]

      Given a fragmentation core, return the molecule ids that have this core from the index.

   .. oe:method:: CoreToMoleculeCount

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

         .. oe:api::

            unsigned int CoreToMoleculeCount(const std::string& core) const

      .. oe:language:: python

         .. oe:api:: python

            CoreToMoleculeCount(core: str) -> int

      Given a fragmentation core, return a count of the number of molecules that have this core in the index.

   .. oe:method:: GetMaxCoreMolecule

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

         .. oe:api::

            std::string GetMaxCoreMolecule(const char delim = '.') const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxCoreMolecule(delim: str = '.') -> str

      Return the most common core fragment(s) recorded in the index.  If there are multiple cores with the same occurrence count,
      the specified ``delim`` character is used to delimit the strings.

   .. oe:method:: GetMaxCoreMoleculeCount

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

         .. oe:api::

            unsigned int GetMaxCoreMoleculeCount() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxCoreMoleculeCount() -> int

      Return the maximum core occurrence count recorded in the index.

   .. oe:method:: GetMaxMolIdx

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

         .. oe:api::

            unsigned int GetMaxMolIdx() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxMolIdx() -> int

      Returns the highest molecule id currently present in the index.

   .. oe:method:: GetOptions

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

         .. oe:api::

            const OEMCSFragDatabaseOptions& GetOptions() const

      .. oe:language:: python

         .. oe:api:: python

            GetOptions() -> OEMCSFragDatabaseOptions

      Returns the currently active options for the instance.  Options
      cannot be changed, and require the desired options to be provided
      when the index is instantiated.

   .. oe:method:: GetScores

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

         .. oe:api::

            OESystem::OEIterBase<OEMedChem::OEMCSMolSimScore>* GetScores(const OEChem::OEMolBase& query,
                                                                         unsigned int bgn = 0,
                                                                         unsigned int end = 0,
                                                                         unsigned int scorecounts = OEMCSScoreType::Default,
                                                                         const OEMCSSimFuncBase& scorefunc = OEMCSTanimotoSim()) const

      .. oe:language:: python

         .. oe:api:: python

            GetScores(query: Union[OEGraphMol,OEMol,OEQMol], bgn: int = 0,
                      end: int = 0, scorecounts: int,
                      scorefn: OEMCSSimFuncBase = OEMCSTanimotoSim()) -> Iterable[OEMCSMolSimScore]

      Performs similarity calculations between a query molecule
      and the fragment cores stored in the
      :ref:`OEMCSFragDatabase <OEMedChem_OEMCSFragDatabase>` object.
      It returns an iterator over the calculated similarity
      scores (:ref:`OEMCSMolSimScore <OEMedChem_OEMCSMolSimScore>`).
      Each :ref:`OEMCSMolSimScore <OEMedChem_OEMCSMolSimScore>` object holds a similarity score,
      an index of database molecule and the fragment core in common between the hit and the query.

      **bgn**, **end**
         The ``bgn`` and ``end`` arguments define the segment of the
         database on which the similarity calculation will take place.
         If both of these parameters are omitted (or set to zero), then
         the similarity calculation is performed on the entire
         fragment database.

      **scorecounts**
         The value that defines the type of similarity scores (atom or bond) returned by the
         :oe:meth:`OEMedChem::OEMCSFragDatabase::GetScores` method.
         The default type is :oe:const:`OEMedChem::OEMCSScoreType::AtomCount`.

      **scorefunc**
         A class that computes the similarity score.  By default this is
         :ref:`OEMCSTanimotoSim <OEMedChem_OEMCSTanimotoSim>` but an implementation of
         :ref:`OEMCSTverskySim <OEMedChem_OEMCSTverskySim>`  is also provided.
         By providing a class derived from :ref:`OEMCSSimFuncBase <OEMedChem_OEMCSSimFuncBase>`
         user-defined similarity measures other than the provided versions can be generated.

      .. note::

         * By default, the :oe:meth:`OEMedChem::OEMCSFragDatabase::GetScores`
           method calculates :oe:const:`Tanimoto<OEGraphSim::OESimMeasure::Tanimoto>`
           atom similarity scores.

   .. oe:method:: GetSortedScores

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

         .. oe:api::

            OESystem::OEIterBase<OEMedChem::OEMCSMolSimScore>* GetSortedScores(const OEChem::OEMolBase& query,
                                                                               unsigned int limit = 0,
                                                                               unsigned int bgn = 0,
                                                                               unsigned int end = 0,
                                                                               bool descending = true,
                                                                               unsigned int scorecounts = OEMCSScoreType::Default,
                                                                               const OEMCSSimFuncBase& scorefunc = OEMCSTanimotoSim()) const

      .. oe:language:: python

         .. oe:api:: python

            GetSortedScores(query: Union[OEGraphMol,OEMol,OEQMol],
                            limit: int = 0, bgn: int = 0, end: int = 0,
                            descending: bool = True, scorecounts: int,
                            scorefn: OEMCSSimFuncBase = OEMCSTanimotoSim()) -> Iterable[OEMCSMolSimScore]

      Performs similarity calculations between a query molecule
      and the fragment cores stored in the
      :ref:`OEMCSFragDatabase <OEMedChem_OEMCSFragDatabase>` object.
      It returns an iterator over the calculated similarity
      scores (:ref:`OEMCSMolSimScore <OEMedChem_OEMCSMolSimScore>`) in sorted order.
      Each :ref:`OEMCSMolSimScore <OEMedChem_OEMCSMolSimScore>` object holds a similarity score
      an index of database molecule and the fragment core in common between the hit and query.

      **limit**
         The value that defines the number of similarity scores
         returned by the
         :oe:meth:`OEMedChem::OEMCSFragDatabase::GetSortedScores` method.
         If it is omitted (or set to zero) then all of the similarity
         scores are returned.

      **bgn**, **end**
         The ``bgn`` and ``end`` arguments define the segment of the
         database on which the similarity calculation will take place.
         If both of these parameters are omitted (or set to zero), then
         the similarity calculation is performed on the entire
         fragment database.

      **descending**
         A boolean value that indicates the direction of the sort values where
         ``true`` requests a descending sort and ``false`` requests ascending.

      **scorecounts**
         The value that defines the type of similarity scores (atom or bond) returned by the
         :oe:meth:`OEMedChem::OEMCSFragDatabase::GetSortedScores` method.
         The default type is :oe:const:`OEMedChem::OEMCSScoreType::AtomCount`.

      **scorefunc**
         A class that computes the similarity score.  By default this is
         :ref:`OEMCSTanimotoSim <OEMedChem_OEMCSTanimotoSim>` but an implementation of
         :ref:`OEMCSTverskySim <OEMedChem_OEMCSTverskySim>`  is also provided.
         By providing a class derived from :ref:`OEMCSSimFuncBase <OEMedChem_OEMCSSimFuncBase>`
         user-defined similarity measures other than the provided versions can be used.

      .. note::

         * By default, the :oe:meth:`OEMedChem::OEMCSFragDatabase::GetSortedScores`
           method calculates :oe:const:`Tanimoto<OEGraphSim::OESimMeasure::Tanimoto>`
           atom similarity scores and returns the highest scores first.

   .. oe:method:: IsIndexed

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

         .. oe:api::

            bool IsIndexed(unsigned int recordID) const

      .. oe:language:: python

         .. oe:api:: python

            IsIndexed(recID: int) -> bool

      Returns whether this record id is in the index.

   .. oe:method:: MoleculeToCores

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

         .. oe:api::

            OESystem::OEIterBase<const std::string>*MoleculeToCores(const OEChem::OEMolBase& mol,
                                                                    bool permuteFragments = true)

      .. oe:language:: python

         .. oe:api:: python

            MoleculeToCores(mol: Union[OEGraphMol,OEMol,OEQMol],
                            permuteFragments: bool = True) -> Iterable[str ]

      Given a molecule, return the fragmentation cores using either the
      provided fragmentation options, or using the fragmentation options from
      the :ref:`OEMCSFragDatabase <OEMedChem_OEMCSFragDatabase>` instance.  If the
      ``permuteFragments`` argument is ``true``, all combinations
      of the generated fragmentation cores are generated, otherwise a unique set
      of multi-fragment cores is returned representing all combinations
      of bond fragmentations between the min and max cut limits.

      Shown below are versions for two type of examples - one that uses an
      :ref:`OEMCSFragDatabase <OEMedChem_OEMCSFragDatabase>` instance so the database index options
      are used to control the fragmentation behavior and the other uses the free function
      and custom options.

      .. oe:source:: MoleculeToCoreExample.cpp
         :language: c++
         :frag:     SNIPPET-MOLECULETOCORE-DB-EXAMPLE

      .. oe:source:: MoleculeToCoreExample.py
         :language: python
         :frag:     SNIPPET-MOLECULETOCORE-DB-EXAMPLE


      .. oe:source:: MoleculeToCoreExample.java
         :language: java
         :frag:     SNIPPET-MOLECULETOCORE-DB-EXAMPLE

      .. oe:source:: MoleculeToCoreExample.cs
         :language: csharp
         :frag:     SNIPPET-MOLECULETOCORE-DB-EXAMPLE


      .. oe:source:: MoleculeToCoreExample.cpp
         :language: c++
         :frag:     SNIPPET-MOLECULETOCORE-OPTS-EXAMPLE

      .. oe:source:: MoleculeToCoreExample.py
         :language: python
         :frag:     SNIPPET-MOLECULETOCORE-OPTS-EXAMPLE

      .. oe:source:: MoleculeToCoreExample.java
         :language: java
         :frag:     SNIPPET-MOLECULETOCORE-OPTS-EXAMPLE

      .. oe:source:: MoleculeToCoreExample.cs
         :language: csharp
         :frag:     SNIPPET-MOLECULETOCORE-OPTS-EXAMPLE

   .. seealso::

      * :ref:`OEMCSFragDatabaseOptions <OEMedChem_OEMCSFragDatabaseOptions>` class
      * :oe:func:`OEMedChem::OEMoleculeToCores` function

   .. oe:method:: NumFragments

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

         .. oe:api::

            unsigned int NumFragments() const

      .. oe:language:: python

         .. oe:api:: python

            NumFragments() -> int

      Returns the total number of fragment cores present in the index.

   .. oe:method:: NumMols

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

         .. oe:api::

            unsigned int NumMols() const

      .. oe:language:: python

         .. oe:api:: python

            NumMols() -> int

      Returns the total number of indexed molecules present in the index.

   .. oe:method:: ProcessMol

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

         .. oe:api::

            int ProcessMol(OEChem::OEMolBase& inmol)

      .. oe:language:: python

         .. oe:api:: python

            ProcessMol(inmol: Union[OEGraphMol,OEMol,OEQMol]) -> int

      Since the fragmentation engine used internally to generate the index *modifies*
      the input structures (eg discarding all but the largest fragment of the input), this
      method is provided to force the application of the indexing modifications on the input structure.
      This is generally useful for depiction or reporting of the returned similarity results.
