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

.. oe:namespace:: OEBio

.. meta::
   :keywords: OERamachandranAnalysis, Ramachandran


.. _OEBio_OERamachandranAnalysis:

.. oe:class:: OERamachandranAnalysis

   .. oe:api::

      class OERamachandranAnalysis

   This class represents an :ref:`OERamachandranAnalysis <OEBio_OERamachandranAnalysis>`, which holds
   information about the backbone conformation, of a protein residue,
   which can be used for plotting a Ramachandran plot.  A
   Ramachandran plot, is a plot of the protein backbone :math:`\phi`
   and :math:`\psi` angles of an amino acid residue, on the x- and
   y-axis, respectively.  The diagram was originally developed in
   1963 by G. N. Ramachandran [Ramachandran-1963]_ to visualizes
   energetically accessible regions of protein conformational space.
   Initially, there was a single plot used for all standard amino
   acid residues, but recent work has been done on certain residue
   types that do not follow the general pattern [Lovell-2003]_
   [Chen-2010]_ [Hintze-2016]_, specifically new diagrams have been
   derived for: glycine, isoleucine and valine, cis-proline,
   trans-proline, and for residues preceding proline residues, since
   their backbone conformational space is affected by the following
   proline residue. The data was extracted from the open-source 
   Computational Crystallography Toolbox (CCTBX) [Grosse-Kunstleve-2002]_.

   .. note::

      The function expects alternate conformations of the protein to be collapsed,
      meaning only a single alternate conformation should
      exist in the molecule object

   The following is an example of determining the Ramachandran classification for each standard residue in a protein:

   #. Read in a PDB and collapse the alternate conformations (if present). See chapter :ref:`spruce_read_pdb_section` in **Spruce TK**.

   #. Loop over the CA atoms in the protein molecule. Alternatively, (not shown) loop over the residues in the protein.

   #. For each CA atom or residue construct the :ref:`OERamachandranAnalysis <OEBio_OERamachandranAnalysis>`

   #. Print out information about outliers for further analysis

   .. oe:source:: RamaOutlierCheck.py
      :language: python
      :refnum:   1
      :caption:  Example of Ramachandran outlier analysis
      :frag:     SNIPPET-RAMA-OUTLIER-CHECK

   .. oe:source:: RamaOutlierCheck.cpp
      :language: c++
      :refnum:   1
      :caption:  Example of Ramachandran outlier analysis
      :frag:     SNIPPET-RAMA-OUTLIER-CHECK

   .. oe:source:: RamaOutlierCheck.java
      :language: java
      :refnum:   1
      :caption:  Example of Ramachandran outlier analysis
      :frag:     SNIPPET-RAMA-OUTLIER-CHECK

   .. oe:source:: RamaOutlierCheck.cs
      :language: csharp
      :refnum:   1
      :caption:  Example of Ramachandran outlier analysis
      :frag:     SNIPPET-RAMA-OUTLIER-CHECK

   .. seealso:: 

      * :oe:constns:`OEBio::OERamaCategory` namespace
      * :oe:constns:`OEBio::OERamaType` namespace
      * :oe:func:`OEGrapheme::OERenderRamachandranPlot` function in **Grapheme TK** to visualize Ramachandran plots

   .. only:: oehtml

      .. raw:: html

         <p align="center">
         <object data="../../_images/RenderRamachandranPlot-General.svg" type="image/svg+xml"  width = "350" ></object>
         <p>

         <p align="center">
         <b>Example of Grapeheme TK visualization of Ramachandran plot</b>
         <p>

   .. only:: oepdf

      |NOPDFIMAGE|

   .. oe:method:: Constructors

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

         .. oe:api::

            OERamachandranAnalysis(const OEChem::OEAtomBase* atom)

      .. oe:language:: python

         .. oe:api:: python

            OERamachandranAnalysis(atom: OEAtomBase) -> OERamachandranAnalysis

      The atom based constructor accepts any atom of a given amino
      acid residue and returns an
      :ref:`OERamachandranAnalysis <OEBio_OERamachandranAnalysis>`.  While any atom from
      a residue is acceptable, it is advised to loop over the
      protein atoms with a predicate selecting e.g. only CA atoms,
      as this ensures the analysis is only done once per residue.
      The molecule must have 3D coordinates assigned.
      See code example above.

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

         .. oe:api::

            OERamachandranAnalysis(const OEHierResidue& res)
            OERamachandranAnalysis(const OEChem::OEMolBase& mol,
                                   const OEChem::OEResidue& res)

      .. oe:language:: python

         .. oe:api:: python

            OERamachandranAnalysis(res: OEHierResidue) -> OERamachandranAnalysis
            OERamachandranAnalysis(mol: Union[OEGraphMol,OEMol,OEQMol],
                                   res: OEResidue) -> OERamachandranAnalysis

      Residue based constructors. These constructors, like the atom
      based one, use :oe:func:`OEGetTorsion<OEBio::OEGetTorsion>`,
      to determine the :math:`\phi`, :math:`\psi`, and
      :math:`\omega` dihedrals angles. The dihedral is used to
      differentiate Cis/Trans proline.
      The molecule must have 3D coordinates assigned.

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

         .. oe:api::

            OERamachandranAnalysis(double phi, double psi,
                                   const unsigned int ramaType)

      .. oe:language:: python

         .. oe:api:: python

            OERamachandranAnalysis(phi: float, psi: float, ramaType: int) -> OERamachandranAnalysis

      Constructor that determines the Ramachandran category based on
      raw data, where the user specifies which underlying
      Ramachandran plot to use, by specifying the type using the
      :oe:constns:`OEBio::OERamaType` namespace.

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

         .. oe:api::

            OERamachandranAnalysis(const OERamachandranAnalysis& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OERamachandranAnalysis(arg2: OERamachandranAnalysis) -> OERamachandranAnalysis

      Copy constructor.

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

      .. oe:api::

         OERamachandranAnalysis & operator=(const OERamachandranAnalysis &)

      Assignment operator.


   .. oe:method:: GetPhi

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

         .. oe:api::

            double GetPhi() const

      .. oe:language:: python

         .. oe:api:: python

            GetPhi() -> float

      Returns the value of the backbone :math:`\phi` dihedral angle used to evaluate the score, in radians.

   .. oe:method:: GetPsi

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

         .. oe:api::

            double GetPsi() const

      .. oe:language:: python

         .. oe:api:: python

            GetPsi() -> float

      Returns the value of the backbone :math:`\psi` dihedral angle used to evaluate the score, in radians.

   .. oe:method:: GetRamaCategory

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

         .. oe:api::

            unsigned int GetRamaCategory() const

      .. oe:language:: python

         .. oe:api:: python

            GetRamaCategory() -> int

      Returns a value corresponding to the classification for the
      residue from the :oe:constns:`OEBio::OERamaCategory`
      namespace.


   .. oe:method:: GetRamaScore

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

         .. oe:api::

            double GetRamaScore() const

      .. oe:language:: python

         .. oe:api:: python

            GetRamaScore() -> float

      Returns the value of the residue's Ramachandran score, which
      is a score relative to contours of expected Ramachandran
      behavior.

   .. oe:method:: GetRamaType

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

         .. oe:api::

            unsigned int GetRamaType() const

      .. oe:language:: python

         .. oe:api:: python

            GetRamaType() -> int

      Returns a value corresponding to the
      :oe:constns:`OEBio::OERamaCategory` namespace of the type
      of Ramachandran plot data used to determine the classification.
