.. oe:namespace:: OEDocking


.. meta::
   :keywords: OEDock, Dock


.. _OEDocking_OEDock:

.. oe:class:: OEDock

   .. oe:api::

      class OEDock

   :ref:`OEDock <OEDocking_OEDock>` is used to dock and score multiconformer
   molecules in an active site.

   Use the following procedure to dock and score molecules with this class.

   #. Initialize the active site by passing a design unit containing a receptor (see
      :ref:`chapter_receptor` chapter) to the
      :oe:meth:`OEDocking::OEDock::Initialize` method.

   #. Dock molecules using the
      :oe:meth:`OEDocking::OEDock::DockMultiConformerMolecule` method.

   #. Score docked molecules with any of the following methods

      * :oe:meth:`OEDocking::OEDock::ScoreLigand`
      * :oe:meth:`OEDocking::OEDock::ScoreAtom`
      * :oe:meth:`OEDocking::OEDock::ScoreLigandComponent`
      * :oe:meth:`OEDocking::OEDock::ScoreAtomComponent`
      * :oe:meth:`OEDocking::OEDock::AnnotatePose`

   .. oe:method:: Constructor

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

         .. oe:api::

            OEDock(unsigned int scoring = OEDockMethod::Default,
            unsigned int resolution = OESearchResolution::Default)
            OEDock(const OEDockOptions&)
            OEDock(const OEDock&)

      .. oe:language:: python

         .. oe:api:: python

            OEDock(scoring: int, resolution: int) -> OEDock
            OEDock(arg2: OEDockOptions) -> OEDock
            OEDock(arg2: OEDock) -> OEDock

   Default and copy constructors.

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

      .. oe:api::

         OEDock & operator=(const OEDock & rhs)

      Assignment operator.


   .. oe:method:: IsInitialized

   .. oe:api::

               bool IsInitialized() const

   Returns true if this object has been successfully initialized
   and is ready to dock molecules.
   
   .. oe:method:: Initialize

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

         .. oe:api::

            bool Initialize(const OEBio::OEDesignUnit&)
            bool Initialize(const OEChem::OEMolBase&)

      .. oe:language:: python

         .. oe:api:: python

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

      Sets up this object to dock molecules into a receptor. 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.

      Note: This method can take several minutes to complete with larger active sites.

   ..   _OEDocking_DockMultiConformerMolecule:

   .. oe:method:: DockMultiConformerMolecule

      Both overloads of this method dock *inputMol* into the receptor passed to the 
      :oe:meth:`OEDocking::OEDock::Initialize` method.  

      The return value of this method describes the result of the docking, 
      with a value from the :oe:constns:`OEDocking::OEDockingReturnCode` namespace.
      A result of :oe:const:`OEDocking::OEDockingReturnCode::Success` indicates
      docking was successful.

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

         .. oe:api::

            unsigned int DockMultiConformerMolecule(OEChem::OEMolBase& dockedMol,
                                                    const OEChem::OEMCMolBase& inputMol)

      .. oe:language:: python

         .. oe:api:: python

            DockMultiConformerMolecule(dockedMol: Union[OEGraphMol,OEMol,OEQMol],
                                       inputMol: OEMol) -> int

      This overload of 
      :oe:meth:`OEDocking::OEDock::DockMultiConformerMolecule` returns 
      the top scoring pose.

         *dockedMol*   
            Top scoring docked pose of *inputMol*.

         *inputMol*    
            A multiconformer representation of a molecule to dock.
            Must have 3D coordinates assigned.

      The score of the docked pose can be obtained by calling the
      :oe:cls:`OEChem::OEMolBase::GetEnergy` method of *dockedMol*.

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

         .. oe:api::

            unsigned int DockMultiConformerMolecule(OEChem::OEMCMolBase& dockedMol,
                                                    const OEChem::OEMCMolBase& inputMol,
                                                    unsigned int numPoses = 1)

      .. oe:language:: python

         .. oe:api:: python

            DockMultiConformerMolecule(dockedMol: OEMol, inputMol: OEMol,
                                       numPoses: int = 1) -> int

      This overload of 
      :oe:meth:`OEDocking::OEDock::DockMultiConformerMolecule` can
      return alternate docked poses, in addition to the top scoring pose.
         
         *dockedMol*   
            Docked poses of *inputMol*.  Poses are stored as
            conformers of the :ref:`OEMCMolBase <OEChem_OEMCMolBase>`
            and are sorted by score.

         *inputMol*    
            A multiconformer representation of a molecule to dock.
            Must have 3D coordinates assigned.

         *numPoses*    
            Maximum number of top scoring docked poses to return
            in *dockedMol*.  Typically this will be the number of
            poses returned, however, in highly restricted sites fewer
            than *numPoses* may be returned.  The value of *numPoses*
            must be greater than zero.

      The score of the docked poses can be obtained by calling the
      :oe:cls:`OEChem::OEMolBase::GetEnergy` method on the conformers of *dockedMol*.

   .. 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.

   .. 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 docked poses are scored with.

   .. 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]

   .. oe:method:: ScoreLigand

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

         .. oe:api::

            float ScoreLigand(const OEChem::OEMolBase& pose)

      .. oe:language:: python

         .. oe:api:: python

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

      Rescores 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::OEDock::GetHighScoresAreBetter` returns false
      or -FLT_MAX otherwise.

   .. oe:method:: ScoreAtom

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

         .. oe:api::

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

      .. oe:language:: python

         .. oe:api:: python

            ScoreAtom(atom: OEAtomBase, pose: 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::OEDock::GetHighScoresAreBetter` returns false
      or -FLT_MAX otherwise.

   .. 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(pose: Union[OEGraphMol,OEMol,OEQMol],
                                 compName: str) -> float

      Returns the given components 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::OEDock::GetComponentNames`.

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

   .. oe:method:: ScoreAtomComponent

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

         .. oe:api::

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

      .. oe:language:: python

         .. oe:api:: python

            ScoreAtomComponent(atom: OEAtomBase,
                               pose: 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::OEDock::GetComponentNames`.

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

   .. 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(pose: OEMol) -> bool
            AnnotatePose(pose: Union[OEGraphMol,OEQMol]) -> bool

      This overload of :oe:meth:`OEDocking::OEDock::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(pose: OEMol) -> bool
            AnnotatePose(pose: Union[OEGraphMol,OEQMol]) -> bool

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

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

   .. oe:method:: CacheScoringSetup

      This function caches the current scoring setup of the 
      :ref:`OEDock <OEDocking_OEDock>` object onto a receptor object.  When
      another :ref:`OEDock <OEDocking_OEDock>` 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:`OEDock <OEDocking_OEDock>` 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:`OEDock <OEDocking_OEDock>`
         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.


