.. oe:namespace:: OEDocking


.. meta::
   :keywords: OEScore


.. _OEDocking_OEScore:

.. oe:class:: OEScore

   .. oe:api::

      class OEScore

   :ref:`OEScore <OEDocking_OEScore>` is a class for scoring and optimizing
   poses within the active site.  Use of this class is as follows:

   #. Initialize the active site by passing either a receptor (see 
      :ref:`chapter_receptor` chapter) or a protein and box to the 
      :oe:meth:`OEDocking::OEScore::Initialize` method.

   #. Score or optimize the molecules using:

      * :oe:meth:`OEDocking::OEScore::ScoreLigand`
      * :oe:meth:`OEDocking::OEScore::ScoreAtom`
      * :oe:meth:`OEDocking::OEScore::ScoreLigandComponent`
      * :oe:meth:`OEDocking::OEScore::ScoreAtomComponent`
      * :oe:meth:`OEDocking::OEScore::SystematicSolidBodyOptimize`
      * :oe:meth:`OEDocking::OEScore::AnnotatePose`

   .. oe:method:: Constructor

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

         .. oe:api::

            OEScore(const unsigned int scoring = OEScoreType::Default)

      .. oe:language:: python

         .. oe:api:: python

            OEScore(scoring: int) -> OEScore
            OEScore(arg2: OEScore) -> OEScore

      Constructs :ref:`OEScore <OEDocking_OEScore>` to use the specified *scoring*
      function from the :oe:constns:`OEDocking::OEScoreType` namespace.

.. _OEDocking_OEScore_IsInitialized:

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

      .. oe:api::

         OEScore & operator=(const OEScore &)

      Assignment operator.


   .. oe:method:: IsInitialized

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

         .. oe:api::

            bool IsInitialized() const

      .. oe:language:: python

         .. oe:api:: python

            IsInitialized() -> bool

      Returns true if this object has been successfully initialized
      and is ready to score poses.


   .. _OEDocking_OEScore_Initialize:



   .. oe:method:: Initialize

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

         .. oe:api::

            bool Initialize(const OEBio::OEDesignUnit& du)
            bool Initialize(const OEChem::OEMolBase& receptor)
            bool Initialize(const OEChem::OEMolBase& pro,
                            const OEMath::OEBox& box)

      .. oe:language:: python

         .. oe:api:: python

            Initialize(du: OEDesignUnit) -> bool
            Initialize(receptor: Union[OEGraphMol,OEMol,OEQMol]) -> bool
            Initialize(pro: Union[OEGraphMol,OEMol,OEQMol], box: OEBox) -> bool

      Sets up this object to score poses within an active site.  This function returns true if 
      initialization was successful. This object does not depend upon receptor once this call is 
      completed (*i.e.* receptor can be destroyed after calling this method).  The first overload 
      expects a design unit that contains a receptor. The second overload works on a 
      variation of molecule that contains receptor data.  The last overload works with a protein 
      and box enclosing the active site. Method returns ``true`` if setup was successful.


   .. _OEDocking_OEScore_GetName:



   .. oe:method:: GetName

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

         .. oe:api::

            std::string GetName() const

      .. oe:language:: python

         .. oe:api:: python

            GetName() -> str

      Returns the name of the scoring function.


   .. _OEDocking_OEScore_GetComponentNames:



   .. oe:method:: GetComponentNames

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

         .. oe:api::

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

      .. oe:language:: python

         .. oe:api:: python

            GetComponentNames() -> Iterable[str]

      Returns the name of the scoring function components.


   .. _OEDocking_OEScore_GetHighScoresAreBetter:



   .. oe:method:: GetHighScoresAreBetter

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

         .. oe:api::

            bool GetHighScoresAreBetter() const

      .. oe:language:: python

         .. oe:api:: python

            GetHighScoresAreBetter() -> bool

      Returns true if higher scores indicate a better result.

      Returns false if lower scores indicate a better result.



   .. _OEDocking_OEScore_ScoreLigand:




   .. oe:method:: ScoreLigand

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

         .. oe:api::

            float ScoreLigand(const OEChem::OEMolBase& pose)

      .. oe:language:: python

         .. oe:api:: python

            ScoreLigand(lig: Union[OEGraphMol,OEMol,OEQMol]) -> float

      Scores a pose within the active site.

         *pose*
            Structure of a pose within the active site

      If an error occurs this function will return FLT_MAX if
      :oe:meth:`OEDocking::OEScore::GetHighScoresAreBetter` returns false
      or -FLT_MAX otherwise.


   .. _OEDocking_OEScore_ScoreAtom:



   .. oe:method:: ScoreAtom

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

         .. oe:api::

            float ScoreAtom(const OEChem::OEAtomBase* atom,
            const OEChem::OEMolBase& lig)

      .. oe:language:: python

         .. oe:api:: python

            ScoreAtom(atom: OEAtomBase, lig: Union[OEGraphMol,OEMol,OEQMol]) -> float

      Returns the score of an atom of a given pose within the active site.

         *atom*
            Atom of *pose* to score.

         *pose*
            Structure of a pose within the active site

      If an error occurs this function will return FLT_MAX if
      :oe:meth:`OEDocking::OEScore::GetHighScoresAreBetter` returns false
      or -FLT_MAX otherwise.


   .. _OEDocking_OEScore_ScoreLigandComponent:



   .. oe:method:: ScoreLigandComponent

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

         .. oe:api::

            float ScoreLigandComponent(const OEChem::OEMolBase& pose,
                                       std::string compName)

      .. oe:language:: python

         .. oe:api:: python

            ScoreLigandComponent(lig: Union[OEGraphMol,OEMol,OEQMol],
                                 compName: str) -> float

      Returns the given component's contribution to the total score.

         *pose*
            Structure of a pose within the active site

         *compName*
            Name of the score component to report.  Name must be one
            returned by
            :oe:meth:`OEDocking::OEScore::GetComponentNames`.

      If an error occurs this function will return FLT_MAX if
      :oe:meth:`OEDocking::OEScore::GetHighScoresAreBetter` returns false
      or -FLT_MAX otherwise.


   .. _OEDocking_OEScore_ScoreAtomComponent:



   .. oe:method:: ScoreAtomComponent

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

         .. oe:api::

            float ScoreAtomComponent(const OEChem::OEAtomBase* atom,
            const OEChem::OEMolBase& lig, std::string compName)

      .. oe:language:: python

         .. oe:api:: python

            ScoreAtomComponent(atom: OEAtomBase,
                               lig: Union[OEGraphMol,OEMol,OEQMol],
                               compName: str) -> float

      Returns the given components contribution to the score of a given atom score.

         *atom*
           Atom of *pose* to score.

         *pose*
           Structure of a pose within the active site

         *compName*
            Name of the score component to report.  Name must be one
            returned by
            :oe:meth:`OEDocking::OEScore::GetComponentNames`.

      If an error occurs this function will return FLT_MAX if
      :oe:meth:`OEDocking::OEScore::GetHighScoresAreBetter` returns false
      or -FLT_MAX otherwise.


   .. _OEDocking_OEScore_SystematicSolidBodyOptimize:



   .. oe:method:: SystematicSolidBodyOptimize

      Performs a solid body optimization on the *pose* or *poses* passed.  Three
      rotational and three translational degrees of freedom are explored, the
      pose (and protein) are held rigid.  A plus and minus rotational step is
      taken for each rotational and translational degree of freedom
      (for a total of 3^6 or 729 positions tested for each pose).

      Both overloads return true if no error occurred.

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

         .. oe:api::

            bool SystematicSolidBodyOptimize(OEChem::OEMCMolBase& poses,
                                             unsigned int searchResolution = OESearchResolution::Default)

      .. oe:language:: python

         .. oe:api:: python

            SystematicSolidBodyOptimize(mol: OEMol, searchRes: int) -> bool

      This overload of 
      :oe:meth:`OEDocking::OEScore::SystematicSolidBodyOptimize`
      optimizes all poses of an :ref:`OEMCMolBase <OEChem_OEMCMolBase>`.
         
         *poses*
            An :ref:`OEMCMolBase <OEChem_OEMCMolBase>` with conformers that are
            poses within the active site to be optimized.  

         *searchResolution*
            Search resolution of the optimization (see 
            :oe:constns:`OEDocking::OESearchResolution` constant namespace).

      The optimized poses are returned in *poses*.  This poses retain their
      original ordering and are not ordered by the new optimized score.  

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

         .. oe:api::

            bool SystematicSolidBodyOptimize(OEChem::OEMolBase& pose,
                                             unsigned int searchResolution = OESearchResolution::Default)

      .. oe:language:: python

         .. oe:api:: python

            SystematicSolidBodyOptimize(mol: Union[OEGraphMol,OEQMol],
                                        searchRes: int) -> bool

      This overload of 
      :oe:meth:`OEDocking::OEScore::SystematicSolidBodyOptimize`
      optimizes a single pose.
         
         *pose*
            A pose within the active site to be optimized. 

         *searchResolution*
            Search resolution of the optimization (see 
            :oe:constns:`OEDocking::OESearchResolution` constant namespace).


   .. _OEDocking_OEScore_AnnotatePose:



   .. oe:method:: AnnotatePose

      Adds **VIDA** scoring annotation to the *pose* or *poses* passed.

      The annotated poses must be written out in either *oeb* or *oeb.gz* format
      and are only viewable in **VIDA**.

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

         .. oe:api::

            bool AnnotatePose(OEChem::OEMolBase& pose)

      .. oe:language:: python

         .. oe:api:: python

            AnnotatePose(lig: Union[OEGraphMol,OEQMol]) -> bool

      This overload of :oe:meth:`OEDocking::OEScore::AnnotatePose`
      annotates a single pose.

         *pose*
            Structure of a pose within the active site

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

         .. oe:api::

            bool AnnotatePose(OEChem::OEMCMolBase& poses)

      .. oe:language:: python

         .. oe:api:: python

            AnnotatePose(lig: OEMol) -> bool

      This overload of :oe:meth:`OEDocking::OEScore::AnnotatePose`
      annotates all poses of a given ligand.

         *poses*
            An :ref:`OEMCMolBase <OEChem_OEMCMolBase>` the conformers of which are
            poses within the active site.


   .. _OEDocking_OEScore_CacheScoringSetup:



   .. oe:method:: CacheScoringSetup

      This function caches the current scoring setup of the :ref:`OEScore <OEDocking_OEScore>` object onto a
      receptor object.  When another :ref:`OEScore <OEDocking_OEScore>` object is initialized with this
      receptor the it will read in the cached score data rather than
      recalculating it from scratch, thus improving the startup time of the
      :ref:`OEScore <OEDocking_OEScore>` object.

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

         .. oe:api::

            bool CacheScoringSetup(OEBio::OEDesignUnit& receptor,
                                   bool clearOldData = true)
            bool CacheScoringSetup(OEChem::OEMolBase& receptor,
                                   bool clearOldData = true)

      .. oe:language:: python

         .. oe:api:: python

            CacheScoringSetup(du: OEDesignUnit, clearOldData: bool = True) -> bool
            CacheScoringSetup(receptor: Union[OEGraphMol,OEMol,OEQMol],
                              clearOldData: bool = True) -> bool

      *receptor*
         A receptor object.  This must be the same receptor object the :ref:`OEScore <OEDocking_OEScore>`
         object was initialized with or an exact copy.

      *clearOldData*
         Flag to clear cached data from a prior call to CacheScoringSetup with
         this receptor.  The cached data can be quite sizable (hundreds of
         megabytes), so leaving this flag at the default value of true is
         recommended.

      .. note:: The cached score data on a receptor will be saved when the receptor is written to a file.


