.. include:: ../../toolkit-substitutions

.. oe:namespace:: OEDocking

.. meta::
   :keywords: OEPosit, Posit


.. _OEDocking_OEPosit:

.. oe:class:: OEPosit

   .. oe:api::

      class OEPosit

   :ref:`OEPosit <OEDocking_OEPosit>` is used to pose predict multiconformer
   molecules in an active site.

   The :ref:`OEPosit <OEDocking_OEPosit>` class defines the following public methods:
    * :oe:meth:`AddReceptor<OEDocking::OEPosit::AddReceptor>`
    * :oe:meth:`ClearReceptors<OEDocking::OEPosit::ClearReceptors>`
    * :oe:meth:`Dock<OEDocking::OEPosit::Dock>`
    * :oe:meth:`GetHighScoresAreBetter<OEDocking::OEPosit::GetHighScoresAreBetter>`
    * :oe:meth:`GetName<OEDocking::OEPosit::GetName>`
    * :oe:meth:`GetInvalidScore<OEDocking::OEPosit::GetInvalidScore>`
    * :oe:meth:`MethodChoice<OEDocking::OEPosit::MethodChoice>`
    * :oe:meth:`RankDesignUnits<OEDocking::OEPosit::RankDesignUnits>`
    * :oe:meth:`ScoreLigand<OEDocking::OEPosit::ScoreLigand>`

  Deprecated methods of the class:
    * :oe:meth:`DockMultiConformerMolecule<OEDocking::OEPosit::DockMultiConformerMolecule>`
    * :oe:meth:`Initialize<OEDocking::OEPosit::Initialize>`
    * :oe:meth:`RankReceptors<OEDocking::OEPosit::RankReceptors>`


   .. oe:method:: Constructor

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

         .. oe:api::

            OEPosit( const OEPositOptions& options = OEPositOptions() )
            OEPosit(const OEPosit &)

      .. oe:language:: python

         .. oe:api:: python

            OEPosit(options: OEPositOptions = OEPositOptions()) -> OEPosit
            OEPosit(arg2: OEPosit) -> OEPosit

      Default and copy constructors.

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

      .. oe:api::

         OEPosit &operator=(const OEPosit &)


.. _OEDocking_OEPosit_AddReceptor:

      Assignment operator.


   .. oe:method:: AddReceptor

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

         .. oe:api::

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

      .. oe:language:: python

         .. oe:api:: python

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

      Adds a receptor to the list of receptors to pose against. The function returns ``true`` if receptor is 
      addded successful. 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::

      Since **OEPosit** can generate pose using any of the methods described in :oe:constns:`OEDocking::OEPositMethod`,
      constraints present in the receptor may or may not play any role for the specific pose generation. 
      Constraints only effect the generated pose when :oe:const:`OEDocking::OEPositMethod::FRED` or 
      :oe:const:`OEDocking::OEPositMethod::HYBRID` is the underlying method.


.. _OEDocking_OEPosit_ClearReceptors:

   .. oe:method:: ClearReceptors

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

         .. oe:api::

            void ClearReceptors()

      .. oe:language:: python

         .. oe:api:: python

            ClearReceptors() -> None

      Removes all existing receptors. Removing receptors will un-initialize an
      already initialized :ref:`OEPosit <OEDocking_OEPosit>` instance.


.. _OEDocking_OEPosit_Dock:

   .. oe:method:: Dock

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

         .. oe:api::

            unsigned Dock(OESinglePoseResult& res,
                          const OEChem::OEMCMolBase& mol) const
            unsigned Dock(OEPositResults& res, const OEChem::OEMCMolBase& mol,
                          const unsigned numPoses = 1) const

      .. oe:language:: python

         .. oe:api:: python

            Dock(res: OESinglePoseResult, mol: OEMol) -> int
            Dock(res: OEPositResults, mol: OEMol, numPoses: int = 1) -> int

      Dock the input molecule ``mol``.  The second overload can return alternate docked poses,
      in addition to the top scoring pose, with ``numPoses`` being the maximum desired number of poses.

      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.


.. _OEDocking_OEPosit_GetHighScoresAreBetter:

   .. oe:method:: GetHighScoresAreBetter

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

         .. oe:api::

            bool GetHighScoresAreBetter() const

      .. oe:language:: python

         .. oe:api:: python

            GetHighScoresAreBetter() -> bool

      This always returns ``true`` for ``OEPosit``.


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


.. _OEDocking_OEPosit_GetInvalidScore:

   .. oe:method:: GetInvalidScore

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

         .. oe:api::

            float  GetInvalidScore() const

      .. oe:language:: python

         .. oe:api:: python

            GetInvalidScore() -> float

      Returns the invalid score returned by OEPosit. These values are set up to
      sort invalid values in reverse order from the best reported values.


.. _OEDocking_OEPosit_IsInitialized:

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


.. _OEDocking_OEPosit_MethodChoice:

   .. oe:method:: MethodChoice

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

         .. oe:api::

            unsigned MethodChoice(const unsigned recIdx,
                                  const OEChem::OEMCMolBase& mol) const

      .. oe:language:: python

         .. oe:api:: python

            MethodChoice(recIdx: int, mol: OEMol) -> int

      Returns the method that would be used for pose prediction for a given ligand against a given receptor.


.. _OEDocking_OEPosit_RankDesignUnits:

   .. oe:method:: RankDesignUnits

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

         .. oe:api::

            OESystem::OEIterBase<OEBio::OEDesignUnit>* RankDesignUnits(const OEChem::OEMCMolBase& mol) const

      .. oe:language:: python

         .. oe:api:: python

            RankDesignUnits(mol: OEMol) -> Iterable[OEDesignUnit]

      Rank the design units, from best to worst receptors, to pose against, for the specified ligand.


.. _OEDocking_OEPosit_DockMultiConformerMolecule:

   .. oe:method:: DockMultiConformerMolecule

      .. warning::

         |DEPRECATED-API|
         Please use :oe:meth:`OEPosit::Dock<OEDocking::OEPosit::Dock>` instead.

      Both overloads of this method dock *inputMol* into the receptor added by the
      :oe:meth:`OEDocking::OEPosit::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::OEPosit::DockMultiConformerMolecule` returns
      the top scoring pose.

         *dockedMol*
            Docked pose with the best pose prediction probability of *inputMol*.

         *inputMol*
            A multiconformer representation of a molecule to dock.

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


.. _OEDocking_OEPosit_Initialize:

   .. oe:method:: Initialize

      .. warning::

         |DEPRECATED-API|
         Please use :oe:meth:`OEPosit::AddReceptor<OEDocking::OEPosit::AddReceptor>` instead.

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

         .. oe:api::

            bool Initialize(const OEChem::OEMolBase& receptor)

      .. oe:language:: python

         .. oe:api:: python

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

      Initializes :ref:`OEPosit <OEDocking_OEPosit>` with receptor to pose ligand against. Calling
      initialize will remove any existing receptors in the current :ref:`OEPosit <OEDocking_OEPosit>`
      instance. Function returns ``true`` if setup was successful and ``false`` otherwise.


.. _OEDocking_OEPosit_RankReceptors:

   .. oe:method:: RankReceptors

      .. warning::

         |DEPRECATED-API|
         Please use :oe:meth:`OEPosit::RankDesignUnits<OEDocking::OEPosit::RankDesignUnits>` instead.

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

         .. oe:api::

            OESystem::OEIterBase<OEChem::OEMolBase>* RankReceptors(const OEChem::OEMCMolBase&) const

      .. oe:language:: python

         .. oe:api:: python

            RankReceptors(mol: OEMol) -> Iterable[Union[OEGraphMol, OEMol, OEQMol]]

      Rank the receptors, from best to worst, to pose against, for the specified ligand.


.. _OEDocking_OEPosit_ScoreLigand:

   .. oe:method:: ScoreLigand

      .. warning::

         |DEPRECATED-API|
         This method is only compatible with 
         :oe:meth:`DockMultiConformerMolecule<OEDocking::OEPosit::DockMultiConformerMolecule>`, for
         obtaining a score (pose probability) after the pose has been generated.

         Method provides invalid score when called on poses generated using 
         :oe:meth:`Dock<OEDocking::OEPosit::Dock>`.  The scores (pose probability) from that calculation 
         are available in the resulting :ref:`OESinglePoseResult <OEDocking_OESinglePoseResult>`.

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

         .. oe:api::

            float ScoreLigand(const OEChem::OEMolBase& pose) const

      .. oe:language:: python

         .. oe:api:: python

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

      Rescores a pose within the active site.

      If an error occurs this function will return the limiting large double in C++.
