.. oe:namespace:: OEChem

.. include:: ../substitutions

.. meta::
   :keywords: OEResidue, Residue


.. _OEChem_OEResidue:

.. oe:class:: OEResidue

   .. oe:api::

      class OEResidue

   The :ref:`OEResidue <OEChem_OEResidue>` class is used to attach biopolymer
   information to each :ref:`OEAtomBase <OEChem_OEAtomBase>` object.
   This class contains a number of fields specific to processing
   macromolecules, such as proteins and nucleic acids.
   Each atom may be annotated with a unique
   :ref:`OEResidue <OEChem_OEResidue>`, hence :ref:`OEResidue <OEChem_OEResidue>`
   objects are not shared between different atoms.
   If the fields of an :ref:`OEResidue <OEChem_OEResidue>` associated with a
   single atom are updated, only that atom is affected.
   To adapt to the change for mmCIF where a chainID can now contain
   multiple characters, the chainID is now stored as an string. The
   existing GetChainID() function will return just the first character
   of the chain ID. We encourage users to switch to use GetExtChainID()
   which will return the string.

   .. seealso::

      * :oe:func:`OEChem::OEHasResidue` function
      * :oe:func:`OEChem::OEAtomGetResidue` function
      * :oe:func:`OEChem::OEAtomSetResidue` function

   .. note::

      See section :ref:`section_biopolymer_residues` for a detailed description
      of the data stored in an :ref:`OEResidue <OEChem_OEResidue>`.

   .. oe:method:: Constructors

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

         .. oe:api::

            OEResidue()

      .. oe:language:: python

         .. oe:api:: python

            OEResidue() -> OEResidue

      Default constructor.

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

         .. oe:api::

            OEResidue(const OEResidue& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OEResidue(rhs: OEResidue) -> OEResidue

      Copy constructor.

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

      .. oe:api::

         OEResidue &operator=(const OEResidue &rhs)

      Assignment operator that copies the data of the 'rhs' :ref:`OEResidue <OEChem_OEResidue>` object
      into the right-hand side :ref:`OEResidue <OEChem_OEResidue>` object.

      Assignment operator.


   .. oe:method:: operator bool

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

         .. oe:api::

            operator bool() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool


      Determines whether any field of an :ref:`OEResidue <OEChem_OEResidue>`
      has a non-default value.

   .. oe:language:: c++

      .. oe:method:: Comparison Operators

         .. oe:api::

            bool operator==(const OEResidue& rhs) const
            bool operator!=(const OEResidue& rhs) const
            bool operator<(const OEResidue& rhs) const
            bool operator<=(const OEResidue& rhs) const
            bool operator>(const OEResidue& rhs) const
            bool operator>=(const OEResidue& rhs) const

         The comparison operators compare properties of two
         :oe:cls:`OEResidue<OEChem::OEResidue>` objects.
         Two residues are considered equal if all their properties are equal.
         The <, <=, >, and >= operators consider the residue properties in
         the following order: model number, chain ID, fragment number,
         residue number, insertion code, and residue name.

         Because of the existence of the < operator, it is possible to sort
         containers by residue, and also to create std::map containers using
         :oe:cls:`OEResidue<OEChem::OEResidue>` as a key.  The residue sorting
         order produced by the < operator is the same as that produced by
         :oe:func:`OEPDBOrderAtoms<OEChem::OEPDBOrderAtoms>`.

   .. oe:method:: GetAlternateLocation

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

         .. oe:api::

            char GetAlternateLocation() const

      .. oe:language:: python

         .. oe:api:: python

            GetAlternateLocation() -> str

      Returns the 'alternate location' property of an atom in a
      residue. The 'alternate location' property may be set using the
      :oe:meth:`OEChem::OEResidue::SetAlternateLocation` method.

   .. oe:method:: GetBFactor

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

         .. oe:api::

            float GetBFactor() const

      .. oe:language:: python

         .. oe:api:: python

            GetBFactor() -> float

      Returns the crystallographic 'b-factor' property of an atom in a
      residue. The 'b-factor' property may be set using the
      :oe:meth:`OEChem::OEResidue::SetBFactor` method.

      .. seealso::

         * :ref:`OEHasAnisou <OEChem_OEHasAnisou>`
         * :oe:func:`OEChem::OEGetAnisou`
         * :oe:func:`OEChem::OESetAnisou`

   .. oe:method:: GetChainID

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

         .. oe:api::

            char GetChainID() const

      .. oe:language:: python

         .. oe:api:: python

            GetChainID() -> str

      This method is deprecated and should no longer be used.
      Instead, use :oe:meth:`OEChem::OEResidue::GetExtChainID`.
      Returns the first character of the 'chain identifier' property
      of the residue. The 'chain identifier' property may be set using
      the :oe:meth:`OEChem::OEResidue::SetExtChainID` method.

   .. oe:method:: GetExtChainID

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

         .. oe:api::

            string GetExtChainID() const

      .. oe:language:: python

         .. oe:api:: python

            GetExtChainID() -> str

      Returns the 'chain identifier' property of the residue.
      The 'chain identifier' property may be set using
      the :oe:meth:`OEChem::OEResidue::SetExtChainID` method.
      If reading from mmCIF, this property is ``auth_asym_id`` field from the mmCIF spec.

   .. oe:method:: GetSubChainID

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

         .. oe:api::

            string GetSubChainID() const

      .. oe:language:: python

         .. oe:api:: python

            GetSubChainID() -> str

      Returns the 'subchain identifier' property
      of the residue. The 'subchain identifier' property may be set using
      the :oe:meth:`OEChem::OEResidue::SetSubChainID` method.
      When reading from PDB, this is default to a space character. When reading from
      mmCIF, these are now a further subdivision of the chain identifier based on connected
      components. If reading from mmCIF, this property is ``label_asym_id`` field from the mmCIF spec.

   .. oe:method:: GetFragmentNumber

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

         .. oe:api::

            int GetFragmentNumber() const

      .. oe:language:: python

         .. oe:api:: python

            GetFragmentNumber() -> int

      Returns the 'fragment number' property of a residue. Fragment
      numbers are integer indices that define connected components of
      a macromolecule.
      When reading from a PDB file, the first atom is placed in
      fragment number ``1``.
      Each time a `TER`_, `END`_ or `ENDM`_ record is encountered
      within a single connection table, the fragment number is
      incremented.
      Similarly, when writing a PDB file, a `TER`_ record is written
      between any consecutive pair of atoms with different fragment
      numbers.
      The fragment number property may be set using the
      :oe:meth:`OEChem::OEResidue::SetFragmentNumber` number property.

   .. oe:method:: GetInsertCode

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

         .. oe:api::

            char GetInsertCode() const

      .. oe:language:: python

         .. oe:api:: python

            GetInsertCode() -> str

      Returns the 'insertion code' of a residue.
      Insertion codes are single character suffixes used to
      distinguish insertions when using a standardized residue
      numbering system.
      By default, this property contains a single space character, ``' '``.
      The insertion code property of a residue may be set using the
      :oe:meth:`OEChem::OEResidue::SetInsertCode` method.

   .. oe:method:: GetModelNumber

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

         .. oe:api::

            int GetModelNumber() const

      .. oe:language:: python

         .. oe:api:: python

            GetModelNumber() -> int


      Returns the 'model number' property of a residue. For NMR or
      molecular dynamics files, the model number contains the index of
      the NMR model or dynamics time-step within a file.
      When reading from mmCIF, the model numbers start from 1.
      The 'model number' property may be set using the
      :oe:meth:`OEChem::OEResidue::SetModelNumber` method.

   .. oe:method:: GetName

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

         .. oe:api::

            const char* GetName() const

      .. oe:language:: python

         .. oe:api:: python

            GetName() -> str

      Returns the 'residue name' property of a residue. The 'residue
      name' property may be set using the
      :oe:meth:`OEChem::OEResidue::SetName` method.

   .. oe:method:: GetOccupancy

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

         .. oe:api::

            float GetOccupancy() const

      .. oe:language:: python

         .. oe:api:: python

            GetOccupancy() -> float

      Returns the crystallographic 'occupancy' property of an atom in
      a residue. The default value is ``1.0``. The 'occupancy'
      property may be set using the
      :oe:meth:`OEChem::OEResidue::SetOccupancy` method.

   .. oe:method:: GetResidueNumber

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

         .. oe:api::

            int GetResidueNumber() const

      .. oe:language:: python

         .. oe:api:: python

            GetResidueNumber() -> int

      Returns the 'residue number' property of a residue. The 'residue
      number' property may be set using the
      :oe:meth:`OEChem::OEResidue::SetResidueNumber` method.

   .. oe:method:: GetEntityID

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

         .. oe:api::

            string GetEntityID() const

      .. oe:language:: python

         .. oe:api:: python

            GetEntityID() -> str

      Returns the 'entity ID' property of a residue. The 'entity ID' 
      property may be set using the
      :oe:meth:`OEChem::OEResidue::SetEntityID` method.

   .. oe:method:: GetSequenceID

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

         .. oe:api::

            int GetSequenceID() const

      .. oe:language:: python

         .. oe:api:: python

            GetSequenceID() -> int

      Returns the 'sequence id' property of a residue, if set by reading an mmCIF file. The 'sequence
      id' property may be set using the :oe:meth:`OEChem::OEResidue::SetSequenceID` method.
      The number of typically sequential starting from 1, contrary to the
      'residue number' which typically follows the biological sequence numbering.
      If reading from mmCIF, this property is ``label_seq_id`` field from the mmCIF spec.

   .. oe:method:: GetSecondaryStructure

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

         .. oe:api::

            int GetSecondaryStructure() const

      .. oe:language:: python

         .. oe:api:: python

            GetSecondaryStructure() -> int

      Returns the protein 'secondary structure'  property of a
      residue.
      The default value is zero.
      The 'secondary structure' property of a residue may be set using
      the :oe:meth:`OEChem::OEResidue::SetSecondaryStructure` method.

   .. oe:method:: GetSerialNumber

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

         .. oe:api::

            int GetSerialNumber() const

      .. oe:language:: python

         .. oe:api:: python

            GetSerialNumber() -> int

      Returns the 'atom serial number' property of an atom in a
      residue. The 'atom serial number' property may be set using the
      :oe:meth:`OEChem::OEResidue::SetSerialNumber` method.

   .. oe:method:: IsHetAtom

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

         .. oe:api::

            bool IsHetAtom() const

      .. oe:language:: python

         .. oe:api:: python

            IsHetAtom() -> bool

      Returns the 'hetero atom' property of an atom in a residue.
      The 'hetero atom' property may be set using the
      :oe:meth:`OEChem::OEResidue::SetHetAtom` method.

      .. note::

         A 'hetero atom' is distinguished from a 'standard atom' in a PDB file
         by using the record type ``HETATM`` rather than ``ATOM``.

   .. oe:method:: SetAlternateLocation

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

         .. oe:api::

            bool SetAlternateLocation(char v)

      .. oe:language:: python

         .. oe:api:: python

            SetAlternateLocation(v: str) -> bool

      Sets the 'alternate location' property of an atom in a residue.
      The default value is a space character.
      The 'alternate location' property of an atom in a residue may be
      retrieved using the
      :oe:meth:`OEChem::OEResidue::GetAlternateLocation` method.

   .. oe:method:: SetBFactor

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

         .. oe:api::

            bool SetBFactor(float v)

      .. oe:language:: python

         .. oe:api:: python

            SetBFactor(v: float) -> bool

      Sets the crystallographic 'b-factor' property of an atom in a residue.
      The default value is ``0.0``.
      The 'b-factor' property of an atom in a residue may be retrieved
      using the :oe:meth:`OEChem::OEResidue::GetBFactor` method.

      .. seealso::

         * :ref:`OEHasAnisou <OEChem_OEHasAnisou>`
         * :oe:func:`OEChem::OESetAnisou`
         * :oe:func:`OEChem::OEGetAnisou`

   .. oe:method:: SetChainID

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

         .. oe:api::

            bool SetChainID(char v)

      .. oe:language:: python

         .. oe:api:: python

            SetChainID(v: str) -> bool

      This method is deprecated and should no longer be used. Instead, use :oe:meth:`OEChem::OEResidue::SetExtChainID`.
      Sets the 'chain identifier' property of a residue.
      This sets the same property as :oe:meth:`OEChem::OEResidue::SetExtChainID`
      The default value is a space character. The 'chain identifier' property of a residue may be retrieved
      using the :oe:meth:`OEChem::OEResidue::GetExtChainID` method.

   .. oe:method:: SetExtChainID

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

         .. oe:api::

            bool SetExtChainID(const string &)

      .. oe:language:: python

         .. oe:api:: python

            SetExtChainID(v: str) -> bool

      Sets the 'chain identifier' property of a residue.
      The default value is a space character. The 'chain identifier' property of a residue may be retrieved
      using the :oe:meth:`OEChem::OEResidue::GetExtChainID` method.

   .. oe:method:: SetSubChainID

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

         .. oe:api::

            bool SetSubChainID(const string &)

      .. oe:language:: python

         .. oe:api:: python

            SetSubChainID(v: str) -> bool

      Sets the 'subchain identifier' property of a residue.
      The default value is a space character. The 'subchain identifier' property of a residue may be retrieved
      using the :oe:meth:`OEChem::OEResidue::GetSubChainID` method.

   .. oe:method:: SetFragmentNumber

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

         .. oe:api::

            bool SetFragmentNumber(int v)

      .. oe:language:: python

         .. oe:api:: python

            SetFragmentNumber(v: int) -> bool

      Sets the fragment number property of a residue.
      Fragment numbers are integer indices that define the connected
      components of a macromolecule.
      When reading from a PDB file, the first atom is placed in
      fragment number ``1``.
      Each time a `TER`_, `END`_ or `ENDM`_ record is encountered
      within a single connection table, the fragment number is
      incremented.
      Similarly, when writing a PDB file, a `TER`_ record is written
      between any consecutive pair of atoms with different fragment
      numbers.
      When reading from an mmCIF file, this number is read directly
      from the input as it is defined in that file spec.
      The default value is zero.
      The 'fragment number' property of a residue may be retrieved
      using the :oe:meth:`OEChem::OEResidue::GetFragmentNumber` method.

   .. oe:method:: SetHetAtom

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

         .. oe:api::

            bool SetHetAtom(bool v)

      .. oe:language:: python

         .. oe:api:: python

            SetHetAtom(v: bool) -> bool

      Set the 'hetero atom' property of an atom in a residue.
      The default value is ``false``.
      The 'hetero atom' property of an atom in a residue may be
      retrieved using the :oe:meth:`OEChem::OEResidue::IsHetAtom`
      method.

   .. oe:method:: SetInsertCode

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

         .. oe:api::

            bool SetInsertCode(char v)

      .. oe:language:: python

         .. oe:api:: python

            SetInsertCode(v: str) -> bool

      Sets the 'insertion code' of a residue.
      Insertion codes are single character suffices used to
      distinguish insertions when using a standardized residue
      numbering system.
      By default, this property contains a single space character ``' '``.
      The 'insertion code' property of a residue may be retrieved using
      the :oe:meth:`OEChem::OEResidue::GetInsertCode` method.

   .. oe:method:: SetModelNumber

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

         .. oe:api::

            bool SetModelNumber(int v)

      .. oe:language:: python

         .. oe:api:: python

            SetModelNumber(v: int) -> bool

      Sets the `model number` property of a residue.
      For NMR or molecular dynamics files, the model number contains
      the index of the NMR model or dynamics time-step within a file.
      The default value is 0.
      The 'model number' property of a residue may be retrieved using
      the :oe:meth:`OEChem::OEResidue::GetModelNumber` method.

   .. oe:method:: SetName

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

         .. oe:api::

            bool SetName(const char* v)
            bool SetName(const std::string& v)

      .. oe:language:: python

         .. oe:api:: python

            SetName(v: str) -> bool

      Sets the 'residue name' property of a residue.
      The default value is ``MOL``.
      The 'residue name' property of a residue may be retrieved using
      the :oe:meth:`OEChem::OEResidue::GetName` method.

   .. oe:method:: SetOccupancy

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

         .. oe:api::

            bool SetOccupancy(float v)

      .. oe:language:: python

         .. oe:api:: python

            SetOccupancy(v: float) -> bool

      Sets the crystallographic 'occupancy' property of an atom in a residue.
      The default value is ``1.0``.
      The 'occupancy' property of an atom in a molecule may be
      retrieved using the :oe:meth:`OEChem::OEResidue::GetOccupancy`
      method.

   .. oe:method:: SetResidueNumber

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

         .. oe:api::

            bool SetResidueNumber(int v)

      .. oe:language:: python

         .. oe:api:: python

            SetResidueNumber(v: int) -> bool

      Sets the 'residue number' property of a residue.
      The default value is ``1``.
      The 'residue number' property of a residue may be retrieved
      using the :oe:meth:`OEChem::OEResidue::GetResidueNumber` method.

   .. oe:method:: SetEntityID

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

         .. oe:api::

            bool SetEntityID(const string &)

      .. oe:language:: python

         .. oe:api:: python

            SetEntityID(v: str) -> bool

      Sets the 'Entity ID' property of a residue.
      The default value is a single space character, ``' '``.
      The 'Entity ID' property of a residue may be retrieved
      using the :oe:meth:`OEChem::OEResidue::GetEntityID` method.

   .. oe:method:: SetSequenceID

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

         .. oe:api::

            bool SetSequenceID(int v)

      .. oe:language:: python

         .. oe:api:: python

            SetSequenceID(v: int) -> bool

      Sets the 'sequence id' property of a residue.
      The default value is ``-1``.
      The 'sequence id' property of a residue may be retrieved
      using the :oe:meth:`OEChem::OEResidue::GetSequenceID` method.

   .. oe:method:: SetSecondaryStructure

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

         .. oe:api::

            bool SetSecondaryStructure(int v)

      .. oe:language:: python

         .. oe:api:: python

            SetSecondaryStructure(v: int) -> bool

      Sets the protein 'secondary structure' property of a residue.
      The default value is 0.
      The 'secondary structure' property of a residue may be retrieved
      using the :oe:meth:`OEChem::OEResidue::GetSecondaryStructure`
      method.

   .. oe:method:: SetSerialNumber

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

         .. oe:api::

            bool SetSerialNumber(int v)

      .. oe:language:: python

         .. oe:api:: python

            SetSerialNumber(v: int) -> bool

      Sets the 'atom serial number' property of an atom in a residue.
      The default value is 0.
      The 'atom serial number' property may be retrieved using the
      :oe:meth:`OEChem::OEResidue::GetSerialNumber` method.
