.. _chapter_fragmentation:

********************************************************************************
Molecule Fragmentation
********************************************************************************

The *OEMedChem TK* currently provides four ways to partition a molecule
into fragments:

* :oe:func:`OEMedChem::OEGetRingChainFragments` -
  fragments a molecule into ring and chain components.

* :oe:func:`OEMedChem::OEGetRingLinkerSideChainFragments` -
  fragments a molecule into ring, linker and side-chain components as defined
  in [Bemis-1996]_ .

* :oe:func:`OEMedChem::OEGetFuncGroupFragments` - fragments a molecule into ring
  and functional group components.

* :oe:func:`OEMedChem::OEGetBemisMurcko` - fragments a molecule into ring, linker,
  framework and functional group components as in [Bemis-1996]_ .

These functions return an iterator over :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` objects
that store the atoms and the bonds of the fragments.

.. _section_example_fragringchain:

The following examples (:oe:src:`Listing 1<FragRingChain>`, :oe:src:`Listing 2<OEGetBemisMurcko>`) show how to
fragment a molecule into ring and chain components.
The code loops over the :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` objects
returned by the :oe:func:`OEMedChem::OEGetRingChainFragments`.
Each :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` object is used to initialize an atom
and a bond predicates. These predicates specify which atoms and bonds have to be
considered when creating a subset of the molecule, *i.e* the fragment, when
calling the :oe:func:`OEChem::OESubsetMol` function.
See the depiction of the input molecule and the generated fragments
in :ref:`Figure: Example of fragmentation <figure_Fragmentation>`.

.. oe:source:: FragRingChain.py
   :language: python
   :refnum:   1
   :caption:  Example of molecule fragmentation.
   :frag:     SNIPPET

..	oe:language: python

	:ref:`Full listing. <listing-FragRingChain.py>'

.. oe:source:: FragRingChain.cpp
   :language: c++
   :refnum:   1
   :caption:  Example of molecule fragmentation
   :frag:     SNIPPET

.. oe:source:: FragRingChain.java
   :language: java
   :refnum:   1
   :caption:  Example of molecule fragmentation
   :frag:     SNIPPET

.. oe:source:: FragRingChain.cs
   :language: csharp
   :refnum:   1
   :caption:  Example of molecule fragmentation
   :frag:     SNIPPET



The output of :oe:src:`Listing 1<FragRingChain>` is the following:

::

   CO
   c1ccccc1
   CC(=O)N

.. _figure_Fragmentation:

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

   **Example of fragmentation** (A) input molecule
   (B) fragments returned by the OEGetRingChainFragments function


.. seealso::

   * :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` class and :oe:func:`OEChem::OESubsetMol` function in the *OEChem TK* manual
   * :ref:`chapter_predicates` chapter in the *OEChem TK* manual.

.. _section_example_oegetbemismurcko:

The following example (:oe:src:`Listing 2<OEGetBemisMurcko>`) shows how to
fragment a molecule into ring and chain components with annotations.
See the depiction of the input molecule and the generated fragments
in :ref:`Figure: Example of Bemis Murcko fragmentation <figure_OEGetBemisMurcko>`.

.. oe:source:: OEGetBemisMurcko.py
   :language: python
   :refnum:   2
   :caption:  Example of molecule fragmentation with annotations.
   :frag:     SNIPPET

..	oe:language: python

	:ref:`Full listing. <listing-OEGetBemisMurcko.py>'

.. oe:source:: OEGetBemisMurcko.cpp
   :language: c++
   :refnum:   2
   :caption:  Example of molecule fragmentation with annotations
   :frag:     SNIPPET

.. oe:source:: OEGetBemisMurcko.java
   :language: java
   :refnum:   2
   :caption:  Example of molecule fragmentation with annotations
   :frag:     SNIPPET

.. oe:source:: OEGetBemisMurcko.cs
   :language: csharp
   :refnum:   2
   :caption:  Example of molecule fragmentation with annotations
   :frag:     SNIPPET

The output of :oe:src:`Listing 2<OEGetBemisMurcko>` is the following:

::

   Framework c1ccc(cc1)CCc2ccccc2
   Ring c1ccccc1.c1ccccc1
   Linker CC
   Sidechain CCO.CC(=O)N.CO

.. _figure_OEGetBemisMurcko:

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

   **Example of Bemis Murcko fragmentation**

.. _section_example_oegetbemismurckounsatheterobonds:

The following example (:oe:src:`Listing 3<OEGetBemisMurckoUnsatHeteroBonds>`) shows how to
fragment a molecule and include unsaturated hetero bonds on the main framework.
See the depiction of the input molecule and the generated fragments
in :ref:`Figure: Example of custom Bemis Murcko fragmentation including heteroatoms <figure_OEGetBemisMurckoUnsatHeteroBonds>`.

.. oe:source:: OEGetBemisMurckoUnsatHeteroBonds.py
   :language: python
   :refnum:   3
   :caption:  Example of custom molecule fragmentation.
   :frag:     SNIPPET

..	oe:language: python

	:ref:`Full listing. <listing-OEGetBemisMurckoUnsatHeteroBonds.py>'

.. oe:source:: OEGetBemisMurckoUnsatHeteroBonds.cpp
   :language: c++
   :refnum:   3
   :caption:  Example of custom molecule fragmentation.
   :frag:     SNIPPET

.. oe:source:: OEGetBemisMurckoUnsatHeteroBonds.java
   :language: java
   :refnum:   3
   :caption:  Example of custom molecule fragmentation
   :frag:     SNIPPET

.. oe:source:: OEGetBemisMurckoUnsatHeteroBonds.cs
   :language: csharp
   :refnum:   3
   :caption:  Example of custom molecule fragmentation
   :frag:     SNIPPET

The output of :oe:src:`Listing 3<OEGetBemisMurckoUnsatHeteroBonds>` is the following:

::

   Framework c1ccc(cc1)S(=O)(=O)NC(=O)Nc2ncncn2
   Ring c1ccccc1.c1ncncn1
   Linker C(=O)(N)NS(=O)=O
   Sidechain CC.CO.CO

.. _figure_OEGetBemisMurckoUnsatHeteroBonds:

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

   **Example of Bemis Murcko fragmentation including unsaturated hetero bonds on main framework.**

.. _section_example_oegetbemismurckocustomsubstituents:

The following example (:oe:src:`Listing 4<OEGetBemisMurckoCustomSubstituents>`) shows how to
fragment a molecule and include custom sidechains on the main framework.
See the depiction of the input molecule and the generated fragments
in :ref:`Figure: Example of custom Bemis Murcko fragmentation including custom substituents <figure_OEGetBemisMurckoCustomSubstituents>`.

.. oe:source:: OEGetBemisMurckoCustomSubstituents.py
   :language: python
   :refnum:   4
   :caption:  Example of custom molecule fragmentation 
   :frag:     SNIPPET

..	oe:language: python

	:ref:`Full listing. <listing-OEGetBemisMurckoCustomSubstituents.py>'

.. oe:source:: OEGetBemisMurckoCustomSubstituents.cpp
   :language: c++
   :refnum:   4
   :caption:  Example of custom molecule fragmentation
   :frag:     SNIPPET

.. oe:source:: OEGetBemisMurckoCustomSubstituents.java
   :language: java
   :refnum:   4
   :caption:  Example of custom molecule fragmentation
   :frag:     SNIPPET

.. oe:source:: OEGetBemisMurckoCustomSubstituents.cs
   :language: csharp
   :refnum:   4
   :caption:  Example of custom molecule fragmentation
   :frag:     SNIPPET

The output of :oe:src:`Listing 4<OEGetBemisMurckoCustomSubstituents>` is the following:

::

   Framework c1ccc(c(c1)CC(=O)N)[SH4]NC(CC(=O)N)Nc2ncncn2
   Ring c1ccc(cc1)CC(=O)N.c1ncncn1
   Linker C(C(N)N[SH5])C(=O)N
   Sidechain CC.CO.O.O

.. _figure_OEGetBemisMurckoCustomSubstituents:

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

   **Example of Bemis Murcko fragmentation including custom substituents on framework**





