.. oe:namespace:: OEChem


.. meta::
   :keywords: OEMolDatabase, MolDatabase


.. _OEChem_OEMolDatabase:

.. oe:class:: OEMolDatabase

   .. oe:api::

      class OEMolDatabase : public OESystem::OEBase

   This class provides an abstraction for fast read-only random access
   to any molecular file format **OEChem** supports reading. The
   :ref:`chapter_moldatabase` chapter provides a description of the
   fundamentals of using this class.

   When :oe:meth:`opened<OEChem::OEMolDatabase::Open>` or
   :oe:meth:`saved<OEChem::OEMolDatabase::Save>` to an :file:`.oeb`
   file, the generic data on the object itself will be preserved
   through the :ref:`OEHeader <OESystem_OEHeader>` record in the file. The
   following methods can be used to access the generic since they are
   inherited from :ref:`OEBase <OESystem_OEBase>`:

   ======================================================== ========================================================= =========================================================
   :oe:meth:`operator=<OESystem::OEBase::operator=>`        :oe:meth:`GetData<OESystem::OEBase::GetData>`             :oe:meth:`IsDataType<OESystem::OEBase::IsDataType>`
   :oe:meth:`operator+=<OESystem::OEBase::operator+=>`      :oe:meth:`GetDataIter<OESystem::OEBase::GetDataIter>`     :oe:meth:`SetBaseData<OESystem::OEBase::SetBaseData>`
   :oe:meth:`AddBaseData<OESystem::OEBase::AddBaseData>`    :oe:meth:`GetDataType<OESystem::OEBase::GetDataType>`     :oe:meth:`SetBoolData<OESystem::OEBase::SetBoolData>`
   :oe:meth:`AddData<OESystem::OEBase::AddData>`            :oe:meth:`GetDoubleData<OESystem::OEBase::GetDoubleData>` :oe:meth:`SetData<OESystem::OEBase::SetData>`
   :oe:meth:`Clear<OESystem::OEBase::Clear>`                :oe:meth:`GetFloatData<OESystem::OEBase::GetFloatData>`   :oe:meth:`SetDoubleData<OESystem::OEBase::SetDoubleData>`
   :oe:meth:`CreateCopy<OESystem::OEBase::CreateCopy>`      :oe:meth:`GetIntData<OESystem::OEBase::GetIntData>`       :oe:meth:`SetFloatData<OESystem::OEBase::SetFloatData>`
   :oe:meth:`DeleteData<OESystem::OEBase::DeleteData>`      :oe:meth:`GetStringData<OESystem::OEBase::GetStringData>` :oe:meth:`SetIntData<OESystem::OEBase::SetIntData>`
   :oe:meth:`GetBoolData<OESystem::OEBase::GetBoolData>`    :oe:meth:`HasData<OESystem::OEBase::HasData>`             :oe:meth:`SetStringData<OESystem::OEBase::SetStringData>`
   ======================================================== ========================================================= =========================================================

   .. oe:method:: Constructors

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

         .. oe:api::

            OEMolDatabase()
            OEMolDatabase(OEChem::oemolistream& ifs)
            OEMolDatabase(const std::string& filename)
            OEMolDatabase(OEPlatform::oeistream& istr, unsigned int format)
            OEMolDatabase(const std::string& filename, unsigned int format)
            OEMolDatabase(const std::string& filename, unsigned int format,
                          unsigned int flavor)
            OEMolDatabase(OEPlatform::oeistream& istr, unsigned int format,
                          unsigned int flavor)

      .. oe:language:: python

         .. oe:api:: python

            OEMolDatabase() -> OEMolDatabase
            OEMolDatabase(filename: str) -> OEMolDatabase
            OEMolDatabase(filename: str, format: int) -> OEMolDatabase
            OEMolDatabase(filename: str, format: int, flavor: int) -> OEMolDatabase
            OEMolDatabase(ifs: oemolistream) -> OEMolDatabase
            OEMolDatabase(istr: oeistream, format: int) -> OEMolDatabase
            OEMolDatabase(istr: oeistream, format: int, flavor: int) -> OEMolDatabase

      The default constructor will initialize the object to an empty
      state where most of the accessors methods will fail. It is
      expected that the user will later call
      :oe:meth:`OEChem::OEMolDatabase::Open` on the object.

      The other constructors are convenience methods for opening the
      database on the given ``filename`` or stream with the specified
      ``format`` and ``flavor``.

      The database requires file storage to store the actual molecule
      data. Therefore, if given a :ref:`oeistream <OEPlatform_oeistream>`, the
      stream's data will be copied to a temporary file. The temporary
      file will be automatically deleted by the destructor of this
      class.

      :ref:`oemolistream <OEChem_oemolistream>` may not need a temporary file if
      they were opened on an actual file.

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

      .. oe:api::

         OEMolDatabase & operator=(const OEMolDatabase &)

      Assignment operator.


   .. oe:method:: Clear

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

         .. oe:api::

            void Clear()

      .. oe:language:: python

         .. oe:api:: python

            Clear() -> None

      Removes all generic by calling through to
      :oe:meth:`OESystem::OEBase::Clear` as well as resetting the
      database back to an un-initialized state, the same state as the
      default constructor.

   .. oe:method:: CreateCopy

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

         .. oe:api::

            OESystem::OEBase* CreateCopy() const

      .. oe:language:: python

         .. oe:api:: python

            CreateCopy() -> OEBase

      Creates a copy of the database pointing to the same backing file
      store as the original. The copy is invalid if the original is
      destroyed.

      .. warning::

         It is not recommended to use this method. It is only
         implemented to adhere to the :ref:`OEBase <OESystem_OEBase>` API.

   .. oe:method:: Delete

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

         .. oe:api::

            bool Delete(unsigned int idx)
            bool Delete(const std::vector<unsigned int>& indices)
            bool Delete(const OESystem::OEUnaryPredicate<OEMolBase>& pred)
            bool Delete(const OESystem::OEUnaryPredicate<OEMCMolBase>& pred)

      .. oe:language:: python

         .. oe:api:: python

            Delete(idx: int) -> bool
            Delete(indices: OEUIntVector) -> bool
            Delete(pred: OEUnaryMolBasePred) -> bool
            Delete(pred: OEUnaryPredicate[OEMol]) -> bool

      Mark the given molecules as "deleted" in the database in
      constant time, ``O(1)``. Deleted molecules will not be written
      during a :oe:meth:`Save<OEChem::OEMolDatabase::Save>`
      operation. Deleted molecules will return ``false`` when accessed
      from the :oe:meth:`OEChem::OEMolDatabase::GetMolecule` method.

   .. oe:method:: GetDataType

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

         .. oe:api::

            const void* GetDataType() const

      .. oe:language:: python

         .. oe:api:: python

            GetDataType() -> void

      Return an opaque value representing the data type of this class.

   .. oe:method:: GetFlavor

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

         .. oe:api::

            unsigned int GetFlavor() const

      .. oe:language:: python

         .. oe:api:: python

            GetFlavor() -> int

      Returns ``0`` if uninitialized. Returns the flavor used to
      interpret the molecules in this database, pulled from the
      :oe:constns:`OEChem::OEIFlavor` namespace associated with the
      format returned from the
      :oe:meth:`OEChem::OEMolDatabase::GetFormat` method.

   .. oe:method:: GetFormat

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

         .. oe:api::

            unsigned int GetFormat() const

      .. oe:language:: python

         .. oe:api:: python

            GetFormat() -> int

      Returns the format used to interpret the molecules in the file
      this database was opened on. The value returned is a member of
      the :ref:`the OEFormat namespace <OEChem_OEFormat>`.

   .. oe:method:: GetIdx

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

         .. oe:api::

            unsigned int GetIdx(unsigned int row)

      .. oe:language:: python

         .. oe:api:: python

            GetIdx(row: int) -> int

      Returns the index for the nth ``row`` in the
      database. ``row`` should be less than
      :oe:meth:`OEChem::OEMolDatabase::NumMols` and the value returned
      will be less than
      :oe:meth:`OEChem::OEMolDatabase::GetMaxMolIdx`. By default, row
      numbers are the same as their index. Row numbers can be changed
      by deleting or re-ordering the database. If row numbers were
      altered before this call, this call is
      ``O(GetMaxMolIdx())``. After the first call to ``GetIdx``,
      subsequent calls are ``O(1)``, until another alteration is made
      to the database.

      This is the reverse operation from
      :oe:meth:`OEChem::OEMolDatabase::GetRow`.

   .. oe:method:: GetIdxs

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

         .. oe:api::

            OESystem::OEIterBase<unsigned int>* GetIdxs() const
            bool GetIdxs(std::vector<unsigned int>& indices) const

      .. oe:language:: python

         .. oe:api:: python

            GetIdxs() -> Iterable[int]
            GetIdxs(indices: OEUIntVector) -> bool

      Returns all the valid indices in the order that is currently
      considered the database order by this object.

   .. oe:method:: GetMaxMolIdx

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

         .. oe:api::

            unsigned int GetMaxMolIdx() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxMolIdx() -> int

      Returns one more than the maximum molecule index this database
      currently contains.

   .. oe:method:: GetMolecule

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

         .. oe:api::

            bool GetMolecule(OEMolBase& mol, unsigned int idx) const
            bool GetMolecule(OEMCMolBase& mol, unsigned int idx) const
            bool GetMolecule(oemolostream& ostr, unsigned int idx) const

      .. oe:language:: python

         .. oe:api:: python

            GetMolecule(mol: Union[OEGraphMol,OEQMol], idx: int) -> bool
            GetMolecule(mol: OEMol, idx: int) -> bool
            GetMolecule(ofs: oemolostream, idx: int) -> bool

      Read the molecule located at index ``idx`` into the molecule
      ``mol``. If the file format is a multi-conformer :file:`.oeb`
      file, only the first will be read if ``mol`` is an
      :ref:`OEMolBase <OEChem_OEMolBase>`. If there is a need for handling
      multi-conformer molecules, the :ref:`OEMCMolBase <OEChem_OEMCMolBase>`
      overload should be used instead.

      .. warning::

         The overload that takes an :ref:`oemolostream <OEChem_oemolostream>` is
         deprecated as of 2015.Jun and will be removed in a future
         version of **OEChem TK**, please use
         :oe:meth:`OEChem::OEMolDatabase::WriteMolecule` instead.

         The overload that takes an :ref:`oemolostream <OEChem_oemolostream>` will
         write bytes for the molecule record at index ``idx`` to the
         stream ``ostr``. No attempt will be made to interpret the data
         as a molecule and verify whether it is truly a parsable
         molecule. The molecule will be in whatever format the database
         was opened on.

   .. oe:method:: GetMoleculeString

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

         .. oe:api::

            std::string GetMoleculeString(unsigned int idx) const

      .. oe:language:: python

         .. oe:api:: python

            GetMoleculeString(idx: int) -> bytes

      Return the chunk of data from the molecule file that corresponds
      to the molecule record at index ``idx``.

      .. oe:language:: python

         In **Python** the :oe:meth:`OEChem::OEMolDatabase::GetMoleculeString`
         method returns ``bytes``.

   .. oe:language:: python

      .. oe:method:: GetOEGraphMols

         .. oe:api::

            GetOEGraphMols() -> <generator of OEGraphMol objects>

         Returns a generator over all the non-deleted molecules in the
         :ref:`OEMolDatabase <OEChem_OEMolDatabase>` in the current order. By
         default, the molecule database order is defined by the file,
         but can be altered by
         :oe:meth:`OEChem::OEMolDatabase::Order`. Each molecule will be
         an :ref:`OEGraphMol <OEChem_OEGraphMol>` object. If opened on a
         multi-conformer :file:`.oeb` file, only the first conformer
         will be returned for each molecule record.

         .. note::

            Unlike ``OEChem::oemolistream::GetOEGraphMols``, a new
            molecule object will be returned upon each iteration, reducing
            the need to create molecule copies when keeping the molecules
            around.


      .. oe:method:: GetOEMols

         .. oe:api::

            GetOEMols() -> <generator of OEMol objects>

         Returns a generator over all the non-deleted molecules in the
         :ref:`OEMolDatabase <OEChem_OEMolDatabase>` in the current order. By
         default, the molecule database order is defined by the file,
         but can be altered by
         :oe:meth:`OEChem::OEMolDatabase::Order`. Each molecule will be
         an :ref:`OEMol <OEChem_OEMol>` object.

         .. note::

            Unlike :oe:meth:`OEChem::oemolistream::GetOEMols`, a new
            molecule object will be returned upon each iteration, reducing
            the need to create molecule copies when keeping the molecules
            around.

   .. oe:method:: GetRow

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

         .. oe:api::

            unsigned int GetRow(unsigned int idx)

      .. oe:language:: python

         .. oe:api:: python

            GetRow(idx: int) -> int

      Return where the database considers the molecule record ``idx``
      to reside in the global order of the database. ``idx`` should be
      less than :oe:meth:`OEChem::OEMolDatabase::GetMaxMolIdx` and the
      value returned will be less than
      :oe:meth:`OEChem::OEMolDatabase::NumMols`. By default, row
      numbers are the same as their index. Row numbers can be changed
      by deleting or re-ordering the database. If row numbers were
      altered before this call, this call is
      ``O(GetMaxMolIdx())``. After the first call to ``GetIdx``,
      subsequent calls are ``O(1)``, until another alteration is made
      to the database.

      This is the reverse operation from
      :oe:meth:`OEChem::OEMolDatabase::GetIdx`.

   .. oe:method:: GetTitle

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

         .. oe:api::

            std::string GetTitle(unsigned int idx) const

      .. oe:language:: python

         .. oe:api:: python

            GetTitle(idx: int) -> str

      Returns the title for the molecule at index ``idx`` in the
      database. This is the same value that is returned by
      :oe:meth:`OEChem::OEMolBase::GetTitle`, but without the need to
      parse the whole molecule record into an :ref:`OEMolBase <OEChem_OEMolBase>`.

   .. oe:method:: GetTitles

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

         .. oe:api::

            OESystem::OEIterBase<const std::string>* GetTitles() const

      .. oe:language:: python

         .. oe:api:: python

            GetTitles() -> Iterable[str]

      Returns all the titles for the database as would be returned by
      :oe:meth:`OEChem::OEMolDatabase::GetTitle` in database index
      order.

   .. oe:method:: IsDataType

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

         .. oe:api::

            bool IsDataType(const void *) const

      .. oe:language:: python

         .. oe:api:: python

            IsDataType(arg2: void) -> bool

      Returns whether the opaque data passed represents the same data
      type as this class.

   .. oe:method:: IsDeleted

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

         .. oe:api::

            bool IsDeleted(unsigned int idx) const

      .. oe:language:: python

         .. oe:api:: python

            IsDeleted(idx: int) -> bool

      Returns whether the database index ``idx`` has already been
      deleted by a previous call to
      :oe:meth:`OEChem::OEMolDatabase::Delete`.

   .. oe:method:: NumMols

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

         .. oe:api::

            unsigned int NumMols() const

      .. oe:language:: python

         .. oe:api:: python

            NumMols() -> int

      Returns the number of molecule **records** in the database.

      .. note::

         The number of valid molecules in the database might be less than
         the number returned by :oe:meth:`OEChem::OEMolDatabase::NumMols`.
         The reason is that the molecule file is not fully parsed when invoking the
         :oe:meth:`OEChem::OEMolDatabase::NumMols` function.

   .. oe:method:: Open

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

         .. oe:api::

            bool Open(OEChem::oemolistream& ifs)
            bool Open(const std::string& filename)
            bool Open(const std::string& filename, unsigned int format)
            bool Open(OEPlatform::oeistream& istr, unsigned int format)
            bool Open(const std::string& filename, unsigned int format,
                      unsigned int flavor)
            bool Open(OEPlatform::oeistream& istr, unsigned int format,
                      unsigned int flavor)

      .. oe:language:: python

         .. oe:api:: python

            Open(ifs: oemolistream) -> bool
            Open(filename: str) -> bool
            Open(filename: str, format: int) -> bool
            Open(istr: oeistream, format: int) -> bool
            Open(filename: str, format: int, flavor: int) -> bool
            Open(istr: oeistream, format: int, flavor: int) -> bool

      Initializes the database to the file name given.  The database
      requires file storage to store the actual molecule
      data. Therefore, if given a :ref:`oeistream <OEPlatform_oeistream>`, the
      stream's data will be copied to a temporary file. The temporary
      file will be automatically deleted by the destructor of this
      class.

      :ref:`oemolistream <OEChem_oemolistream>` may not need a temporary file if
      they were opened on an actual file.

      This method is expensive, it may require scanning the whole file
      to determine the proper file offsets to the individual molecule
      records. To speed up the ``Open`` operation, :file:`.idx` files
      can be generated by :oe:func:`OEChem::OECreateMolDatabaseIdx` or
      :oe:meth:`OEChem::OEMolDatabase::Save`. If ``Open`` detects the
      presence of an :file:`.idx` file parallel to the database file,
      the file offsets will be read directly from this file instead,
      possibly saving the need to stream the entire database from disk.

      .. seealso::

         :ref:`section_index_files` section

   .. oe:method:: Order

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

         .. oe:api::

            bool Order(const std::vector<unsigned int>& indices)

      .. oe:language:: python

         .. oe:api:: python

            Order(indices: OEUIntVector) -> bool

      Re-orders the molecules in the database according to the order
      of the indices specified by ``indices``. Subsequent calls to
      :oe:meth:`OEChem::OEMolDatabase::GetIdx` or
      :oe:meth:`OEChem::OEMolDatabase::GetRow` will return this
      order. Subsequent calls to :oe:meth:`OEChem::OEMolDatabase::Save`
      will output the database in this order.

   .. oe:method:: Save

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

         .. oe:api::

            bool Save(const std::string& filename, unsigned int format) const
            bool Save(OEPlatform::oeostream& ostr, unsigned int format) const
            bool Save(const std::string& filename, unsigned int format,
                      unsigned int flavor) const
            bool Save(OEPlatform::oeostream& ostr, unsigned int format,
                      unsigned int flavor) const
            bool Save(OEChem::oemolostream& ofs,
                      const OEMolDatabaseSaveOptions& opts = OEMolDatabaseSaveOptions()) const
            bool Save(const std::string& filename,
                      const OEMolDatabaseSaveOptions& opts = OEMolDatabaseSaveOptions()) const

      .. oe:language:: python

         .. oe:api:: python

            Save(filename: str, format: int) -> bool
            Save(ostr: oeostream, format: int) -> bool
            Save(filename: str, format: int, flavor: int) -> bool
            Save(ostr: oeostream, format: int, flavor: int) -> bool
            Save(ofs: oemolostream,
                 opts: OEMolDatabaseSaveOptions = OEMolDatabaseSaveOptions()) -> bool
            Save(filename: str,
                 opts: OEMolDatabaseSaveOptions = OEMolDatabaseSaveOptions()) -> bool

      Save the database to the file specified by ``filename`` in the
      ``format`` and ``flavor`` specified. The data may be written
      directly to the stream ``ostr`` as well.

      This method is heavily optimized for the case whenever the
      output file format is the same as the input file format used to
      initialize the database. If the same file format is used, the
      molecule record's bytes will be streamed directly, without an
      intermediate :ref:`OEMolBase <OEChem_OEMolBase>` to do the conversion.

      .. seealso::

         * :ref:`OEMolDatabaseSaveOptions <OEChem_OEMolDatabaseSaveOptions>` class for more
           options when saving a database to a file.
         * :oe:meth:`OEChem::OEGetMolDatabaseIdxFileName` to retrieve
           the default filename used for the index file generated.

      .. warning::

         Since :ref:`OEMolDatabase <OEChem_OEMolDatabase>` depends on backing file
         storage. Therefore, if the contents of the file change after
         :oe:meth:`OEChem::OEMolDatabase::Open` completes, the
         behavior is undefined. It is very likely the file data itself
         will be corrupted. For this reason,
         :oe:meth:`OEChem::OEMolDatabase::Save` will fail to write to
         the same file name used to open the database object. This
         protects against the common case, but does not protect
         against the general case of file changing during access.

   .. oe:method:: WriteMolecule

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

         .. oe:api::

            bool WriteMolecule(oemolostream& ostr, unsigned int idx) const

      .. oe:language:: python

         .. oe:api:: python

            WriteMolecule(ofs: oemolostream, idx: int) -> bool

      Write bytes for the molecule record at index ``idx`` to the
      stream ``ostr``. No attempt will be made to interpret the data
      as a molecule and verify whether it is truly a parsable
      molecule. The molecule will be in whatever format the database
      was opened on. Returns ``false`` if the
      :ref:`oemolostream <OEChem_oemolostream>` is not the exact same file format
      as the :ref:`OEMolDatabase <OEChem_OEMolDatabase>` or any input/output
      operation fails.
