.. oe:namespace:: OEBio



.. _OEBio_OEPlaceHydrogensDetails:

.. oe:class:: OEPlaceHydrogensDetails

   .. oe:api::


      class OEPlaceHydrogensDetails

   The *read-only* container `OEPlaceHydrogensDetails` holds information about
   the results of applying the function :oe:func:`OEBio::OEPlaceHydrogens`
   to a particular molecule. Details objects can provide insight into
   the conformational states and how they were chosen.

   Information is broken down into clusters (including singletons)
   of "movers" or moving functional groups and their associated
   "background" of non-moving groups. Information about each mover is
   collected in a corresponding
   :oe:cls:`OEPlaceHydrogensMoverNote<OEBio::OEPlaceHydrogensMoverNote>`.

   .. seealso::

      * :ref:`section_place_hydrogens` section
      * :oe:func:`OEBio::OEPlaceHydrogens` function
      * :ref:`OEPlaceHydrogensMoverNote <OEBio_OEPlaceHydrogensMoverNote>` class

   .. oe:method:: Constructors

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

         .. oe:api::

            OEPlaceHydrogensDetails()
            OEPlaceHydrogensDetails(const OEPlaceHydrogensDetails& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OEPlaceHydrogensDetails() -> OEPlaceHydrogensDetails
            OEPlaceHydrogensDetails(rhs: OEPlaceHydrogensDetails) -> OEPlaceHydrogensDetails

      Default and copy constructor.

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

      .. oe:api::

         OEPlaceHydrogensDetails &operator=(const OEPlaceHydrogensDetails &rhs)

      Assignment operator.

   .. oe:method:: ClusterHasBadClash

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

         .. oe:api::

            bool ClusterHasBadClash(unsigned clusterIdx) const

      .. oe:language:: python

         .. oe:api:: python

            ClusterHasBadClash(clusterIdx: int) -> bool

      Returns ``true`` if the cluster referred to by `clusterIdx`
      is in a conformation that generates a "bad" atom-atom clash.

      .. seealso::

         * :oe:meth:`GetNumClusters<OEBio::OEPlaceHydrogensDetails::GetNumClusters>` method
         * :oe:meth:`OEBio::OEPlaceHydrogensOptions::SetBadClashOverlapDistance` method
         * :oe:meth:`OEBio::OEPlaceHydrogensOptions::GetBadClashOverlapDistance` method

   .. oe:method:: Describe

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

         .. oe:api::

            std::string Describe(bool showBackground = false) const

      .. oe:language:: python

         .. oe:api:: python

            Describe(showBackground: bool = False) -> str

      Returns a multi-line description of the conformation and score
      of movers in each cluster processed by the
      :oe:func:`OEPlaceHydrogens<OEBio::OEPlaceHydrogens>` function.

      .. code-block:: bash

         OEBio 2.1.1: score system MMFF-NIE: flip bias 2.000
         87 clusters : 5 flips
         cluster 0  : score -53.935!
                      CG  ASN44(A)   :      amide:   -6.084  (o=-53.93!,f=-8.42!)
                      NZ  LYS47(A)   : NH3 150deg:  -14.865
                      CG  HIS80(A)   :    +bothHN:   -5.628  (o=-53.93!,f=-15.89!)
                      OG1 THR81(A)   : OH   65deg:    1.255
                      CD  GLN87(A)   :FLIP  amide:   -4.976  (o=-26.48!,f=-53.93!)
                      CG  ASN126(A)  :      amide:   -5.193  (o=-53.93!,f=-35.33!)
                      CG  ASN169(A)  :      amide:   -2.230  (o=-53.93!,f=-33.02!)
                      CD  GLN203(A)  :      amide:   -1.400  (o=-53.93!,f=-15.53!)
                      CG  HIS205(A)  :    +bothHN:   -8.693! (o=-53.93!,f=-6.89!)
                      OG1 THR232(A)  : OH  179deg:    9.120
                      O3B XYP601(A)  : OH  280deg:   -5.020
                      O2B XYP601(A)  : OH  173deg:    3.917
                      O4B XYP601(A)  : OH   50deg:    1.236
                      O3  XIF602(A)  : OH   29deg:   -3.688
         cluster 1  : score -85.724!
                      CG  HIS85(A)   :    +bothHN:   -7.737! (o=-85.72!,f=-84.85!)
                      OG  SER86(A)   : OH  241deg:    2.116
                      OG  SER139(A)  : OH  185deg:    3.367!
                      OH  TYR171(A)  : OH   25deg:   -3.384
                      CG  ASN172(A)  :      amide:    1.153  (o=-85.72!,f=-68.75!)
                      NZ  LYS179(A)  : NH3 188deg:  -39.497
         ...
         single  13 : OG1 THR2(A)    : OH  151deg:    1.545
         single  14 : OG  SER25(A)   : OH  292deg:    2.046
         single  15 : OH  TYR29(A)   : OH  199deg:   -1.262
         single  16 : OG  SER35(A)   : OH  254deg:    1.935
         ...

      Key elements in the description output:

      * The score system is ``MMFF-NIE`` which stands for
        "MMFF Neighbor Interaction Energies". This is is a physics based
        score where the Coulombic and Van der Waals terms are from MMFF94
        (including MMFF partial charges), with a weighting factor of 1:3 Coulomb
        to VDW. There are biases against ionization and "flipping" a group.
        Interactions are scored between movers and between movers and non-moving
        background atoms. Background atoms are neighboring atoms that form a
        "dipole cluster", the sum of the partial charges of these clusters are
        the same as the sum of the formal charges.

      * The count ``87 clusters`` includes both groups of interacting movers
        and singletons, movers that interact only with non-moving atoms or waters.

      * ``5 flips`` indicates that five movers were "flipped" by 180 degrees to
        improve hydrogen bonding or avoid clashes. Groups such as the asparagine
        sidechain ``CD  GLN87(A)   :FLIP  amide:`` are occasionally modeled
        with certain heavy atoms in the wrong orientation. Any free amide or
        imidazole group will be considered for flipping.

      * The score in ``OG  SER139(A)  : OH  185deg:    3.367!`` is from
        ``score system MMFF-NIE`` for this mover in the specified
        conformation. Lower numbers represent better scores. The exclamation
        point (!) indicates a clash between this group and another group or
        non-moving background atom.

      * The score in ``cluster 0  : score -53.935!`` is the sum of both the mover
        scores, and the background scores (not shown here, but displayable if
        the ``showBackground`` parameter is set to ``true``).
        The exclamation point (!) indicates that at least one mover had a clash.

      * The pair of scores for flippable groups ``(o=-53.93!,f=-8.42!)``
        are the best cluster scores for both the original (o) and the
        flipped (f) state. After the basic
        optimization, each flippable mover in a cluster is fixed in the opposite
        flip state and the optimization is re-run. A group is flipped
        only if the flipped cluster score is lower than the original score
        by more than ``flip bias 2.000``.

      * Imidazoles have both flipped states and three protonation states for
        each flip state. The description indicates whether the group is flipped
        and where protons are with respect to the two ring nitrogens:
        ``:     no HE2:`` *neutral with HD1 but no HE2* or
        ``:FLIP no HD1:`` *flipped neutral with HE2 but no HD1* or
        ``:    +bothHN:`` *+ charged with two NH protons.*

      * Other groups have descriptions of their state.
        ``O3B XYP601(A)  : OH  280deg:`` shows the orientation of one
        of the hydroxyl rotors in the residue XYP.

      * Waters (not shown above) are processed after other movers,
        progressively in shells away from the protein.

      .. seealso::

         * :oe:meth:`OEBio::OEPlaceHydrogensMoverNote::Describe` method
         * :oe:constns:`OEBio::OEPlaceHydrogensMoverClass` constants

   .. oe:method:: GetClusterScore

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

         .. oe:api::

            double GetClusterScore(unsigned clusterIdx) const

      .. oe:language:: python

         .. oe:api:: python

            GetClusterScore(clusterIdx: int) -> float

      Returns the combined score of all the movers (plus non-moving background)
      of the cluster referred to by `clusterIdx`.

      .. seealso::

         * :oe:meth:`GetNumClusters<OEBio::OEPlaceHydrogensDetails::GetNumClusters>` method

   .. oe:method:: GetFlipBias

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

         .. oe:api::

            double GetFlipBias() const

      .. oe:language:: python

         .. oe:api:: python

            GetFlipBias() -> float

      Returns the score bias against flipping functional groups (e.g. imidazole, amide)
      used by :oe:func:`OEPlaceHydrogens<OEBio::OEPlaceHydrogens>` when this
      details object was produced.

      .. seealso::

         * :oe:meth:`OEBio::OEPlaceHydrogensOptions::GetFlipBias` method

   .. oe:method:: GetMoverNotes

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

         .. oe:api::

            OESystem::OEIterBase<OEPlaceHydrogensMoverNote>* GetMoverNotes(unsigned clusterIdx) const

      .. oe:language:: python

         .. oe:api:: python

            GetMoverNotes(clusterIdx: int) -> Iterable[OEPlaceHydrogensMoverNote]

      Returns an iterator of all the
      :oe:cls:`mover notes<OEBio::OEPlaceHydrogensMoverNote>`
      describing the state of movers in the cluster referred to by `clusterIdx`.

      .. seealso::

         * :ref:`OEPlaceHydrogensMoverNote <OEBio_OEPlaceHydrogensMoverNote>`
         * :ref:`OEIter <OESystem_OEIter>` class

   .. oe:method:: GetNumClusters

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

         .. oe:api::

            unsigned GetNumClusters() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumClusters() -> int

      Returns the number of mover clusters processed
      by :oe:func:`OEPlaceHydrogens<OEBio::OEPlaceHydrogens>` when this
      details object was produced.

   .. oe:method:: GetNumFlips

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

         .. oe:api::

            unsigned GetNumFlips() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumFlips() -> int

      Returns the number movers
      :oe:func:`OEPlaceHydrogens<OEBio::OEPlaceHydrogens>`
      decided to flip when this details object was produced.

      .. seealso::

         * :oe:meth:`OEBio::OEPlaceHydrogensOptions::GetFlipBias` method

   .. oe:method:: GetNumHydrogensStandardized

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

         .. oe:api::

            unsigned GetNumHydrogensStandardized() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumHydrogensStandardized() -> int

      Returns the number of bonds between a hydrogen and a heavy atom
      whose length was adjusted by
      :oe:func:`OEPlaceHydrogens<OEBio::OEPlaceHydrogens>`
      when this details object was produced.

      .. seealso::

         * :oe:meth:`OEBio::OEPlaceHydrogensOptions::SetStandardizeBondLen` method


   .. oe:method:: GetNumMovers

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

         .. oe:api::

            unsigned GetNumMovers(unsigned clusterIdx) const

      .. oe:language:: python

         .. oe:api:: python

            GetNumMovers(clusterIdx: int) -> int

      Returns the number of movers in the cluster referred to by `clusterIdx`
      (including all non-moving background "movers").

      .. seealso::

         * :oe:meth:`GetNumClusters<OEBio::OEPlaceHydrogensDetails::GetNumClusters>` method
         * :oe:meth:`IsSingleton<OEBio::OEPlaceHydrogensDetails::IsSingleton>` method
         * :oe:meth:`GetMoverNotes<OEBio::OEPlaceHydrogensDetails::GetMoverNotes>` method

   .. oe:method:: IsSingleton

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

         .. oe:api::

            bool IsSingleton(unsigned clusterIdx) const

      .. oe:language:: python

         .. oe:api:: python

            IsSingleton(clusterIdx: int) -> bool

      Returns ``true`` if the cluster referred to by `clusterIdx`
      only contains a single mover
      (not counting the corresponding non-moving background).

      .. seealso::

         * :oe:meth:`GetNumMovers<OEBio::OEPlaceHydrogensDetails::GetNumMovers>` method

   .. oe:method:: IsValid

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

         .. oe:api::

            bool IsValid() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool

      Returns ``true`` if this details object contains valid information.
      Returns ``false`` if
      :oe:func:`OEPlaceHydrogens<OEBio::OEPlaceHydrogens>` failed.
