.. oe:namespace:: OEDepict


.. meta::
   :keywords: OEAlignmentOptions, AlignmentOptions


.. _OEDepict_OEAlignmentOptions:

.. oe:class:: OEAlignmentOptions

   .. oe:api::

      class OEAlignmentOptions

   This class represents :ref:`OEAlignmentOptions <OEDepict_OEAlignmentOptions>` and
   stores the following parameters which are used when performing molecule
   alignment.

   .. list-table::
      :widths: 150 100 100
      :header-rows: 1

      * - Property
        - Get method
        - Set method

      * - re-generating 2D coordinates
        - :oe:meth:`GetClearCoords<OEDepict::OEAlignmentOptions::GetClearCoords>`
        - :oe:meth:`SetClearCoords<OEDepict::OEAlignmentOptions::SetClearCoords>`

      * - adding depiction hydrogens
        - :oe:meth:`GetAddDepictionHydrogens<OEDepict::OEAlignmentOptions::GetAddDepictionHydrogens>`
        - :oe:meth:`SetAddDepictionHydrogens<OEDepict::OEAlignmentOptions::SetAddDepictionHydrogens>`

      * - starting from the 2D coords of the reference molecule
        - :oe:meth:`GetFixedCoords<OEDepict::OEAlignmentOptions::GetFixedCoords>`
        - :oe:meth:`SetFixedCoords<OEDepict::OEAlignmentOptions::SetFixedCoords>`

      * - max number of allowed atom pair clushes
        - :oe:meth:`GetMaxAllowedAtomPairClashes<OEDepict::OEAlignmentOptions::GetMaxAllowedAtomPairClashes>`
        - :oe:meth:`SetMaxAllowedAtomPairClashes<OEDepict::OEAlignmentOptions::SetMaxAllowedAtomPairClashes>`

      * - max number of bond rotations
        - :oe:meth:`GetMaxBondRotations<OEDepict::OEAlignmentOptions::GetMaxBondRotations>`
        - :oe:meth:`SetMaxBondRotations<OEDepict::OEAlignmentOptions::SetMaxBondRotations>`

      * - max number of pattern matches
        - :oe:meth:`GetMaxPatternMatches<OEDepict::OEAlignmentOptions::GetMaxPatternMatches>`
        - :oe:meth:`SetMaxPatternMatches<OEDepict::OEAlignmentOptions::SetMaxPatternMatches>`

      * - RMSD cutoff
        - :oe:meth:`GetRMSDCutoff<OEDepict::OEAlignmentOptions::GetRMSDCutoff>`
        - :oe:meth:`SetRMSDCutoff<OEDepict::OEAlignmentOptions::SetRMSDCutoff>`

      * - rotation around bonds
        - :oe:meth:`GetRotateAroundBonds<OEDepict::OEAlignmentOptions::GetRotateAroundBonds>`
        - :oe:meth:`SetRotateAroundBonds<OEDepict::OEAlignmentOptions::SetRotateAroundBonds>`

      * - suppressing hydrogens
        - :oe:meth:`GetSuppressHydrogens<OEDepict::OEAlignmentOptions::GetSuppressHydrogens>`
        - :oe:meth:`SetSuppressHydrogens<OEDepict::OEAlignmentOptions::SetSuppressHydrogens>`

   .. seealso::

      * :oe:func:`OEDepict::OEPrepareAlignedDepiction` function


   .. ################################################################
      # Constructors
      ################################################################

   .. oe:method:: Constructors

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

         .. oe:api::

            OEAlignmentOptions()

      .. oe:language:: python

         .. oe:api:: python

            OEAlignmentOptions() -> OEAlignmentOptions

      Default constructor that initializes an :ref:`OEAlignmentOptions <OEDepict_OEAlignmentOptions>`
      object with the following properties:

      .. list-table::
         :widths: 100 100
         :header-rows: 1

         * - Property
           - Default value

         * - re-generating 2D coordinates
           - true

         * - adding depiction hydrogens
           - true

         * - starting from the 2D coordinates of the reference molecule
           - false

         * - max number of allowed atom pair clushes
           - `0` (means an alignment is rejected if there is any atom clash)

         * - max number of bond rotations
           - :math:`2^{16} = 65536` (max allowed number is :math:`2^{31}`)

         * - max number of pattern matches
           - `0` (means no limit)

         * - RMSD cutoff
           - `0.1`

         * - rotation around bonds
           - true

         * - suppressing hydrogens
           - true

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

         .. oe:api::

            OEAlignmentOptions(bool rotatebonds, bool clearcoords,
                               bool suppressH)

      .. oe:language:: python

         .. oe:api:: python

            OEAlignmentOptions(rotateBonds: bool, clearcoords: bool,
                               suppressH: bool) -> OEAlignmentOptions

      Creates an :ref:`OEAlignmentOptions <OEDepict_OEAlignmentOptions>` object with
      the specified parameters.

      *rotatebonds*
         See the :oe:meth:`OEDepict::OEAlignmentOptions::SetRotateAroundBonds` method.

      *clearcoords*
         See the :oe:meth:`OEDepict::OEAlignmentOptions::SetClearCoords` method.

      *suppressH*
         See the :oe:meth:`OEDepict::OEAlignmentOptions::SetSuppressHydrogens` method.

      By default, the RMSD cutoff is `0.1` (see the :oe:meth:`OEDepict::OEAlignmentOptions::SetRMSDCutoff` method)
      and maximum number of bond rotations is
      :math:`2^{16} = 65536` (see the :oe:meth:`OEDepict::OEAlignmentOptions::SetMaxBondRotations` method).


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

         .. oe:api::

            OEAlignmentOptions(const OEAlignmentOptions& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OEAlignmentOptions(arg2: OEAlignmentOptions) -> OEAlignmentOptions

      Copy constructor.

   .. ################################################################
      # operator=
      ################################################################

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

      .. oe:api::

         OEAlignmentOptions &operator=(const OEAlignmentOptions &rhs)

      Assignment operator.


   .. oe:method:: GetAddDepictionHydrogens

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

         .. oe:api::

            bool GetAddDepictionHydrogens() const

      .. oe:language:: python

         .. oe:api:: python

            GetAddDepictionHydrogens() -> bool

      Returns whether the depiction hydrogens are kept/added during the molecule
      alignment.

   .. seealso::

      * :oe:meth:`OEDepict::OEAlignmentOptions::SetAddDepictionHydrogens` method


   .. oe:method:: GetClearCoords

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

         .. oe:api::

            bool GetClearCoords() const

      .. oe:language:: python

         .. oe:api:: python

            GetClearCoords() -> bool

      Returns whether the 2D coordinates of the *fit* molecule will be
      re-calculated prior to the alignment process.

      .. seealso::

         * :oe:func:`OEDepict::OEDepictCoordinates` function
         * :oe:meth:`OEDepict::OEAlignmentOptions::SetClearCoords` method


   .. oe:method:: GetFixedCoords

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

         .. oe:api::

            bool GetFixedCoords() const

      .. oe:language:: python

         .. oe:api:: python

            GetFixedCoords() -> bool

      Returns whether the :oe:func:`OEDepict::OEPrepareAlignedDepiction`
      function can start the alignment process by copying over the
      coordinates of the *reference* molecule to the *fit* molecule.

      .. seealso::

         * :oe:meth:`OEDepict::OEAlignmentOptions::SetFixedCoords` method


   .. oe:method:: GetMaxAllowedAtomPairClashes

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

         .. oe:api::

            unsigned int GetMaxAllowedAtomPairClashes() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxAllowedAtomPairClashes() -> int

      Returns the maximum number of atom pair clashes allowed in fix
      coordinate mode.

       .. seealso::

         * :oe:meth:`OEDepict::OEAlignmentOptions::SetMaxAllowedAtomPairClashes` method


   .. oe:method:: GetMaxBondRotations

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

         .. oe:api::

            unsigned int GetMaxBondRotations() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxBondRotations() -> int

      Returns the maximum number of bond rotations performed during
      the alignment process.

      The default value for maximum number of bond rotations is
      :math:`2^{16} = 65536`. This means that by default only the first
      16 single bonds of the *fit* molecule will be rotated to maximize
      molecule alignment. The max allowed number is :math:`2^{31}` that
      allows the rotate `31` bonds independently to find the best
      alignment.

      .. seealso::

         * :oe:meth:`OEDepict::OEAlignmentOptions::SetMaxBondRotations` method


   .. oe:method:: GetMaxPatternMatches

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

         .. oe:api::

            unsigned int GetMaxPatternMatches() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxPatternMatches() -> int

      Returns the maximum number of matches utilized to performed
      molecule alignments.

      .. seealso::

         * :oe:meth:`OEDepict::OEAlignmentOptions::SetMaxPatternMatches` method


   .. oe:method:: GetRMSDCutoff

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

         .. oe:api::

            double GetRMSDCutoff() const

      .. oe:language:: python

         .. oe:api:: python

            GetRMSDCutoff() -> float

      Returns the RMSD cutoff value used to identify acceptable
      alignments.

      .. seealso::

         * :oe:meth:`OEDepict::OEAlignmentOptions::SetRMSDCutoff` method


   .. oe:method:: GetRotateAroundBonds

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

         .. oe:api::

            bool GetRotateAroundBonds() const

      .. oe:language:: python

         .. oe:api:: python

            GetRotateAroundBonds() -> bool

      Returns whether rotation around the bonds of the *fit* molecule
      is allowed.

      .. seealso::

         * :oe:meth:`OEDepict::OEAlignmentOptions::SetRotateAroundBonds` method


   .. oe:method:: GetSuppressHydrogens

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

         .. oe:api::

            bool GetSuppressHydrogens() const

      .. oe:language:: python

         .. oe:api:: python

            GetSuppressHydrogens() -> bool

      Returns whether the explicit hydrogens are suppressed in the *fit*
      molecule prior to the alignment process.

      .. seealso::

         * :oe:meth:`OEDepict::OEAlignmentOptions::SetSuppressHydrogens` method


   .. oe:method:: SetAddDepictionHydrogens

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

         .. oe:api::

            void SetAddDepictionHydrogens(bool)

      .. oe:language:: python

         .. oe:api:: python

            SetAddDepictionHydrogens(a: bool) -> None

      Sets whether depiction hydrogens are kept/added during alignment.

      .. seealso::

         * :oe:func:`OEDepict::OEAddDepictionHydrogens` function
         * :oe:meth:`OEDepict::OEPrepareDepictionOptions::GetAddDepictionHydrogens` method


   .. oe:method:: SetClearCoords

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

         .. oe:api::

            void SetClearCoords(bool clearcoords)

      .. oe:language:: python

         .. oe:api:: python

            SetClearCoords(c: bool) -> None

      Sets whether the 2D coordinates of the *fit* molecule will be
      re-calculated prior to the alignment process by calling the
      :oe:func:`OEDepict::OEPrepareDepiction` function.

      .. seealso::

         * :oe:func:`OEDepict::OEDepictCoordinates` function
         * :oe:meth:`OEDepict::OEAlignmentOptions::GetClearCoords` method


   .. oe:method::  SetFixedCoords

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

         .. oe:api::

            void SetFixedCoords(bool fixed)

      .. oe:language:: python

         .. oe:api:: python

            SetFixedCoords(f: bool) -> None

      Sets whether the :oe:func:`OEDepict::OEPrepareAlignedDepiction`
      function can start the alignment process by copying over the
      coordinates of the *reference* molecule to the *fit* molecule based
      on the provided match.

      If the alignment process based of 'fixed' coordinates can not be
      performed or it is unsuccessful *i.e.* no alignment is found
      without atom clashes
      than the :oe:func:`OEDepict::OEPrepareAlignedDepiction` function
      falls back to maximizing the overlap between the *fit* and the
      *reference* 2D molecules by rotating around single bonds.
      See also :oe:meth:`OEDepict::OEAlignmentOptions::SetMaxAllowedAtomPairClashes`
      method that can be used to allow some atom clashes.

      The alignment process based on 'fixed' coordinates currently
      can only be performed if:

      * neither the *reference* nor the *fit* molecule have more
        than one component
      * there is no partial ring match *i.e.* if a ring atom of
        the *fit* molecule is matched for alignment than all of the atom
        of the same ring systems have to be matched for alignment

      .. seealso::

         * :oe:meth:`OEDepict::OEAlignmentOptions::GetFixedCoords` method

   .. oe:method:: SetMaxAllowedAtomPairClashes

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

         .. oe:api::

            void SetMaxAllowedAtomPairClashes(unsigned int maxclashes)

      .. oe:language:: python

         .. oe:api:: python

            SetMaxAllowedAtomPairClashes(m: int) -> None

      Sets the number of atom pair clashes allowed after the 'fixed'
      coordinates alignment process
      (see :oe:meth:`OEDepict::OEAlignmentOptions::SetFixedCoords` method).
      The default value is ``0``, i.e. no atom clashes are allowed.
      If the number of clashes exceeds this
      limit the alignment is rejected and process falls back to
      maximizing the overlap between the *fit* and the
      *reference* 2D molecules by rotating around single bonds.

      .. seealso::

         * :oe:meth:`OEDepict::OEAlignmentOptions::SetMaxAllowedAtomPairClashes` method


   .. oe:method:: SetMaxBondRotations

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

         .. oe:api::

            void SetMaxBondRotations(unsigned int maxrotations)

      .. oe:language:: python

         .. oe:api:: python

            SetMaxBondRotations(m: int) -> None

      Sets the maximum number of bond rotations performed during
      the alignment process.

      *maxrotations*
        The zero value means that there is no limit.
        Upon reaching this limit, the alignment process terminates
        and returns the best alignment identified up to that point.

      .. hint::

         The default value for maximum number of bond rotations is
         :math:`2^{16} = 65536`. This means that by default only the first
         16 single bonds of the *fit* molecule will be rotated to maximize
         molecule alignment.

         It is recommended to use this parameter in the following cases:

         * if the *fit* molecule being aligned has a large number of rotatable
           bonds

         * if the match that determines the atoms of the *fit* molecule
           that will be aligned to the atoms of the *reference* molecule
           has a large number of rotatable bonds

      .. seealso::

         * :oe:meth:`OEDepict::OEAlignmentOptions::GetMaxBondRotations` method


   .. oe:method:: SetMaxPatternMatches

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

         .. oe:api::

            void SetMaxPatternMatches(unsigned int maxmatches)

      .. oe:language:: python

         .. oe:api:: python

            SetMaxPatternMatches(m: int) -> None

      Sets the maximum number of matches utilized to perform molecule
      alignments.

      *maxmatches*
         The zero value means that there is no limit.
         If the molecule alignment is based on more than one matches,
         then upon reaching this limit, the alignment process terminates
         and returns the best alignment identified up to that point.

      .. hint::

         It is recommended to use this parameter in the following cases:

         * if the alignment is based on substructure or maximum common
           substructure matches and the *reference* or/and *fit* molecules
           are highly symmetrical *i.e.* a large number of matches
           returned by the substructure or maximum common substructure
           search algorithms, respectively.

      .. seealso::

         * :oe:meth:`OEDepict::OEAlignmentOptions::GetMaxPatternMatches` method


   .. oe:method:: SetRMSDCutoff

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

         .. oe:api::

            void SetRMSDCutoff(double rmsdcutoff)

      .. oe:language:: python

         .. oe:api:: python

            SetRMSDCutoff(r: float) -> None

      Sets the RMSD cutoff value used to identify acceptable
      alignments.

      *rmsdcutoff*
        This number has to be non-negative number.
        The alignment procedure terminates when the *rmsdcutoff* between
        the *fit* and the *reference* molecule is below this limit and there is no
        internal clash detected between the atoms of the *fit* molecule.

      .. seealso::

        * :oe:meth:`OEDepict::OEAlignmentOptions::GetRMSDCutoff` method


   .. oe:method:: SetRotateAroundBonds

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

         .. oe:api::

            void SetRotateAroundBonds(bool rotatebonds)

      .. oe:language:: python

         .. oe:api:: python

            SetRotateAroundBonds(r: bool) -> None

      Sets whether rotation around the bonds of the *fit* molecule
      is allowed.

      *rotatebonds*
         If 'true', then bond of the *fit* molecule will be rotated to
         find the best alignment between molecules.
         If 'false', then only 2D rotation and translation of the *fit*
         molecule is allowed (*i.e.* no rotations around bonds) in order
         to align it to the *reference* molecule

      .. seealso::

        * :oe:meth:`OEDepict::OEAlignmentOptions::GetRotateAroundBonds` method


   .. oe:method:: SetSuppressHydrogens

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

         .. oe:api::

            void SetSuppressHydrogens(bool)

      .. oe:language:: python

         .. oe:api:: python

            SetSuppressHydrogens(s: bool) -> None

      Sets whether the explicit hydrogens are suppressed in the *fit*
      molecule prior to the alignment process.
      Only hydrogens that are necessary to faithfully represent
      tetrahedral stereochemistry will be kept.

      .. seealso::

         * :oe:func:`OEDepict::OEAddDepictionHydrogens` function
         * :oe:func:`OEDepict::OEHasDepictionHydrogens` function
         * :oe:meth:`OEDepict::OEAlignmentOptions::GetSuppressHydrogens` method
