.. _chapter_bioisostereexamples:
.. _bioisostere_part_examples:

********************************************************************************
Bioisostere Examples
********************************************************************************

The following table lists the currently available **Bioisostere TK** examples:

.. oe:language:: c++

   .. list-table::
      :widths: 100 100
      :header-rows: 1

      * - Program
        - Description

      * - :ref:`database<section_examples_database>`
        - Building Brood Database (CHOMP)

      * - :ref:`query<section_examples_query>`
        - Creating Brood Query

      * - :ref:`hitlist<section_examples_hitlist>`
        - Generating Brood Hits

      * - :ref:`matches<section_examples_matches>`
        - Generating Brood Matches
      
      * - :ref:`fragment_overlay<section_examples_fragment_overlay>`
        - Overlay between Fragments

      * - :ref:`replace_fragment<section_examples_replace_fragment>`
        - Replacing a Fragment in a Molecule

      * - :ref:`cpddb<section_examples_cpddb>`
        - Building and Using an External Compound Database

      * - :ref:`cluster<section_examples_cluster>`
        - Clustering Brood Hits

      * - :ref:`2molLinker_query<section_2_molecules_Linker_query>`
        - Creating a Brood Query by Linking Two Molecules (Bridging)

      * - :ref:`combo_builder<section_examples_combo_builder>`
        - Building Combined Hits from Different Queries of the Same Molecule

      * - :ref:`score_hitlist<section_examples_score_hitlist>`
        - Curating Scored Fragment Hits with OEScoreHitlist

      * - :ref:`connection_mol_builder<section_examples_connection_mol_builder>`
        - Comparing Connection and Molecule Building Outcomes


.. oe:language:: python

   .. list-table::
      :widths: 100 100
      :header-rows: 1

      * - Program
        - Description

      * - :ref:`brood_database<section_examples_database>`
        - Building Brood Database (CHOMP)

      * - :ref:`brood_query<section_examples_query>`
        - Creating Brood Query

      * - :ref:`brood_hitlist<section_examples_hitlist>`
        - Generating Brood Hits

      * - :ref:`brood_matches<section_examples_matches>`
        - Generating Brood Matches

      * - :ref:`fragment_overlay<section_examples_fragment_overlay>`
        - Overlay between Fragments

      * - :ref:`replace_fragment<section_examples_replace_fragment>`
        - Replacing a Fragment in a Molecule

      * - :ref:`cpddb<section_examples_cpddb>`
        - Building and Using an External Compound Database

      * - :ref:`brood_cluster<section_examples_cluster>`
        - Clustering Brood Hits

      * - :ref:`2molLinker_query<section_2_molecules_Linker_query>`
        - Creating a Brood Query for Linking Two Molecules (Bridging)

      * - :ref:`brood_combo_builder<section_examples_combo_builder>`
        - Building Combined Hits from Different Queries of the Same Molecule

      * - :ref:`brood_score_hitlist<section_examples_score_hitlist>`
        - Curating Scored Fragment Hits with OEScoreHitlist

      * - :ref:`brood_connection_mol_builder<section_examples_connection_mol_builder>`
        - Comparing Connection and Molecule Building Outcomes


.. _section_examples_database:

Building Brood Database (CHOMP)
--------------------------------------------------------------------------------

The following code example shows how to build a **Brood** database from
a library of molecules.

This example demonstrates end-to-end fragment database construction, including
fragment generation, optional filtering, and writing the final Brood database.

.. seealso::

   * :ref:`OEFragmentOptions <OEBioisostere_OEFragmentOptions>` class
   * :ref:`OEDBScreenOptions <OEBioisostere_OEDBScreenOptions>` class
   * :ref:`OEDBBuilder <OEBioisostere_OEDBBuilder>` class
   * :ref:`OEDBWriter <OEBioisostere_OEDBWriter>` class
   * :ref:`OEGenerateConformers <OEBioisostere_OEGenerateConformers>` function


.. oe:source:: brood_database.cpp
   :language: c++
   :caption:  Building Brood Database (CHOMP)
   :refnum:   1

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_database.cpp <../../../../sublibs/tklibs/bioisostere/examples/brood_database.cpp>`


.. oe:source:: brood_database.py
   :language: python
   :caption:  Building Brood Database (CHOMP)
   :refnum:   1

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_database.py <../../../../wrappers/python/examples/bioisostere/brood_database.py>`


.. _section_examples_query:

Creating Brood Query
--------------------------------------------------------------------------------

The following code example shows how to create a **Brood** query from a molecule
that could be used for bioisosteric fragment replacements using **Brood**.

.. seealso::

   * :ref:`OEBroodQuery <OEBioisostere_OEBroodQuery>` class
   * :ref:`OECreateBroodQuery <OEBioisostere_OECreateBroodQuery>` function

.. oe:source:: brood_query.cpp
   :language: c++
   :caption:  Creating Brood Query
   :refnum:   2

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_query.cpp <../../../../sublibs/tklibs/bioisostere/examples/brood_query.cpp>`


.. oe:source:: brood_query.py
   :language: python
   :caption:  Creating Brood Query
   :refnum:   2

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_query.py <../../../../wrappers/python/examples/bioisostere/brood_query.py>`


.. _section_examples_hitlist:

Generating Brood Hits
--------------------------------------------------------------------------------

The following code example shows how to perform bioisosteric fragment replacements
on a **Brood** query and generate a hit list.

.. seealso::

   * :ref:`OEBroodGeneralOptions <OEBioisostere_OEBroodGeneralOptions>` class
   * :ref:`OEBroodScoreOptions <OEBioisostere_OEBroodScoreOptions>` class
   * :ref:`OEBroodHitlistOptions <OEBioisostere_OEBroodHitlistOptions>` class
   * :ref:`OEBroodOverlay <OEBioisostere_OEBroodOverlay>` class
   * :ref:`OEHitlistBuilder <OEBioisostere_OEHitlistBuilder>` class

.. oe:source:: brood_hitlist.cpp
   :language: c++
   :caption:  Generating Brood Hits
   :refnum:   3

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_hitlist.cpp <../../../../sublibs/tklibs/bioisostere/examples/brood_hitlist.cpp>`


.. oe:source:: brood_hitlist.py
   :language: python
   :caption:  Generating Brood Hits
   :refnum:   3


.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_hitlist.py <../../../../wrappers/python/examples/bioisostere/brood_hitlist.py>`


.. _section_examples_matches:

Generating Brood Matches
--------------------------------------------------------------------------------

The following code example shows how to perform bioisosteric fragment replacements
on a **Brood** query and generate all possible matches. This could be a use case when
generating all possible design ideas using **BROOD** and postprocessing them with
other tools.

.. seealso::

   * :ref:`OEBroodGeneralOptions <OEBioisostere_OEBroodGeneralOptions>` class
   * :ref:`OEBroodScoreOptions <OEBioisostere_OEBroodScoreOptions>` class
   * :ref:`OEBroodOverlay <OEBioisostere_OEBroodOverlay>` class
   * :ref:`OEBroodMolBuilder <OEBioisostere_OEBroodMolBuilder>` class

.. oe:source:: brood_matching.cpp
   :language: c++
   :caption:  Generating Brood Matches
   :refnum:   4

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_matching.cpp <../../../../sublibs/tklibs/bioisostere/examples/brood_matching.cpp>`


.. oe:source:: brood_matching.py
   :language: python
   :caption:  Generating Brood Matches
   :refnum:   4


.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_matching.py <../../../../wrappers/python/examples/bioisostere/brood_matching.py>`


.. _section_examples_fragment_overlay:

Overlay between Fragments
--------------------------------------------------------------------------------

The following code example shows how to overlay a fragment against a query
fragment. This could be a use case when working with synthons and trying
to find similar synthons based on 3D similarity.

.. seealso::

   * :ref:`OEBroodGeneralOptions <OEBioisostere_OEBroodGeneralOptions>` class
   * :ref:`OEBroodScoreOptions <OEBioisostere_OEBroodScoreOptions>` class
   * :ref:`OEFragOverlay <OEBioisostere_OEFragOverlay>` class

.. oe:source:: fragment_overlay.cpp
   :language: c++
   :caption:  Overlay between Fragments
   :refnum:   5

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`fragment_overlay.cpp <../../../../sublibs/tklibs/bioisostere/examples/fragment_overlay.cpp>`


.. oe:source:: fragment_overlay.py
   :language: python
   :caption:  Overlay between Fragments
   :refnum:   5


.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`fragment_overlay.py <../../../../wrappers/python/examples/bioisostere/fragment_overlay.py>`


.. _section_examples_replace_fragment:

Replacing a Fragment in a Molecule
--------------------------------------------------------------------------------

The following code example shows how to replace a fragment in a molecule
defined in the form of a **BROOD** query.

.. seealso::

   * :ref:`OEBroodGeneralOptions <OEBioisostere_OEBroodGeneralOptions>` class
   * :ref:`OEBroodScoreOptions <OEBioisostere_OEBroodScoreOptions>` class
   * :ref:`OEBroodOverlay <OEBioisostere_OEBroodOverlay>` class
   * :ref:`OEBroodMolBuilder <OEBioisostere_OEBroodMolBuilder>` class

.. oe:source:: replace_fragment.cpp
   :language: c++
   :caption:  Replacing a Fragment in a Molecule
   :refnum:   6

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`replace_fragment.cpp <../../../../sublibs/tklibs/bioisostere/examples/replace_fragment.cpp>`

.. oe:source:: replace_fragment.py
   :language: python
   :caption:  Replacing a Fragment in a Molecule
   :refnum:   6


.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`replace_fragment.py <../../../../wrappers/python/examples/bioisostere/replace_fragment.py>`



.. _section_examples_cpddb:

Building and Using an External Compound Database
--------------------------------------------------------------------------------

The following code example shows how to build and use an external (in-house) compound database
to find similar 2D compounds to a generated hit list. It demonstrates optional analog lookup
against a user-provided compound database to annotate Brood hits with similar known molecules.

.. seealso::

   * :ref:`OECPDDatabase <OEBioisostere_OECPDDatabase>` class
   * :ref:`OEBroodGeneralOptions <OEBioisostere_OEBroodGeneralOptions>` class
   * :ref:`OEBroodScoreOptions <OEBioisostere_OEBroodScoreOptions>` class
   * :ref:`OEBroodOverlay <OEBioisostere_OEBroodOverlay>` class
   * :ref:`OEDBBuilder <OEBioisostere_OEDBBuilder>` class
   * :ref:`OEDBWriter <OEBioisostere_OEDBWriter>` class

.. oe:source:: brood_cpddb.cpp
   :language: c++
   :caption:  Building and using an external Compound Database
   :refnum:   7

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_cpddb.cpp <../../../../sublibs/tklibs/bioisostere/examples/brood_cpddb.cpp>`

.. oe:source:: brood_cpddb.py
   :language: python
   :caption:  Building and using an external compound database
   :refnum:   7


.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_cpddb.py <../../../../wrappers/python/examples/bioisostere/brood_cpddb.py>`



.. _section_2_molecules_Linker_query:

Creating Brood Query by Linking Two Molecules (Bridging)
--------------------------------------------------------------------------------

The following code example shows how to create a **Brood** query from two molecules
to find a suitable linker between the two using bioisosteric fragment replacements using **Brood**.


.. seealso::

   * :ref:`OEBroodQuery <OEBioisostere_OEBroodQuery>` class
   * :ref:`OECreateBroodQuery <OEBioisostere_OECreateBroodQuery>` function

.. oe:source:: brood_2molLinker_query.cpp
   :language: c++
   :caption:  Creating Brood Query by Linking Two Molecules (Bridging)
   :refnum:   8

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_2molLinker_query.cpp <../../../../sublibs/tklibs/bioisostere/examples/brood_2molLinker_query.cpp>`

.. oe:source:: brood_2molLinker_query.py
   :language: python
   :caption:  Creating Brood Query by Linking Two Molecules (Bridging)
   :refnum:   8


.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_2molLinker_query.py <../../../../wrappers/python/examples/bioisostere/brood_2molLinker_query.py>`


.. _section_examples_cluster:

Clustering Brood Hits
--------------------------------------------------------------------------------

The following code example shows how to cluster a generated **Brood** hit list
using :ref:`OEBroodClusterBuilder <OEBioisostere_OEBroodClusterBuilder>` and
:ref:`OEBroodCluster <OEBioisostere_OEBroodCluster>`. It demonstrates
post-processing of hits into similarity clusters and cluster-level prioritization.

.. seealso::

   * :ref:`OEBroodGeneralOptions <OEBioisostere_OEBroodGeneralOptions>` class
   * :ref:`OEBroodScoreOptions <OEBioisostere_OEBroodScoreOptions>` class
   * :ref:`OEBroodHitlistOptions <OEBioisostere_OEBroodHitlistOptions>` class
   * :ref:`OEBroodOverlay <OEBioisostere_OEBroodOverlay>` class
   * :ref:`OEHitlistBuilder <OEBioisostere_OEHitlistBuilder>` class
   * :ref:`OEBroodClusterBuilder <OEBioisostere_OEBroodClusterBuilder>` class
   * :ref:`OEBroodCluster <OEBioisostere_OEBroodCluster>` class

.. oe:source:: brood_cluster.cpp
   :language: c++
   :caption:  Clustering Brood Hits
   :refnum:   9

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_cluster.cpp <../../../../sublibs/tklibs/bioisostere/examples/brood_cluster.cpp>`

.. oe:source:: brood_cluster.py
   :language: python
   :caption:  Clustering Brood Hits
   :refnum:   9


.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_cluster.py <../../../../wrappers/python/examples/bioisostere/brood_cluster.py>`


.. _section_examples_combo_builder:

Building Combined Hits from Different Queries of the Same Molecule with OEBroodComboBuilder
---------------------------------------------------------------------------------------------

The following code example shows how to use two **Brood** queries for the same
molecule, where the first query is used to select a limited set of primary hits
(controlled by ``-primaryQueryMaxHits``) and the second query uses
:ref:`OEBroodComboBuilder <OEBioisostere_OEBroodComboBuilder>` to generate all
possible secondary (combo) hits from those selected primary hits. The second
stage is bounded by ``-secondaryQueryMaxHits``.

This example demonstrates a two-query combo workflow using ``-in`` and ``-in2``: it
builds primary hits from the first query, expands secondary combo hits from the
second query, then clusters and ranks the resulting combo hits before writing the
final output molecules.

.. seealso::

   * :ref:`OEDBReader <OEBioisostere_OEDBReader>` class
   * :ref:`OEBroodOverlay <OEBioisostere_OEBroodOverlay>` class
   * :ref:`OEBroodMolBuilder <OEBioisostere_OEBroodMolBuilder>` class
   * :ref:`OEBroodComboBuilder <OEBioisostere_OEBroodComboBuilder>` class
   * :ref:`OEBroodClusterBuilder <OEBioisostere_OEBroodClusterBuilder>` class
   * :ref:`OEBroodCluster <OEBioisostere_OEBroodCluster>` class

.. oe:source:: brood_combo_builder.cpp
   :language: c++
   :caption:  Building Combined Hits from Different Queries of the Same Molecule with OEBroodComboBuilder
   :refnum:   10

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_combo_builder.cpp <../../../../sublibs/tklibs/bioisostere/examples/brood_combo_builder.cpp>`

.. oe:source:: brood_combo_builder.py
   :language: python
   :caption:  Building Combined Hits from Different Queries of the Same Molecule with OEBroodComboBuilder
   :refnum:   10


.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_combo_builder.py <../../../../wrappers/python/examples/bioisostere/brood_combo_builder.py>`


.. _section_examples_score_hitlist:

Curating Scored Fragment Hits with OEScoreHitlist
--------------------------------------------------------------------------------

The following code example shows how to collect scored fragment matches for a
query and curate them with :ref:`OEScoreHitlist <OEBioisostere_OEScoreHitlist>`.

This example demonstrates score-level deduplication and ranking prior to full
molecule building.

.. seealso::

   * :ref:`OEDBReader <OEBioisostere_OEDBReader>` class
   * :ref:`OEBroodOverlay <OEBioisostere_OEBroodOverlay>` class
   * :ref:`OEScoreHitlist <OEBioisostere_OEScoreHitlist>` class
   * :ref:`OEBroodScore <OEBioisostere_OEBroodScore>` class

.. oe:source:: brood_score_hitlist.cpp
   :language: c++
   :caption:  Curating Scored Fragment Hits with OEScoreHitlist
   :refnum:   11

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_score_hitlist.cpp <../../../../sublibs/tklibs/bioisostere/examples/brood_score_hitlist.cpp>`

.. oe:source:: brood_score_hitlist.py
   :language: python
   :caption:  Curating Scored Fragment Hits with OEScoreHitlist
   :refnum:   11


.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_score_hitlist.py <../../../../wrappers/python/examples/bioisostere/brood_score_hitlist.py>`


.. _section_examples_connection_mol_builder:

Comparing Connection and Molecule Building Outcomes
--------------------------------------------------------------------------------

The following code example shows how to compare connection-table construction
and full molecule-building outcomes from curated scored fragments.

This example demonstrates use of :ref:`OEMolCTBuilder <OEBioisostere_OEMolCTBuilder>`,
:ref:`OEBroodMolBuilder <OEBioisostere_OEBroodMolBuilder>`, and
:ref:`OEBroodBuildResult <OEBioisostere_OEBroodBuildResult>` for build diagnostics.

.. seealso::

   * :ref:`OEScoreHitlist <OEBioisostere_OEScoreHitlist>` class
   * :ref:`OEMolCTBuilder <OEBioisostere_OEMolCTBuilder>` class
   * :ref:`OEBroodMolBuilder <OEBioisostere_OEBroodMolBuilder>` class
   * :ref:`OEBroodBuildResult <OEBioisostere_OEBroodBuildResult>` class

.. oe:source:: brood_connection_mol_builder.cpp
   :language: c++
   :caption:  Comparing Connection and Molecule Building Outcomes
   :refnum:   12

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_connection_mol_builder.cpp <../../../../sublibs/tklibs/bioisostere/examples/brood_connection_mol_builder.cpp>`

.. oe:source:: brood_connection_mol_builder.py
   :language: python
   :caption:  Comparing Connection and Molecule Building Outcomes
   :refnum:   12


.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`brood_connection_mol_builder.py <../../../../wrappers/python/examples/bioisostere/brood_connection_mol_builder.py>`
