.. include:: ../substitutions

.. oe:namespace:: OEChem

.. meta::
   :keywords: OESubsetMol

.. |DST|    replace:: The destination subset molecule generated
                      from the source molecule.
                      The source molecule may be multi-conformer, in which case a
                      multi-conformational subset molecule is produced.

.. |SRC|    replace:: The source molecule.

.. |RGROUP| replace:: Flag that indicates whether "R groups" are to be added when covalent
                      bonds are broken by the selection.

.. |ADJUSTH| replace:: Flag that indicates whether the implicit hydrogen count is to be adjusted
                       when covalent bonds are broken by the selection in order to preserve
                       the original hybridization.

.. |MAP| replace::  A mapping between the atoms or / and bonds of the source  and destination
                    molecule can be obtained by passing in the ``atomMap`` and
                    ``bondMap`` arrays respectively.
                    These arrays should be large
                    enough to hold all the atoms / bonds for the source molecule, *i.e.*,
                    the size of :oe:meth:`OEChem::OEMolBase::GetMaxAtomIdx` and
                    :oe:meth:`OEChem::OEMolBase::GetMaxBondIdx`, respectively.
                    The atoms or bonds in the array are those from the destination molecule
                    placed at the source molecule's atom / bond index location in the array.


The following functions generate fully-functional molecule
from a subset of another molecule.
The following subset methods are available:

  * :ref:`Match-based selection <api_Match_based_SubSet>` methods

  * :ref:`Atom predicate-based selection <api_AtomPred_based_SubSet>` methods

  * :ref:`Atom and bond predicate-based selection <api_AtomBondPred_based_SubSet>` methods

  * :ref:`Atom and bond set-based selection <api_AtomBondSet_based_SubSet>` methods

.. oe:function:: OESubsetMol

   **Match-based selection**

   .. _api_Match_based_SubSet:

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

      .. oe:api::

         bool OESubsetMol(OEMolBase& dst, const OEMatchBase* match,
                          bool adjustHCount = false, bool RGroup = false,
                          OEAtomBase** atomMap = 0, OEBondBase** bondMap = 0)
         bool OESubsetMol(OEMCMolBase& dst, const OEMCMolBase& src,
                          const OEMatchBase* match, bool adjustHCount = false,
                          bool RGroup = false, OEAtomBase** atomMap = 0,
                          OEBondBase** bondMap = 0)

   .. oe:language:: python

      .. oe:api:: python

         OESubsetMol(dst: OEMol, src: OEMol, match: OEMatchBase,
                     adjustHCount: bool = False, RGroup: bool = False,
                     atomMap: OEAtomBase = None, bondMap: OEBondBase = None) -> bool
         OESubsetMol(dst: Union[OEGraphMol,OEMol,OEQMol], match: OEMatchBase,
                     adjustHCount: bool = False, RGroup: bool = False,
                     atomMap: OEAtomBase = None, bondMap: OEBondBase = None) -> bool

   *dst*
     |DST|

   *src*
     |SRC|

   *match*
      The container that stores the selected atoms that will be in
      the generated subset molecule.
      By default, bonds between the selected atoms are carried along.
      If no source molecule is specified then the target molecule
      of the :oe:meth:`OEChem::OEMatchBase` defines the source
      molecule.

   *RGroup*
     |RGROUP|


   *adjustHCount*
     |ADJUSTH|

   *atomMap, bondMap*
      |MAP|

   **Atom predicate-based selection**

   .. _api_AtomPred_based_SubSet:

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

      .. oe:api::

         bool OESubsetMol(OEMolBase& dst, const OEMolBase& src,
                          const OESystem::OEUnaryPredicate<OEAtomBase>& atomfcn,
                          bool adjustHCount = false, bool RGroup = false,
                          OEAtomBase** atomMap = 0, OEBondBase** bondMap = 0)
         bool OESubsetMol(OEMCMolBase& dst, const OEMCMolBase& src,
                          const OESystem::OEUnaryPredicate<OEAtomBase>& atomfcn,
                          bool adjustHCount = false, bool RGroup = false,
                          OEAtomBase** atomMap = 0, OEBondBase** bondMap = 0)
         bool OESubsetMol(OEQMolBase& dst, const OEQMolBase& src,
                          const OESystem::OEUnaryPredicate<OEAtomBase>& atomfcn,
                          bool adjustHCount = false, bool RGroup = false,
                          OEAtomBase** atomMap = 0, OEBondBase** bondMap = 0)

   .. oe:language:: python

      .. oe:api:: python

         OESubsetMol(dst: OEMol, src: OEMol, atomfcn: OEUnaryAtomPred,
                     adjustHCount: bool = False, RGroup: bool = False,
                     atomMap: OEAtomBase = None, bondMap: OEBondBase = None) -> bool
         OESubsetMol(dst: OEQMol, src: OEQMol, atomfcn: OEUnaryAtomPred,
                     adjustHCount: bool = False, RGroup: bool = False,
                     atomMap: OEAtomBase = None, bondMap: OEBondBase = None) -> bool
         OESubsetMol(dst: Union[OEGraphMol,OEMol,OEQMol],
                     src: Union[OEGraphMol,OEMol,OEQMol],
                     atomfcn: OEUnaryAtomPred, adjustHCount: bool = False,
                     RGroup: bool = False, atomMap: OEAtomBase = None,
                     bondMap: OEBondBase = None) -> bool

   *dst*
     |DST|

   *src*
     |SRC|

   *atomfcn*
      The atom predicate that defines the subset of atoms that are
      carried over to the destination molecule.
      By default, bonds between the selected atoms are carried along.

   *RGroup*
     |RGROUP|

   *adjustHCount*
     |ADJUSTH|

   *atomMap, bondMap*
      |MAP|

   **Atom and bond predicate-based selection**

   .. _api_AtomBondPred_based_SubSet:

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

      .. oe:api::

         bool OESubsetMol(OEMolBase& dst, const OEMolBase& src,
                          const OESystem::OEUnaryPredicate<OEAtomBase>& atomfcn,
                          const OESystem::OEUnaryPredicate<OEBondBase>& bondfcn,
                          bool adjustHCount = false, bool RGroup = false,
                          OEAtomBase** atomMap = 0, OEBondBase** bondMap = 0)
         bool OESubsetMol(OEMCMolBase& dst, const OEMCMolBase& src,
                          const OESystem::OEUnaryPredicate<OEAtomBase>& atomfcn,
                          const OESystem::OEUnaryPredicate<OEBondBase>& bondfcn,
                          bool adjustHCount = false, bool RGroup = false,
                          OEAtomBase** atomMap = 0, OEBondBase** bondMap = 0)
         bool OESubsetMol(OEQMolBase& dst, const OEQMolBase& src,
                          const OESystem::OEUnaryPredicate<OEAtomBase>& atomfcn,
                          const OESystem::OEUnaryPredicate<OEBondBase>& bondfcn,
                          bool adjustHCount = false, bool RGroup = false,
                          OEAtomBase** atomMap = 0, OEBondBase** bondMap = 0)

   .. oe:language:: python

      .. oe:api:: python

         OESubsetMol(dst: OEMol, src: OEMol, atomfcn: OEUnaryAtomPred,
                     bondfcn: OEUnaryBondPred, adjustHCount: bool = False,
                     RGroup: bool = False, atomMap: OEAtomBase = None,
                     bondMap: OEBondBase = None) -> bool
         OESubsetMol(dst: OEQMol, src: OEQMol, atomfcn: OEUnaryAtomPred,
                     bondfcn: OEUnaryBondPred, adjustHCount: bool = False,
                     RGroup: bool = False, atomMap: OEAtomBase = None,
                     bondMap: OEBondBase = None) -> bool
         OESubsetMol(dst: Union[OEGraphMol,OEMol,OEQMol],
                     src: Union[OEGraphMol,OEMol,OEQMol],
                     atomfcn: OEUnaryAtomPred, bondfcn: OEUnaryBondPred,
                     adjustHCount: bool = False, RGroup: bool = False,
                     atomMap: OEAtomBase = None, bondMap: OEBondBase = None) -> bool

   *dst*
     |DST|

   *src*
     |SRC|

   *atomfcn*
      The atom predicate that defines the subset of atoms that are
      carried over to the destination molecule.

   *bondfcn*
      The atom predicate that defines the subset of bonds that are
      carried over to the destination molecule.

   *RGroup*
     |RGROUP|

   *adjustHCount*
     |ADJUSTH|

   *atomMap, bondMap*
      |MAP|

   **Atom and bond set-based selection**

   .. _api_AtomBondSet_based_SubSet:

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

      .. oe:api::

         bool OESubsetMol(OEMolBase& dst, const OEAtomBondSet& abset,
                          bool adjustHCount = false, bool RGroup = false,
                          OEAtomBase** atomMap = 0, OEBondBase** bondMap = 0)
         bool OESubsetMol(OEMolBase& dst, const OEMolBase& src,
                          const OEAtomBondSet& abset,
                          bool adjustHCount = false, bool RGroup = false,
                          OEAtomBase** atomMap = 0, OEBondBase** bondMap = 0)
         bool OESubsetMol(OEMCMolBase& dst, const OEMCMolBase& src,
                          const OEAtomBondSet& abset,
                          bool adjustHCount = false, bool RGroup = false,
                          OEAtomBase** atomMap = 0, OEBondBase** bondMap = 0)
         bool OESubsetMol(OEQMolBase& dst, const OEQMolBase& src,
                          const OEAtomBondSet& abset,
                          bool adjustHCount = false, bool RGroup = false,
                          OEAtomBase** atomMap = 0, OEBondBase** bondMap = 0)

   .. oe:language:: python

      .. oe:api:: python

         OESubsetMol(dst: OEMol, src: OEMol, submol: OEAtomBondSet,
                     adjustHCount: bool = False, RGroup: bool = False,
                     atomMap: OEAtomBase = None, bondMap: OEBondBase = None) -> bool
         OESubsetMol(dst: OEQMol, src: OEQMol, submol: OEAtomBondSet,
                     adjustHCount: bool = False, RGroup: bool = False,
                     atomMap: OEAtomBase = None, bondMap: OEBondBase = None) -> bool
         OESubsetMol(dst: Union[OEGraphMol,OEMol,OEQMol],
                     submol: OEAtomBondSet, adjustHCount: bool = False,
                     RGroup: bool = False, atomMap: OEAtomBase = None,
                     bondMap: OEBondBase = None) -> bool
         OESubsetMol(dst: Union[OEGraphMol,OEMol,OEQMol],
                     src: Union[OEGraphMol,OEMol,OEQMol],
                     submol: OEAtomBondSet, adjustHCount: bool = False,
                     RGroup: bool = False, atomMap: OEAtomBase = None,
                     bondMap: OEBondBase = None) -> bool

   *dst*
     |DST|

   *src*
     |SRC|

   *abset*
      The container that stores the selected atoms and bonds that will be in
      the generated subset molecule.
      If no source molecule is specified then :oe:meth:`OEChem::OEAtomBondSet`
      defines the source molecule.

   *RGroup*
     |RGROUP|

   *adjustHCount*
     |ADJUSTH|

   *atomMap, bondMap*
      |MAP|

   .. seealso::

      .. oe:language:: c++

         * :ref:`section_atombondindices_paralleldatastructures` section
         * :ref:`section_predicates_partitioning` section
         * Example program :ref:`parts2mols.cpp<section_example_oechem_parts2mols>`
         * Example program :ref:`extractscaffold.cpp<section_example_oechem_extractscaffold>`

      .. oe:language:: python

         * :ref:`section_atombondindices_paralleldatastructures` section
         * :ref:`section_predicates_partitioning` section
         * Example program :ref:`parts2mols.py<section_example_oechem_parts2mols>`
         * Example program :ref:`extractscaffold.py<section_example_oechem_extractscaffold>`

      .. oe:language:: java

         * :ref:`section_atombondindices_paralleldatastructures` section
         * :ref:`section_predicates_partitioning` section
         * Example program :ref:`Parts2Mols.java<section_example_oechem_parts2mols>`
         * Example program :ref:`ExtractScaffold.java<section_example_oechem_extractscaffold>`

      .. oe:language:: csharp

         * :ref:`section_atombondindices_paralleldatastructures` section
         * :ref:`section_predicates_partitioning` section
         * Example program :ref:`Parts2Mols.cs<section_example_oechem_parts2mols>`
         * Example program :ref:`ExtractScaffold.cs<section_example_oechem_extractscaffold>`

