.. include:: ../../common/cookbook/cookbook-hyperlinks

.. oe:namespace:: OEGrapheme

.. meta::
   :keywords: OEDrawResidues

.. _OEGrapheme_OEDrawResidues:

.. oe:function:: OEDrawResidues

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

      .. oe:api::

         bool OEDrawResidues(OEDepict::OEImageBase& image,
                             const OEChem::OEMolBase& mol,
                             const bool interactive = false)

   .. oe:language:: python

      .. oe:api:: python

         OEDrawResidues(image: OEImageBase,
                        mol: Union[OEGraphMol,OEMol,OEQMol],
                        interactive: bool = False) -> bool

   The :oe:func:`OEGrapheme::OEDrawResidues` function depicts the residue graph of a molecule
   with up to 300 heavy atoms.
   It is recommended to use when a molecule is imported from a :file:`PDB` file that automatically assigns
   residues (:oe:cls:`OEChem::OEResidue`) to each atom.

   *image*
     The image on which the molecule is drawn.

   *mol*
      The molecule being depicted.

   *interactive*
      The parameter that determines whether the generated image will be interactive
      (only available for :file:`SVG`` images) revealing the residue on mouse hover.

   .. note::

      The :oe:func:`OEGrapheme::OEDrawResidues` does not support
      visualizing large proteins. The number of heavy atoms is limited to 250.

   **Example:**

   The following code snippet shows how to use the :oe:func:`OEGrapheme::OEDrawResidues`
   function to generate an interactive SVG image. The image created is shown in
   :ref:`Figure: Example of using the OEDrawResidues function <figure_draw_residues>`.
   If the molecule has no residue information, if the :ref:`OEHasResidues <OEChem_OEHasResidues>`
   function returns ``false``, then a warning will be throw and no image will be generated.

   .. oe:source:: DrawResidues.py
      :language: python
      :noindent:
      :frag:     SNIPPET-DRAW-RESIDUES

   .. oe:source:: DrawResidues.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-DRAW-RESIDUES

   The :oe:func:`OEGrapheme::OEDrawResidues` function allows the visualization of nonstandard
   amino acids. Nonstandard amino acid residues are represented with a black jagged circle
   with the residue labels shown at the center.

   .. _figure_draw_residues:

   .. only:: oehtml

      .. raw:: html

         <p align="center">
         <b>hover mouse over any residue circles</b>
         </p>

         <p align="center">
         <object data="../../_images/DrawResidues.svg" type="image/svg+xml"  width = "500" ></object>
         <p>

         <p align="center">
         <b>Example of using the OEDrawResidues function to generate an interactive SVG image</b>
         <p>

      .. image:: ../images/DrawResidues.svg
         :width: 1pt

   .. only:: oepdf

      .. figure:: ../images/DrawResidues.*
         :align:  center

         **Example of using the OEDrawResidues function**

   .. note::

      This `interactive` functionality is **only available** for :file:`.svg`
      image format.

      The generated :file:`svg` image should be included into and
      HTML page with the SVG MIME type.

      .. code-block:: console

         <object data="<imagename>.svg" type="image/svg+xml"></object>

   .. seealso::

      * :oe:func:`OEGrapheme::OEDrawPeptide` function to depict a peptide with standard amino acids
      * :oe:func:`OEGrapheme::OEDrawMonomerGraph` and :oe:func:`OEGrapheme::OEHighlightMonomers` functions to depict molecules initialized from HELM
      * :ref:`chapter_svg` chapter in **OEDepict TK** manual
