.. oe:namespace:: OEBio

.. meta::
   :keywords: OEAtomMatchResidue, AtomMatchResidue


.. _OEBio_OEAtomMatchResidue:

.. oe:class:: OEAtomMatchResidue

   .. oe:api::

      class OEAtomMatchResidue : public OESystem::OEUnaryPredicate<OEChem::OEAtomBase>

   This class represents :ref:`OEAtomMatchResidue <OEBio_OEAtomMatchResidue>` functor
   that identifies atoms (:ref:`OEAtomBase <OEChem_OEAtomBase>`) in residues
   (:oe:cls:`OEResidue<OEChem::OEResidue>`) matching specific pieces, like residue name,
   residue number, insertion code, chain ID, and fragment number.

   .. seealso::

      * :ref:`section_predicates_reside_data_functors` section
      * :ref:`OEAtomMatchResidueID <OEBio_OEAtomMatchResidueID>` class

   The following methods are publicly inherited from :ref:`OEUnaryPredicate <OESystem_OEUnaryPredicate>`:

   ============================================================================== ============================================================================== ===============================================================================
   :oe:meth:`operator()<OESystem::OEUnaryPredicate::operator()>`                  :oe:meth:`CreateCopy<OESystem::OEUnaryPredicate::CreateCopy>`                  :oe:meth:`CreatePredicateCopy<OESystem::OEUnaryPredicate::CreatePredicateCopy>`
   ============================================================================== ============================================================================== ===============================================================================

   The following methods are publicly inherited from :ref:`OEUnaryFunction <OESystem_OEUnaryFunction>`:

   ============================================================ ============================================================ ===========================================================
   :oe:meth:`operator()<OESystem::OEUnaryFunction::operator()>` :oe:meth:`CreateCopy<OESystem::OEUnaryFunction::CreateCopy>`
   ============================================================ ============================================================ ===========================================================

   .. oe:method:: Constructors

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

         .. oe:api::

            OEAtomMatchResidue(const std::string& resId)
            OEAtomMatchResidue(const std::vector<std::string>& resIds)
            OEAtomMatchResidue(const OEAtomMatchResidueID& resId)
            OEAtomMatchResidue(const std::vector<OEAtomMatchResidueID>& resIds)
            OEAtomMatchResidue(const OEChem::OEResidue& resId)
            OEAtomMatchResidue(const std::vector<OEChem::OEResidue>& resIds)

      .. oe:language:: python

         .. oe:api:: python

            OEAtomMatchResidue(resIds: OEAtomMatchResidueIDVector) -> OEAtomMatchResidue
            OEAtomMatchResidue(resId: OEAtomMatchResidueID) -> OEAtomMatchResidue
            OEAtomMatchResidue(resIds: OEResidueVector) -> OEAtomMatchResidue
            OEAtomMatchResidue(resId: OEResidue) -> OEAtomMatchResidue
            OEAtomMatchResidue(resIds: OEStringVector) -> OEAtomMatchResidue
            OEAtomMatchResidue(resId: str) -> OEAtomMatchResidue

      Constructs the functor with the residue properties specified by a regex string, 
      an :ref:`OEAtomMatchResidueID <OEBio_OEAtomMatchResidueID>` or a vector of those, an OEResidue, or a vector of those.

      .. oe:api: # IGNORE FOR DOCUMENTATION

         OEAtomMatchResidue(const std::vector<std::string>& resIds);

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

         .. oe:api::

            OEAtomMatchResidue(const OEChem::OEMolBase& molA,
                               const OEChem::OEMolBase& molB,
                               const double dist, bool excludeHydrogens = true)

      .. oe:language:: python

         .. oe:api:: python

            OEAtomMatchResidue(protein: Union[OEGraphMol,OEMol,OEQMol],
                               ligand: Union[OEGraphMol,OEMol,OEQMol],
                               dist: float, excludeHydrogens: bool = True) -> OEAtomMatchResidue

      Constructs the functor to match the complete residues in `molA` that are within the specific distance `dist` in `molB`.
      An option exists to exclude explicit hydrogens to be considered inside the distance threshold, which is on by default.

   .. oe:method:: operator()

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

         .. oe:api::

            bool operator()(const OEAtomBase& atom) const

      .. oe:language:: python

         .. oe:api:: python

            __call__(atom: OEAtomBase) -> bool

      Returns ``true``, if the residue of the atom (returned by the
      :oe:func:`OEChem::OEAtomGetResidue` function) has equivalent
      residue properties (i.e. residue name, residue number, insertion
      code, chain ID, and fragment number) with which the functor is
      constructed.

   .. oe:method:: CreateCopy

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

         .. oe:api::

            OESystem::OEUnaryFunction<OEChem::OEAtomBase , bool>* CreateCopy() const

      .. oe:language:: python

         .. oe:api:: python

            CreateCopy() -> OEAtomMatchResidue

      Deep copy constructor that returns a copy of the object.
      The memory for the returned :ref:`OEAtomMatchResidue <OEBio_OEAtomMatchResidue>`
      object is dynamically allocated and owned by the caller.

      .. oe:language:: c++

         The returned copy should be deallocated using C++
         delete operator in order to prevent a memory leak.

   **Examples**

   The examples below demonstrate how to create various predicates that allow to access atoms
   based on their residue information.

   .. oe:source:: AtomMatchResidue.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OEAtomMatchResidue

   .. oe:source:: AtomMatchResidue.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OEAtomMatchResidue

   .. oe:source:: AtomMatchResidue.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OEAtomMatchResidue

   .. oe:source:: AtomMatchResidue.cs
      :language: cs
      :noindent:
      :frag:     SNIPPET-OEAtomMatchResidue
