.. _chapter_predicates:

********************************************************************************
Predicate Functors
********************************************************************************

.. oe:language:: c++

   A *functor* (function object) is simply any object that can be called as if it is a
   function *i.e.* an object of a class that overload ``operator()`` the function call
   operator.
   A functor can be considered as a C++ equivalent of function pointers in C.
   However, functors can also maintain state, be copied, created and destroyed.

.. oe:language:: python

   A *functor* (function object) is simply any object that can be called as if it is a
   function *i.e.* an object of a class that defines the ``__call__()`` method.

Functors that return bool are an important special case. A unary function
whose return type is bool is called a *predicate*.

In **OEChem TK**, these functors are often passed into another function.
The functors are then called from inside the second
function. This is the concept of a *callback*, because the second
function provides the argument and 'call's back' to the functor which
was passed into the function.
Generator method such as :oe:meth:`OEChem::OEMolBase::GetAtoms` can take a functor
as an argument and use the callback mechanism to iterate over
atoms that satisfy the functor passed to it.
See example in :ref:`section_atombondtraversal_subset` section.

In the example below, the function ``CountAtoms`` loops over the atoms
and performs a call-back to the predicate functor ``pred`` for each
atom. If the predicate returns true, a counter is incremented.
The ``main`` function passes :ref:`OEIsOxygen <OEChem_OEIsOxygen>` predefined atom predicates
to the ``CountAtoms`` function that  counts the number of oxygen atoms in the molecule.
(Please note that this function is already implemented in **OEChem TK** and called
:oe:func:`OEChem::OECount`.)

.. oe:source:: Functors.cpp
   :language: c++
   :refnum:   1
   :caption:  Using functor callbacks
   :frag:     SNIPPET

.. oe:source:: Functors.py
   :language: python
   :refnum:   1
   :caption:  Using functor callbacks
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-Functors.py>`



.. oe:source:: Functors.java
   :language: java
   :refnum:   1
   :caption:  Using functor callbacks
   :frag:     SNIPPET

.. oe:source:: Functors.cs
   :language: csharp
   :refnum:   1
   :caption:  Using functor callbacks
   :frag:     SNIPPET

.. _section_predicates_builtin:

Built-in Functors
================================================================================

There are many useful functors already defined in **OEChem TK**.  These can
be used by programmers with little or no understanding of the details
of how functors work. A programmer can simply pass them to one of the
many **OEChem TK** functions and methods which take predicates as arguments.

.. _section_predicates_builtin_atom:

Atom Functors
--------------------------------------------------------------------------------

.. table::

   =================================================== =====================================================================
   Access                                              Functor Name
   =================================================== =====================================================================
   ring atoms                                          :oe:cls:`OEAtomIsInRing<OEChem::OEAtomIsInRing>`
   chain atoms                                         :oe:cls:`OEAtomIsInChain<OEChem::OEAtomIsInChain>`
   atom with specified atom index                      :oe:cls:`OEHasAtomIdx<OEChem::OEHasIdx>`
   atom with selected  atom index                      :oe:cls:`OEAtomIdxSelected<OEChem::OEIdxSelected>`
   atom with specified atom name                       :oe:cls:`OEHasAtomName<OEChem::OEHasAtomName>`
   atoms with specified atom stereo                    :oe:cls:`OEHasAtomStereoSpecified<OEChem::OEHasAtomStereoSpecified>`
   atoms with specified formal charge                  :oe:cls:`OEHasFormalCharge<OEChem::OEHasFormalCharge>`
   atoms with specified number of heavy atom neighbors :oe:cls:`OEHasHvyDegree<OEChem::OEHasHvyDegree>`
   aromatic atoms                                      :oe:cls:`OEIsAromaticAtom<OEChem::OEIsAromaticAtom>`
   atoms with specific hybridization                   :oe:cls:`OEIsAtomHybridization<OEChem::OEIsAtomHybridization>`
   chiral atoms                                        :oe:cls:`OEIsChiralAtom<OEChem::OEIsChiralAtom>`
   atoms with anisotropic B-factor parameters          :oe:cls:`OEHasAnisou<OEChem::OEHasAnisou>`
   atoms with specified map index                      :oe:cls:`OEHasMapIdx<OEChem::OEHasMapIdx>`
   atoms representing R-Groups                         :oe:cls:`OEIsRGroup<OEChem::OEIsRGroup>`
   valid atoms (by OpenEye valence conventions)        :oe:cls:`OEIsValidAtomValence<OEChem::OEIsValidAtomValence>`
   valid atoms (by MDL valence conventions)            :oe:cls:`OEIsValidMDLAtomValence<OEChem::OEIsValidMDLAtomValence>`
   :math:`n^{th}` atom                                 :oe:cls:`OENthAtom<OEChem::OENthAtom>`
   atoms that are both terminal and heavy              :oe:cls:`OEIsTermHeavyAtom<OEChem::OEIsTermHeavyAtom>`
   atom membership in a set of atoms                   :ref:`OEIsAtomMember <OEChem_OEIsMemberPtr_OEIsAtomMember>`
   =================================================== =====================================================================

.. oe:source:: FunctorsAtom.cpp
   :language: c++
   :refnum:   2
   :caption:  Using predefined atom functors
   :frag:     SNIPPET

.. oe:source:: FunctorsAtom.py
   :language: python
   :refnum:   2
   :caption:  Using predefined atom functors
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-FunctorsAtom.py>`



.. oe:source:: FunctorsAtom.java
   :language: java
   :refnum:   2
   :caption:  Using predefined atom functors
   :frag:     SNIPPET

.. oe:source:: FunctorsAtom.cs
   :language: csharp
   :refnum:   2
   :caption:  Using predefined atom functors
   :frag:     SNIPPET

The output of the preceding program is the following:

.. code-block:: bash

   Number of heavy atoms = 12
   Number of ring atoms  = 11

Atomic Number Functors
--------------------------------------------------------------------------------

.. table::

   =================================== =====================================================================
   Access                              Functor Name
   =================================== =====================================================================
   atoms with specified atomic number  :oe:cls:`OEHasAtomicNum<OEChem::OEHasAtomicNum>`
   carbon atoms                        :oe:cls:`OEIsCarbon<OEChem::OEIsCarbon>`
   halogen atoms                       :oe:cls:`OEIsHalogen<OEChem::OEIsHalogen>`
   heavy atoms                         :oe:cls:`OEIsHeavy<OEChem::OEIsHeavy>`
   hetero atoms                        :oe:cls:`OEIsHetero<OEChem::OEIsHetero>`
   explicit hydrogen atoms             :oe:cls:`OEIsHydrogen<OEChem::OEIsHydrogen>`
   metal atoms                         :oe:cls:`OEIsMetal<OEChem::OEIsMetal>`
   nitrogen atoms                      :oe:cls:`OEIsNitrogen<OEChem::OEIsNitrogen>`
   oxygen atoms                        :oe:cls:`OEIsOxygen<OEChem::OEIsOxygen>`
   sulfur atoms                        :oe:cls:`OEIsSulfur<OEChem::OEIsSulfur>`
   phosphorus atoms                    :oe:cls:`OEIsPhosphorus<OEChem::OEIsPhosphorus>`
   non-carbon atoms                    :oe:cls:`OEIsPolar<OEChem::OEIsPolar>`
   polar hydrogen atoms                :oe:cls:`OEIsPolarHydrogen<OEChem::OEIsPolarHydrogen>`
   =================================== =====================================================================

Please note that the following two lines produce the same result.

.. oe:source:: FunctorsAtomic.cpp
   :language: c++
   :frag:     SNIPPET-PRED-ATOMIC

.. oe:source:: FunctorsAtomic.py
   :language: python
   :frag:     SNIPPET-PRED-ATOMIC

.. oe:source:: FunctorsAtomic.java
   :language: java
   :frag:     SNIPPET-PRED-ATOMIC

.. oe:source:: FunctorsAtomic.cs
   :language: csharp
   :frag:     SNIPPET-PRED-ATOMIC

Bond Functors
--------------------------------------------------------------------------------

.. table::

   =================================== =====================================================================
   Access                              Functor Name
   =================================== =====================================================================
   ring bonds                          :oe:cls:`OEBondIsInRing<OEChem::OEBondIsInRing>`
   chain bonds                         :oe:cls:`OEBondIsInChain<OEChem::OEBondIsInChain>`
   bond with specified bond index      :oe:cls:`OEHasBondIdx<OEChem::OEHasIdx>`
   bond with selected  bond index      :oe:cls:`OEBondIdxSelected<OEChem::OEIdxSelected>`
   bonds with specified bond order     :oe:cls:`OEHasOrder<OEChem::OEHasOrder>`
   rotatable bonds                     :oe:cls:`OEIsRotor<OEChem::OEIsRotor>`
   chiral bonds                        :oe:cls:`OEIsChiralBond<OEChem::OEIsChiralBond>`
   bonds with specific bond  stereo    :oe:cls:`OEHasBondStereoSpecified<OEChem::OEHasBondStereoSpecified>`
   aromatic bonds                      :oe:cls:`OEIsAromaticBond<OEChem::OEIsAromaticBond>`
   bond membership in a set of bonds   :ref:`OEIsBondMember <OEChem_OEIsMemberPtr_OEIsBondMember>`
   =================================== =====================================================================

.. oe:source:: FunctorsBond.cpp
   :language: c++
   :refnum:   3
   :caption:  Using predefined bond functors
   :frag:     SNIPPET

.. oe:source:: FunctorsBond.py
   :language: python
   :refnum:   3
   :caption:  Using predefined bond functors
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-FunctorsBond.py>`



.. oe:source:: FunctorsBond.java
   :language: java
   :refnum:   3
   :caption:  Using predefined bond functors
   :frag:     SNIPPET

.. oe:source:: FunctorsBond.cs
   :language: csharp
   :refnum:   3
   :caption:  Using predefined bond functors
   :frag:     SNIPPET

The output of the preceding program is the following:

.. code-block:: bash

   Number of ring bonds  = 5
   Number of rotor bonds = 2

Group Functors
--------------------------------------------------------------------------------

.. table::

   ========================================== =========================================================
   Access                                     Functor Name
   ========================================== =========================================================
   groups with a specific atom                :oe:cls:`OEHasAtomInGroup<OEChem::OEHasAtomInGroup>`
   groups with a specific bond                :oe:cls:`OEHasBondInGroup<OEChem::OEHasBondInGroup>`
   groups with a specific type                :oe:cls:`OEHasGroupType<OEChem::OEHasGroupType>`
   groups that store MDL stereo information   :oe:cls:`OEIsMDLStereoGroup<OEChem::OEIsMDLStereoGroup>`
   ========================================== =========================================================

Reaction Component Functors
--------------------------------------------------------------------------------

.. table::

   ================================================= =========================================================
   Access                                            Functor Name
   ================================================= =========================================================
   atoms of the catalysts or solvents of a reaction  :oe:cls:`OEAtomIsInAgent<OEChem::OEAtomIsInAgent>`
   atoms of the product molecule(s)                  :oe:cls:`OEAtomIsInProduct<OEChem::OEAtomIsInProduct>`
   atoms of the reactant molecule(s)                 :oe:cls:`OEAtomIsInReactant<OEChem::OEAtomIsInReactant>`
   ================================================= =========================================================

Conformer Functors
--------------------------------------------------------------------------------

.. table::

   =================================== ==================================================
   Access                              Functor Name
   =================================== ==================================================
   conformer with specified index      :oe:cls:`OEHasConfIdx<OEChem::OEHasIdx>`
   conformer with selected  index      :oe:cls:`OEConfIdxSelected<OEChem::OEIdxSelected>`
   =================================== ==================================================

.. _section_predicates_reside_data_functors:

Residue Data Functors
--------------------------------------------------------------------------------

.. table::

   ======================================= ===============================================================
   Access                                  Functor Name
   ======================================= ===============================================================
   atoms with specified residue properties :oe:cls:`OEAtomMatchResidue<OEBio::OEAtomMatchResidue>`
   atoms with specified chain id           :oe:cls:`OEHasChainID<OEChem::OEHasChainID>`
   atoms with specified residue number     :oe:cls:`OEHasResidueNumber<OEChem::OEHasResidueNumber>`
   atoms with an alternate location        :oe:cls:`OEHasAlternateLocation<OEBio::OEHasAlternateLocation>`
   atoms with specified fragment number    :oe:cls:`OEHasFragmentNumber<OEChem::OEHasFragmentNumber>`
   atoms with specified PDB index          :oe:cls:`OEHasPDBAtomIndex<OEBio::OEHasPDBAtomIndex>`
   alpha carbon                            :oe:cls:`OEIsCAlpha<OEChem::OEIsCAlpha>`
   backbone atom                           :oe:cls:`OEIsBackboneAtom<OEBio::OEIsBackboneAtom>`
   water                                   :oe:cls:`OEIsWater<OEBio::OEIsWater>`
   nucleic acid base                       :oe:cls:`OEIsNucleicAcidBase<OEBio::OEIsNucleicAcidBase>`
   nucleic acid sugar                      :oe:cls:`OEIsNucleicAcidSugar<OEBio::OEIsNucleicAcidSugar>`
   nucleic acid phosphate                  :oe:cls:`OEIsNucleicAcidPhosphate<OEBio::OEIsNucleicAcidPhosphate>`
   ======================================= ===============================================================

.. _section_predicates_composition_functors:

Composite Functors
================================================================================

Occasionally, one may want to use a logical operator to join two or
more functors. The following table shows the composite functors
defined in **OEChem TK**.

.. oe:language:: c++

   .. table:: **Composite Functors**

      ===================================== ======================================== ========================================
      Composite Functor                     Description                              Example atom composite functor
      ===================================== ======================================== ========================================
      :oe:cls:`OENot<OESystem::OENot>`      logical not                              `OENot<OEAtomBase>`
      :oe:cls:`OEOr<OESystem::OEOr>`        logical or                               `OEOr<OEAtomBase>`
      :oe:cls:`OEAnd<OESystem::OEAnd>`      logical and                              `OEAnd<OEAtomBase>`
      ===================================== ======================================== ========================================

.. oe:language:: python java csharp

   .. table:: **Composite Functors**

      ======================================= ======================================= ========================================== ==========================================
      Logical Not                             Logical or                              Logical and                                Description
      ======================================= ======================================= ========================================== ==========================================
      :oe:cls:`OENotAtom<OESystem::OENot>`    :oe:cls:`OEOrAtom<OESystem::OEOr>`      :oe:cls:`OEAndAtom<OESystem::OEAnd>`       atom composite functors
      :oe:cls:`OENotBond<OESystem::OENot>`    :oe:cls:`OEOrBond<OESystem::OEOr>`      :oe:cls:`OEAndBond<OESystem::OEAnd>`       bond composite functors
      :oe:cls:`OENotConf<OESystem::OENot>`    :oe:cls:`OEOrConf<OESystem::OEOr>`      :oe:cls:`OEAndConf<OESystem::OEAnd>`       conformation composite functors
      :oe:cls:`OENotGroup<OESystem::OENot>`   :oe:cls:`OEOrGroup<OESystem::OEOr>`     :oe:cls:`OEAndGroup<OESystem::OEAnd>`      group composite functors
      :oe:cls:`OENotRoleSet<OESystem::OENot>` :oe:cls:`OEOrRoleSet<OESystem::OEOr>`   :oe:cls:`OEAndRoleSet<OESystem::OEAnd>`    roleset composite functors
      ======================================= ======================================= ========================================== ==========================================


Each composite functor takes the appropriate number of predicates as
arguments and generates a single unary predicate.
The following example demonstrates how to use composite functors to
build expressions from **OEChem TK**'s predefined atom predicates.

.. oe:source:: CompositionFunctorsAtom.cpp
   :language: c++
   :refnum:   4
   :caption:  Combining predefined atom predicates
   :frag:     SNIPPET

.. oe:source:: CompositionFunctorsAtom.py
   :language: python
   :refnum:   4
   :caption:  Combining predefined atom predicates
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-CompositionFunctorsAtom.py>`



.. oe:source:: CompositionFunctorsAtom.java
   :language: java
   :refnum:   4
   :caption:  Combining predefined atom predicates
   :frag:     SNIPPET

.. oe:source:: CompositionFunctorsAtom.cs
   :language: csharp
   :refnum:   4
   :caption:  Combining predefined atom predicates
   :frag:     SNIPPET

The :oe:func:`OEChem::OECount` function returns the number or objects (in this case atoms)
matching the given predicate argument.

The output of the preceding program is the following:

.. code-block:: bash

   Number of chain atoms = 5
   Number of aromatic nitrogens = 1
   Number of non-carbons = 3
   Number of nitrogen and oxygen atoms = 2

.. oe:language:: c++

   Though the explicit template type instantiation isn't strictly
   necessary, in practice it is required to help several parsers make
   it through the expression.  As a convenience to programmers, three
   related template free functions have been defined. These are operator ``&&``,
   operator ``||``, and operator ``!``, which take one or more
   :oe:cls:`OEUnaryPredicates<OESystem::OEUnaryPredicate>` as arguments
   and return the appropriate composite predicate. Not only do these
   make code much easier to read, but in our experience, they also
   make the code easier for C++ parsers to parse.
   The following example is identical to the previous composite
   listing except that the composite predicates have been replaced
   by the operator free-functions.

   .. oe:source:: CompositionFunctors.cpp
      :language: c++
      :frag:     SNIPPET-PRED-COMPOSITION-ATOM


Composite functors can be used similarly to combine predefined
bond predicates.

.. oe:source:: CompositionFunctorsBond.cpp
   :language: c++
   :refnum:   5
   :caption:  Combining predefined bond predicates
   :frag:     SNIPPET

.. oe:source:: CompositionFunctorsBond.py
   :language: python
   :refnum:   5
   :caption:  Combining predefined bond predicates
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-CompositionFunctorsBond.py>`



.. oe:source:: CompositionFunctorsBond.java
   :language: java
   :refnum:   5
   :caption:  Combining predefined bond predicates
   :frag:     SNIPPET

.. oe:source:: CompositionFunctorsBond.cs
   :language: csharp
   :refnum:   5
   :caption:  Combining predefined bond predicates
   :frag:     SNIPPET

The output of the preceding program is the following:

.. code-block:: bash

   Number of non-rotatable bonds = 8
   Number of ring double bonds = 1
   Number of double or triple bonds = 2


User Defined Functors
================================================================================

While many predefined functors exist in **OEChem TK**, it is not difficult
to find a situation which calls for a new user-defined functor.

.. oe:language:: c++

   User-defined functor can be written by deriving from the
   :ref:`OEUnaryPredicate <OESystem_OEUnaryPredicate>` base template class.

.. oe:language:: python java csharp

   User-defined functor can be written by deriving from either
   the :oe:cls:`OEUnaryAtomPred<OESystem::OEUnaryPredicate>`
   or the :oe:cls:`OEUnaryBondPred<OESystem::OEUnaryPredicate>` class.

The following example shows a user defined atom functor which returns true
for aliphatic nitrogens.

.. oe:source:: UserPredAtom.cpp
   :language: c++
   :refnum:   6
   :caption:  User defined atom predicate
   :frag:     SNIPPET

.. oe:source:: UserPredAtom.py
   :language: python
   :refnum:   6
   :caption:  User defined atom predicate
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-UserPredAtom.py>`



.. oe:source:: UserPredAtom.java
   :language: java
   :refnum:   6
   :caption:  User defined atom predicate
   :frag:     SNIPPET

.. oe:source:: UserPredAtom.cs
   :language: csharp
   :refnum:   6
   :caption:  User defined atom predicate
   :frag:     SNIPPET

The output of the preceding program is the following:

.. code-block:: bash

   Number of aliphatic N atoms = 1

.. oe:language:: python

   The previous example can be alternatively rewritten using the PyAtomPredicate class.
   PyAtomPredicate takes a Python function as the single argument. This passed
   function  has to take a single :ref:`OEAtomBase <OEChem_OEAtomBase>` argument and return a
   boolean value.
   In essence, we are creating a predicate that itself holds a predicate.

   .. oe:source:: UserPyAtomPred.py
      :language: python
      :frag:     SNIPPET-PRED-PYATOM

.. oe:language:: c++

   A bond predicate can be similarly defined by deriving from the
   :oe:cls:`OEUnaryBondPred<OESystem::OEUnaryPredicate>` class.

.. oe:language:: python java csharp

   A bond predicate can be similarly defined by deriving from the
   :oe:cls:`OEUnaryBondPred<OESystem::OEUnaryPredicate>` class.

.. oe:source:: UserPredBond.cpp
   :language: c++
   :refnum:   7
   :caption:  User defined bond predicate
   :frag:     SNIPPET

.. oe:source:: UserPredBond.py
   :language: python
   :refnum:   7
   :caption:  User defined bond predicate
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-UserPredBond.py>`



.. oe:source:: UserPredBond.java
   :language: java
   :refnum:   7
   :caption:  User defined bond predicate
   :frag:     SNIPPET

.. oe:source:: UserPredBond.cs
   :language: csharp
   :refnum:   7
   :caption:  User defined bond predicate
   :frag:     SNIPPET

The output of the preceding program is the following:

.. code-block:: bash

   Number of amide bonds = 1

.. oe:language:: python

   Similarly, the previous example can be rewritten using the PyBondPredicate class.
   PyBondPredicate takes a Python function as the single argument. This passed
   function  has to take a single :ref:`OEBondBase <OEChem_OEBondBase>` argument and return a
   boolean value.

   .. oe:source:: UserPyBondPred.py
      :language: python
      :frag:     SNIPPET-PRED-PYBOND

One advantage of functors over function pointers is that they can hold
state. Since this state is held by the instance of the object it can
be thread safe (unlike static-variables inside functions used with
function pointers). The state of a functor can be initialized at
construction. For instance, :ref:`OEHasAtomicNum <OEChem_OEHasAtomicNum>` functor
takes an argument on construction which defines which atomic number is
required for the functor to return true.

.. oe:source:: UserPredAtomArg.cpp
   :language: c++
   :refnum:   8
   :caption:  User defined atom predicate with state
   :frag:     SNIPPET

.. oe:source:: UserPredAtomArg.py
   :language: python
   :refnum:   8
   :caption:  User defined atom predicate with state
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-UserPredAtomArg.py>`



.. oe:source:: UserPredAtomArg.java
   :language: java
   :refnum:   8
   :caption:  User defined atom predicate with state
   :frag:     SNIPPET

.. oe:source:: UserPredAtomArg.cs
   :language: csharp
   :refnum:   8
   :caption:  User defined atom predicate with state
   :frag:     SNIPPET


.. _section_predicates_match:

Functor substructure-based matching
================================================================================

The :oe:src:`Listing 6<SNIPPET-UserPredAtom>` shows an example how to create a
user-defined atom predicate. **OEChem TK** also provides a functor template,
called :ref:`OEMatchFunc <OEChem_OEMatchFunc>`, that allows convenient substructure-based
atom matching.

In the following example functors are initialized with a
:term:`SMARTS` string.  These functors return true only if the atom
matches the substructure pattern specified in construction.

.. oe:source:: FunctorsOEMatch.cpp
   :language: c++
   :refnum:   9
   :caption:  Functor substructure-based matching
   :frag:     SNIPPET

.. oe:source:: FunctorsOEMatch.py
   :language: python
   :refnum:   9
   :caption:  Functor substructure-based matching
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-FunctorsOEMatch.py>`



.. oe:source:: FunctorsOEMatch.java
   :language: java
   :refnum:   9
   :caption:  Functor substructure-based matching
   :frag:     SNIPPET

.. oe:source:: FunctorsOEMatch.cs
   :language: csharp
   :refnum:   9
   :caption:  Functor substructure-based matching
   :frag:     SNIPPET

The output of :oe:src:`Listing 9<SNIPPET-FunctorsOEMatch>` is the following:

.. code-block:: bash

   Number of non-amide nitrogen = 2
   Number of 5-membered ring oxygen = 1
   Number of carbon attached to halogen = 2

.. _section_predicates_partitioning:

Molecule Partitioning
================================================================================

The :oe:func:`OEChem::OESubsetMol` function can take any atom predicate
as an argument and generate a subset molecule from only atoms for which the
specified predicate returns true.  In the following example, ring atoms are
extracted from a molecule by using the :ref:`OEAtomIsInRing <OEChem_OEAtomIsInRing>`
atom functor.


.. oe:source:: FunctorsOESubsetMol.cpp
   :language: c++
   :refnum:   10
   :caption:  Ring system extraction
   :frag:     SNIPPET

.. oe:source:: FunctorsOESubsetMol.py
   :language: python
   :refnum:   10
   :caption:  Ring system extraction
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-FunctorsOESubsetMol.py>`



.. oe:source:: FunctorsOESubsetMol.java
   :language: java
   :refnum:   10
   :caption:  Ring system extraction
   :frag:     SNIPPET

.. oe:source:: FunctorsOESubsetMol.cs
   :language: csharp
   :refnum:   10
   :caption:  Ring system extraction
   :frag:     SNIPPET

The output of :oe:src:`Listing 10<SNIPPET-FunctorsOESubsetMol>` is the following:

.. code-block:: bash

   c1cc[nH]c1.C1CNCOC1


In the following example, ring systems are extracted from a molecule
by using :oe:cls:`OEPartPred<OEChem::OEPartPredT>` functor.

.. oe:source:: FunctorsOEPartPred.cpp
   :language: c++
   :refnum:   11
   :caption:  Ring system extraction
   :frag:     SNIPPET

.. oe:source:: FunctorsOEPartPred.py
   :language: python
   :refnum:   11
   :caption:  Ring system extraction
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-FunctorsOEPartPred.py>`



.. oe:source:: FunctorsOEPartPred.java
   :language: java
   :refnum:   11
   :caption:  Ring system extraction
   :frag:     SNIPPET

.. oe:source:: FunctorsOEPartPred.cs
   :language: csharp
   :refnum:   11
   :caption:  Ring system extraction
   :frag:     SNIPPET

The output of :oe:src:`Listing 11<SNIPPET-FunctorsOEPartPred>` is the following:

.. code-block:: bash

   Number of rings = 2
   1 -> c1cc[nH]c1
   2 -> C1CNCOC1
