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

.. oe:namespace:: OESpruce

.. meta::
   :keywords: OESuperpose, Superpose, Superposition, StructuralSuperposition, SecondaryStructureSuperposition

.. _chapter_sprucetk_superposition:



.. _OESpruce_OESuperpose:

.. oe:class:: OESuperpose

   .. attention::

      |TWOLANGUAGE|

   .. oe:api::

      class OESuperpose

   This class performs a structural superposition of a fit protein onto a
   reference protein. The superposition method (see
   :oe:constns:`OESpruce::OESuperposeMethod`) and other options are controlled
   through the :ref:`OESuperposeOptions <OESpruce_OESuperposeOptions>` class.
   Results including RMSD and TM-score are returned via
   :ref:`OESuperposeResults <OESpruce_OESuperposeResults>`.

   .. seealso::

      * :ref:`OESuperposeOptions <OESpruce_OESuperposeOptions>` class
      * :ref:`OESuperposeResults <OESpruce_OESuperposeResults>` class

   .. admonition:: Code Example

      * :ref:`Spruce_examples_superposition` example


   .. oe:method:: Constructors

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

         .. oe:api::

            OESuperpose(const OESuperposeOptions& opts = OESuperposeOptions(OESuperposeMethod::Default))

      .. oe:language:: python

         .. oe:api:: python

            OESuperpose(opts: OESuperposeOptions = OESuperposeOptions(OESuperposeMethod_Default)) -> OESuperpose

      Constructor for superposing molecules given the specified method and other options.
      If no :ref:`OESuperposeOptions <OESpruce_OESuperposeOptions>` are passed in as ``opts``,
      then the default behavior of using a superposition to all globally matched atoms will be used.

      .. seealso:

         :ref:`OESuperposeOptions <OESpruce_OESuperposeOptions>` class
         :oe:constns:`OESpruce::OESuperposeMethod` namespace

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

         .. oe:api::

            OESuperpose(const OESuperpose& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OESuperpose(rhs: OESuperpose) -> OESuperpose

      Copy constructor.

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

      .. oe:api::

         OESuperpose& operator=(const OESuperpose& rhs)

      Assignment operator.

   .. _OESpruce_OESuperPose_HasRef:


   .. oe:method:: HasRef

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

         .. oe:api::

            bool HasRef() const

      .. oe:language:: python

         .. oe:api:: python

            HasRef() -> bool

      Returns whether or not the reference is set.

   .. _OESpruce_OESuperPose_HasConstraintMol:


   .. oe:method:: HasConstraintMol

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

         .. oe:api::

            bool HasConstraintMol() const

      .. oe:language:: python

         .. oe:api:: python

            HasConstraintMol() -> bool

      Returns whether or not the constraint molecule is set.

   .. _OESpruce_OESuperPose_Clear:


   .. oe:method:: Clear

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

         .. oe:api::

            void Clear()

      .. oe:language:: python

         .. oe:api:: python

            Clear() -> None

      Clears the reference and the constraint molecule.
      
   .. _OESpruce_OESuperPose_SetOptions:


   .. oe:method:: SetOptions

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

         .. oe:api::

            bool SetOptions(const OESuperposeOptions& opts)

      .. oe:language:: python

         .. oe:api:: python

            SetOptions(opts: OESuperposeOptions) -> bool

      Sets the options for the superposition.

      .. seealso:

         :ref:`OESuperposeOptions <OESpruce_OESuperposeOptions>` class


   .. _OESpruce_OESuperPose_SetupRef:


   .. oe:method:: SetupRef

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

         .. oe:api::

            bool SetupRef(const OEBio::OEDesignUnit& refDU,
                          const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& refPred = OEChem::OEIsTrueAtom())
            bool SetupRef(const OEChem::OEMolBase& refMol,
                          const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& refPred = OEChem::OEIsTrueAtom())
            bool SetupRef(const OEChem::OEMolBase& refMol,
                          const OEChem::OEMolBase& refConstraintMol,
                          const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& refPred = OEChem::OEIsTrueAtom())
            bool SetupRef(const OEChem::OEMolBase& refMol,
                          const std::vector<std::string>& siteResidues,
                          const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& refPred = OEChem::OEIsTrueAtom())
            bool SetupRef(const OEChem::OEMolBase& refMol,
                          const OEChem::OEMolBase& refConstraintMol,
                          const std::vector<std::string>& siteResidues,
                          const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& refPred = OEChem::OEIsTrueAtom())

      .. oe:language:: python

         .. oe:api:: python

            SetupRef(refDU: OEDesignUnit,
                     refPred: OEUnaryAtomPred = OEIsTrueAtom()) -> bool
            SetupRef(refMol: Union[OEGraphMol,OEMol,OEQMol],
                     refPred: OEUnaryAtomPred = OEIsTrueAtom()) -> bool
            SetupRef(refMol: Union[OEGraphMol,OEMol,OEQMol],
                     refConstraintMol: Union[OEGraphMol,OEMol,OEQMol],
                     refPred: OEUnaryAtomPred = OEIsTrueAtom()) -> bool
            SetupRef(refMol: Union[OEGraphMol,OEMol,OEQMol],
                     siteResidues: OEStringVector,
                     refPred: OEUnaryAtomPred = OEIsTrueAtom()) -> bool
            SetupRef(refMol: Union[OEGraphMol,OEMol,OEQMol],
                     refConstraintMol: Union[OEGraphMol,OEMol,OEQMol],
                     siteResidues: OEStringVector,
                     refPred: OEUnaryAtomPred = OEIsTrueAtom()) -> bool

      Sets up the reference molecule, constraint molecule, or site residues if given. A predicate (``refPred``) can be 
      passed to subset the reference. If the reference is given as an :ref:`OEDesignUnit <OEBio_OEDesignUnit>` object, then the
      constraint molecule (ligand) and the site residues will be set if such information is available in the design unit. 
      The function returns true if the setup is successful.

      The ``refMol`` argument must have 3D coordinates assigned.

 .. _OESpruce_OESuperPose_SetMethod:


 .. oe:method:: SetMethod

      .. oe:api::

         bool SetMethod(unsigned value)

      Sets the type of superposition to be performed. Types are taken from the
      constants given in :oe:constns:`OESpruce::OESuperposeMethod`.

      .. note::

         This switches the method used during superposition, but not the default, user defined, valid RMSD,
         seqScore, or Tanimoto values.
         This  means switching between a shape and sequence based method requires the user to explicitly set proper
         values for these or, alternatively, reconstruct the class with a new method.

   .. _OESpruce_OESuperPose_Superpose:


   .. oe:method:: Superpose

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

         .. oe:api::

            bool Superpose(OESuperposeResults& results,
                           const OEChem::OEMolBase& fitMol,
                           const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& fitPred = OEChem::OEIsTrueAtom()) const
            bool Superpose(OESuperposeResults& results,
                           const OEChem::OEMolBase& fitMol,
                           const OEChem::OEMolBase& fitConstraintMol,
                           const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& fitPred = OEChem::OEIsTrueAtom()) const
            bool Superpose(OESuperposeResults& results,
                           const OEBio::OEDesignUnit& fitDU,
                           const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& fitPred = OEChem::OEIsTrueAtom()) const

      .. oe:language:: python

         .. oe:api:: python

            Superpose(results: OESuperposeResults,
                      fitMol: Union[OEGraphMol,OEMol,OEQMol],
                      fitPred: OEUnaryAtomPred = OEIsTrueAtom()) -> bool
            Superpose(results: OESuperposeResults,
                      fitMol: Union[OEGraphMol,OEMol,OEQMol],
                      fitConstraintMol: Union[OEGraphMol,OEMol,OEQMol],
                      fitPred: OEUnaryAtomPred = OEIsTrueAtom()) -> bool
            Superpose(results: OESuperposeResults, fitDU: OEDesignUnit,
                      fitPred: OEUnaryAtomPred = OEIsTrueAtom()) -> bool

      Superimposes the fit molecule onto the reference. A predicate (``fitPred``) can be passed to subset the reference. 
      The results for the superposition will be stored in ``results``. The function returns ``results.IsValid()``.

      .. seealso:

         :ref:`OESuperposeResults <OESpruce_OESuperposeResults>` class
