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

.. oe:namespace:: OESpruce

..  _OESpruce_OEMutateResidue:

.. oe:function:: OEMutateResidue

   .. attention::

      |TWOLANGUAGE|

   This function mutates a single standard protein residue in the molecule to another standard amino acid residue
   specified by the 3 letter residue name, it currently only supports the 20 standard amino acids.
   The function works by deleting the residue sidechain and rebuilds the new residue using the :oe:func:`OESpruce::OEBuildSidechains`
   function, but only building the mutated sidechain. The sidechain re-building
   can be controlled using the :ref:`OESidechainBuilderOptions <OESpruce_OESidechainBuilderOptions>` options class argument `opts`.

   .. note::

      Explicit hydrogens are not added to the structure during the build processes, therefore no partial charges are assigned. 

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

      .. oe:api::

         bool OEMutateResidue(OEChem::OEMolBase& mol,
                              const OEChem::OEResidue& res,
                              const std::string newResName,
                              const OESpruce::OESidechainBuilderOptions& opts = OESpruce::OESidechainBuilderOptions(true))

   .. oe:language:: python

      .. oe:api:: python

         OEMutateResidue(mol: Union[OEGraphMol,OEMol,OEQMol], res: OEResidue,
                         newResName: str,
                         opts: OESidechainBuilderOptions = OESidechainBuilderOptions(true)) -> bool

   .. oe:api: IGNORE

       bool OEMutateResidue(OEBio::OEDesignUnit& du,
                            const OEChem::OEResidue& res,
                            const std::string newResName,
                            const OESpruce::OESidechainBuilderOptions& opts=OESpruce::OESidechainBuilderOptions(true))

   .. seealso::

      * :oe:func:`OESpruce::OEBuildSidechains` function
      * :ref:`OESidechainBuilderOptions <OESpruce_OESidechainBuilderOptions>` class
