.. oe:namespace:: OEFastROCS

.. sizeof(OEShapeDatabaseScore) = 48 bytes
.. sizeof(OEBestOverlayScore) = 96 bytes
.. probably not worth the difference... 


.. meta::
   :keywords: OEShapeDatabaseScore, ShapeDatabaseScore


.. _OEFastROCS_OEShapeDatabaseScore:

.. oe:class:: OEShapeDatabaseScore

   .. oe:api::

      class OEShapeDatabaseScore

   This object is used to represent the result of a **FastROCS TK**
   calculation returned by the
   :oe:meth:`OEFastROCS::OEShapeDatabase::GetSortedScores` and
   :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores` methods.

   It encapsulates the following information:

   - Score information:

     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetColorTanimoto`
     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetShapeTanimoto`
     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetTanimotoCombo`
     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetColorTversky`
     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetShapeTversky`
     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetTverskyCombo`
     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetColorScore`
     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetShapeScore`
     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetScore`

   - Overlay recreation:

     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetQuat`
     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetRotMatrix`
     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetTranslation`
     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::Transform`

   - Molecule retrieval:
     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetMolIdx`
     * :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetConfIdx`

   .. _fastrocs_molecule_transforms_warning:
       
   .. warning:: 

      The molecular transforms returned by
      :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetQuat`,
      :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetRotMatrix`, and
      :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetTranslation`
      assume the conformer has already been aligned by
      :oe:func:`OEFastROCS::OESetCoordsToInertialFrame`.

      While it was definitely in-elegant to require calling
      :oe:func:`OEFastROCS::OESetCoordsToInertialFrame` in order to
      reproduce overlays, this allows
      :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>` to not store 28 bytes of
      memory per conformer, a significant space savings, especially
      when conformers are stored in rotor-compressed form.

      Overlays are usually only required for a small number of
      conformations, so re-calculating this for only the "hits" is a
      small price to pay for potentially saving gigabytes of memory on
      an already memory constrained problem. 

      Users should prefer to use the
      :oe:meth:`OEFastROCS::OEShapeDatabaseScore::Transform` directly
      to avoid having to deal with this subtlety, it will
      automatically do all the transformations necessary to generate
      overlays.

     
   .. oe:method:: Constructors

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

         .. oe:api::

            OEShapeDatabaseScore(size_t molIdx, unsigned int confIdx,
                                 float shapeScore, float colorScore,
                                 const float* quat,
                                 unsigned int csimFunc = OEShapeSimFuncType::Default,
                                 unsigned int orient = OEFastROCSOrientation::Default)
            OEShapeDatabaseScore(size_t molIdx, unsigned int confIdx,
                                 float shapeScore, float colorScore,
                                 const double* quat,
                                 unsigned int csimFunc = OEShapeSimFuncType::Default,
                                 unsigned int orient = OEFastROCSOrientation::Default)

      .. oe:language:: python

         .. oe:api:: python

            OEShapeDatabaseScore(molIdx: int, confIdx: int, shapeScore: float,
                                 colorScore: float, quat: OEFloatArray,
                                 csimFunc: int, orient: int) -> OEShapeDatabaseScore
            OEShapeDatabaseScore(molIdx: int, confIdx: int, shapeScore: float,
                                 colorScore: float, quat: OEDoubleArray,
                                 csimFunc: int, orient: int) -> OEShapeDatabaseScore

      Constructs a new score object with the specified data. Typically
      only used by the internals of **FastROCS TK** in order to
      populate the hitlist.

      .. warning::
     
         The constructor has changed in order to support 
         :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs`. The constant 
         :oe:constns:`OEFastROCS::OEFastROCSOrientation::Default`, drawn from the 
         :oe:constns:`OEFastROCS::OEFastROCSOrientation` namespace, has been added to the argument
         list. The default is :oe:constns:`OEFastROCS::OEFastROCSOrientation::Inertial` and the 
         last argument should be left blank unless it is intended to use 
         :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs` starts on the database being loaded,
         in which case ``unsigned int orient=OEFastROCSOrientation::AsIs`` should be passed to the
         constructor. 

      .. warning:: 

         The constructor has changed in order to support Tversky scoring. The constant
         "OEShapeSimFuncType::Default", drawn from the :oe:constns:`OEFastROCS::OEShapeSimFuncType` 
         namespace, has been added to the argument list. The default is "Tanimoto". "Tversky"
         scoring is chosen by passing :oe:constns:`OEFastROCS::OEShapeSimFuncType::Tversky` and
         setting :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetSimFunc` to "Tversky". 

   .. oe:method:: GetColorScore

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

         .. oe:api::

            float GetColorScore() const

      .. oe:language:: python

         .. oe:api:: python

            GetColorScore() -> float

      Returns the “color” component of the score used for ranking molecules by **FastROCS TK**. 
      See the :ref:`molecular_shape_section` section of the **ShapeTK** theory documentation 
      for a description of the calculation. This function should be used in conjunction with 
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetSimFunc` in order to determine which 
      similarity function ("Tanimoto" or "Tversky") was used to calculate the scores. This function
      will return ``0.0`` if the search was requested to be "shape only", i.e., only
      :oe:const:`OEFastROCS::OEShapeDatabaseType::Shape` was specified.
 

   .. oe:method:: GetColorTanimoto

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

         .. oe:api::

            float GetColorTanimoto() const

      .. oe:language:: python

         .. oe:api:: python

            GetColorTanimoto() -> float

      Returns the "color" component of the Tanimoto score used for ranking
      molecules by **FastROCS TK**. See the
      :ref:`shapetk_color_features` section in the **Shape TK** theory
      documentation for a description of what the "color" term is. This function
      will return ``0.0`` if the search was requested to be "shape
      only", i.e., only
      :oe:const:`OEFastROCS::OEShapeDatabaseType::Shape` was
      specified.

      .. note:: 

         A color tanimoto of ``0.0`` is also possible if either the
         query or database molecule does not contain any color
         atoms. Even more surprising is that this value can sometimes
         exceed ``1.0``, which appears to violate the definition of
         "tanimoto". This is due to the first-order-gaussian
         approximation used, i.e, intersection volumes are not
         actually subtracted out since they have little effect on
         virtual screening performance and would be significantly more
         costly to calculate. Typically, these cases are limited to
         complex cage systems like cubane that have many overlapping
         "ring" color atoms that heavily overlap. The use of the
         "ring" color term can be customized by using a custom color
         field specified through the :oe:meth:`OEShapeDatabase
         constructor<OEFastROCS::OEShapeDatabase::Constructors>`.

   .. oe:method:: GetColorTversky

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

         .. oe:api::

            float GetColorTversky() const

      .. oe:language:: python

         .. oe:api:: python

            GetColorTversky() -> float

      Returns the "color" component of the Tversky score used for ranking
      molecules by **FastROCS TK**. See the
      :ref:`shapetk_color_features` section in the **Shape TK** theory
      documentation for a description of what the "color" term is. This function
      will return ``0.0`` if the search was requested to be "shape
      only", i.e., only
      :oe:const:`OEFastROCS::OEShapeDatabaseType::Shape` was
      specified. If "Tversky" scoring was not set using
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetSimFunc` prior to the search
      this function will return with an error.
 
   .. oe:method:: GetConfIdx

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

         .. oe:api::

            unsigned int GetConfIdx() const

      .. oe:language:: python

         .. oe:api:: python

            GetConfIdx() -> int

      Returns the conformer's index of the matching conformer for this
      particular score. This index will match the index returned by
      the :oe:meth:`OEChem::OEConfBase::GetIdx` method. This allows
      retrieving the conformer from the
      :oe:meth:`OEChem::OEMCMolBase::GetConf` method using the
      :oe:cls:`OEHasConfIdx<OEChem::OEHasIdx>` predicate like the
      following:

      .. code:: python

         conf = mol.GetConf(OEHasIdx(score.GetConfIdx()))

   .. oe:method:: GetMolIdx

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

         .. oe:api::

            size_t GetMolIdx() const

      .. oe:language:: python

         .. oe:api:: python

            GetMolIdx() -> int

      Returns the molecule index that returned this particular
      "score". This index maps to the indices used by
      :ref:`OEMolDatabase <OEChem_OEMolDatabase>` to retrieve molecules assuming
      the :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>` was initialized with
      the :oe:meth:`OEFastROCS::OEShapeDatabase::Open` method. This
      allows **FastROCS TK** to rely on disk-based storage through
      :ref:`OEMolDatabase <OEChem_OEMolDatabase>` to retrieve overlays and provide
      connection tables, a significant memory space savings. However,
      this does come at the added latency and computational expense of
      the :oe:meth:`OEChem::OEMolDatabase::GetMolecule` method. 

      To allow for use cases other than virtual screening where only a
      small number of "hits" need to be sent on for further
      processing. This index may map to the index returned by the
      :oe:meth:`OEFastROCS::OEShapeDatabase::AddMol` method. It is up
      to the user to decide how to store the
      :ref:`OEMCMolBase <OEChem_OEMCMolBase>` for later access. Previously
      versions of **FastROCS TK** used
      :oe:const:`OEChem::OEMCMolType::OEDBMCMol` molecules for this
      purpose.

   .. oe:method:: GetQuat

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

         .. oe:api::

            const float* GetQuat() const

      .. oe:language:: python

         .. oe:api:: python

            GetQuat() -> OEFloatArray

      .. warning:: 
      
         It will be easier to use the
         :oe:meth:`OEFastROCS::OEShapeDatabaseScore::Transform` method
         than to use figure out how to use the data from this
         function.

      Returns a pointer to a 7-element quaternion that can be used to
      overlay the database conformer represented by this score with
      the query conformation. This 7-element quaternion contains both
      the rotation and translational components: the first 4 elements
      being the quaternion rotation; the second 3 elements are the
      translational component.

      .. warning::

         Read :ref:`FastROCS transforms
         warning<fastrocs_molecule_transforms_warning>` above about
         performing overlays with these more advanced methods. 

   .. oe:method:: GetRotMatrix

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

         .. oe:api::

            bool GetRotMatrix(float* rmat) const

      .. oe:language:: python

         .. oe:api:: python

            GetRotMatrix(rmat: OEFloatArray) -> bool

      .. warning:: 
      
         It will be easier to use the
         :oe:meth:`OEFastROCS::OEShapeDatabaseScore::Transform` method
         than to use figure out how to use the data from this
         function.

      Fills in the 9-element rotation matrix ``rmat`` with the
      rotation component needed to overlay the database conformer
      represented by this score with the query conformation. Returns
      ``false`` if the rotation matrix is ill-defined, i.e., the
      conversion from the underlying quaternion failed. 

      .. warning::

         Read :ref:`FastROCS transforms
         warning<fastrocs_molecule_transforms_warning>` above about
         performing overlays with these more advanced methods. 

   .. oe:method:: GetScore

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

         .. oe:api::

            float GetScore() const

      .. oe:language:: python

         .. oe:api:: python

            GetScore() -> float

      Returns the sum of the "shape" and "color" scores. This function
      should be used in conjunction with :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetSimFunc`
      in order to determine which similarity function ("Tanimoto" or "Tversky") was used
      to calculate the scores.

   .. oe:method:: GetShapeScore

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

         .. oe:api::

            float GetShapeScore() const

      .. oe:language:: python

         .. oe:api:: python

            GetShapeScore() -> float

      Returns the “shape” component of the score used for ranking molecules by **FastROCS TK**. 
      See the :ref:`molecular_shape_section` section of the **Shape TK** theory documentation 
      for a description of the calculation. This function should be used in conjunction with 
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetSimFunc` in order to determine which 
      similarity function ("Tanimoto" or "Tversky") was used to calculate the scores.

      Currently, it is not possible to request a "color only"
      calculation from **FastROCS TK**. Therefore, this function should
      always be greater than ``0.0``. A value of ``0.0`` would be a
      molecule with no volume, which is impossible. 

   .. oe:method:: GetShapeTanimoto

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

         .. oe:api::

            float GetShapeTanimoto() const

      .. oe:language:: python

         .. oe:api:: python

            GetShapeTanimoto() -> float

      Returns the "shape" component of the tanimoto score used for ranking
      molecules by **FastROCS TK**. See the
      :ref:`molecular_shape_section` section in the **Shape TK**
      theory documentation for a description of how this is calculated. 

      Currently, it is not possible to request a "color only"
      calculation from **FastROCS TK**. Therefore, this function should
      always be greater than ``0.0``. A value of ``0.0`` would be a
      molecule with no volume, which is impossible. 

      .. note:: 

         It is possible, though rare, to see values slightly greater
         than ``1.0`` in the 2nd decimal place. This is due to the
         approximation **FastROCS TK** uses for performance and can be
         disregarded, especially since they usually only occur
         whenever a molecule is matched against itself.
      

   .. oe:method:: GetShapeTversky

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

         .. oe:api::

            float GetShapeTversky() const

      .. oe:language:: python

         .. oe:api:: python

            GetShapeTversky() -> float

      Returns the "shape" component of the tversky score used for ranking
      molecules by **FastROCS TK**. See the
      :ref:`molecular_shape_section` section in the **Shape TK**
      theory documentation for a description of how this is calculated. 
      If "Tversky" scoring was not set using
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetSimFunc` prior to the search
      this function will return with an error.

      As with the "Tanimoto" scoring option, it is not currently 
      possible to request a “color only” calculation from **FastROCS TK**. 
      Therefore, this function should always be greater than ``0.0``. 
      If this is not the case an error has occurred.

      .. note:: 

         It is possible, though rare, to see values slightly greater
         than ``1.0`` in the 2nd decimal place. This is due to the
         approximation **FastROCS TK** uses for performance and can be
         disregarded, especially since they usually only occur
         whenever a molecule is matched against itself.
      
   .. oe:method:: GetSimFunc

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

         .. oe:api::

            unsigned int GetSimFunc() const

      .. oe:language:: python

         .. oe:api:: python

            GetSimFunc() -> int

      Returns a constant from the :oe:constns:`OEFastROCS::OEShapeSimFuncType`
      namespace indicating what type of similarity function, "Tanimoto" or "Tversky", 
      is being used for scoring.

   .. oe:method:: GetTanimotoCombo

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

         .. oe:api::

            float GetTanimotoCombo() const

      .. oe:language:: python

         .. oe:api:: python

            GetTanimotoCombo() -> float

      Returns the sum of the "color" and "shape" tanimotos. 

   .. oe:method:: GetTranslation

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

         .. oe:api::

            bool GetTranslation(float* trans) const

      .. oe:language:: python

         .. oe:api:: python

            GetTranslation(trans: OEFloatArray) -> bool

      .. warning:: 
      
         It will be easier to use the
         :oe:meth:`OEFastROCS::OEShapeDatabaseScore::Transform` method
         than to use figure out how to use the data from this
         function.

      Fills in the 3-element vector ``trans`` with the translation
      component needed to overlay the database conformer represented
      by this score with the query conformation. Returns ``false`` if
      the translation is ill-defined, i.e., something went horribly
      wrong.

      .. warning::

         Read :ref:`FastROCS transforms
         warning<fastrocs_molecule_transforms_warning>` above about
         performing overlays with these more advanced methods. 

   .. oe:method:: ExtractTransform

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

         .. oe:api::

            bool ExtractTransform(OETrans& transform, OEChem::OEMolBase& mol) const

      .. oe:language:: python

         .. oe:api:: python

            ExtractTransform(transform: OETrans,
                             dbmol: Union[OEGraphMol,OEMol,OEQMol]) -> bool

      Fills in the :ref:`OETrans <OEChem_OETrans>` object with the translation and rotation
      matrix necessary to transform mol onto the query. Note that
      :oe:meth:`OEFastROCS::OEShapeDatabaseScore::Transform` is the preferred method for
      visualizing overlays. This method is available for the case in which you need to know
      exactly what transform was performed. For example, when you want to use the same transform
      on another molecule.


   .. oe:method:: GetTverskyCombo

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

         .. oe:api::

            float GetTverskyCombo() const

      .. oe:language:: python

         .. oe:api:: python

            GetTverskyCombo() -> float

      Returns the sum of the "color" and "shape" Tversky scores. If "Tversky" scoring 
      was not set using :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetSimFunc` prior to the search
      this function will return with an error.

   .. oe:method:: Transform

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

         .. oe:api::

            bool Transform(OEChem::OEMolBase& mol) const

      .. oe:language:: python

         .. oe:api:: python

            Transform(mol: Union[OEGraphMol,OEMol,OEQMol]) -> bool

      Overlays the conformer represented by ``mol`` with the query
      conformation passed as the query to
      :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>`. This overlay will be the
      orientation that was used to calculate the scores returned by
      the rest of this class. 

      .. seealso:: 

         This is the preferred method for generating overlays with
         **FastROCS TK**. There is a more complete description of the
         process and its subtleties above in the :ref:`FastROCS transforms
         warning<fastrocs_molecule_transforms_warning>`.
