.. _chapter_shape_examples:

Calculating Overlap
====================

Overlap calculation is the simplest functionality offered through the
**Shape TK**.  These examples show how to calculate static overlap
between two objects (molecules, grids or shape query). Note that static means
that the two input species (ref and fit) are not moved at all.  These examples
simply calculate the overlap and/or other related quantities, given the input
positions. Examples for performing calculations that actually optimize the
alignment/overlap are considered in a separate section.

Simple Overlap
----------------

This example reads in a reference molecule and a few fit
molecules and prints out the *Exact* overlap calculated.

..  oe:language:: c++

    .. oe:source:: simpleoverlap.cpp
       :language: c++
       :caption:  Simple overlap using Exact Overlap
       :refnum:   1

    ..  only:: oehtml

        .. admonition:: Download code

         :download:`simpleoverlap.cpp <../../../../sublibs/tklibs/shape/examples/simpleoverlap.cpp>`


..  oe:language:: java


    .. oe:source:: SimpleOverlap.java
       :language: java
       :caption: Simple overlap using Exact Overlap
       :refnum: 1

    ..  only:: oehtml

        .. admonition:: Download code

         :download:`SimpleOverlap.java <../../../../wrappers/java/examples/openeye/examples/oeshape/SimpleOverlap.java>`


..  oe:language:: python

    .. oe:source:: simpleoverlap.py
       :language: python
       :caption: Simple overlap using Exact Overlap
       :refnum: 1

    ..  only:: oehtml

        .. admonition:: Download code

         :download:`simpleoverlap.py <../../../../wrappers/python/examples/shape/simpleoverlap.py>`


..  oe:language:: csharp

    .. oe:source:: SimpleOverlap.cs
       :language: csharp
       :caption: Simple overlap using Exact Overlap
       :refnum: 1

    .. only:: oehtml

      .. admonition:: Download code

         :download:`SimpleOverlap.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/SimpleOverlap.cs>`


Adding overlap to molecules
----------------------------

This next example program uses the *Analytic* overlap method and also uses a
little extra OEChem to attach the overlap scores to each molecule as
SD data. This can be used to rescore a set of ROCS hits or to measure
the overlap of ROCS alignments against an exclusion region in the
binding site.

..  oe:language:: c++

    .. oe:source:: rescore.cpp
       :language: c++
       :caption: Rescoring pre-aligned structures
       :refnum: 2

    .. only:: oehtml

      .. admonition:: Download code

         :download:`rescore.cpp <../../../../sublibs/tklibs/shape/examples/rescore.cpp>`


..  oe:language:: java

    .. oe:source:: Rescore.java
       :language: java
       :caption: Rescoring pre-aligned structures
       :refnum: 2

    .. only:: oehtml

      .. admonition:: Download code

         :download:`Rescore.java <../../../../wrappers/java/examples/openeye/examples/oeshape/Rescore.java>`


..  oe:language:: python


    .. oe:source:: rescore.py
       :language: python
       :caption: Rescoring pre-aligned structures
       :refnum: 2

    .. only:: oehtml

      .. admonition:: Download code

         :download:`rescore.py <../../../../wrappers/python/examples/shape/rescore.py>`


..  oe:language:: csharp

    .. oe:source:: Rescore.cs
       :language: csharp
       :caption: Rescoring pre-aligned structures
       :refnum: 2

    .. only:: oehtml

      .. admonition:: Download code

         :download:`Rescore.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/Rescore.cs>`


Color Overlap
--------------

This example reads in a reference molecule and a few fit
molecules and prints out the *Exact* color score calculated.
By default all color calculations are performed using the
ImplicitMillsDean force field.

..  oe:language:: c++

    .. oe:source:: coloroverlap.cpp
       :language: c++
       :caption: Calculating color score
       :refnum: 3

    .. only:: oehtml

      .. admonition:: Download code

         :download:`coloroverlap.cpp <../../../../sublibs/tklibs/shape/examples/coloroverlap.cpp>`


..  oe:language:: java

    .. oe:source:: ColorOverlap.java
       :language: java
       :caption: Calculating color score
       :refnum: 3

    .. only:: oehtml

      .. admonition:: Download code

         :download:`ColorOverlap.java <../../../../wrappers/java/examples/openeye/examples/oeshape/ColorOverlap.java>`


..  oe:language:: python

    .. oe:source:: coloroverlap.py
       :language: python
       :caption: Calculating color score
       :refnum: 3

    .. only:: oehtml

      .. admonition:: Download code

         :download:`coloroverlap.py <../../../../wrappers/python/examples/shape/coloroverlap.py>`


..  oe:language:: csharp

    .. oe:source:: ColorOverlap.cs
       :language: csharp
       :caption: Calculating color score
       :refnum: 3

    .. only:: oehtml

      .. admonition:: Download code

         :download:`ColorOverlap.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/ColorOverlap.cs>`


Adding color score to molecules
--------------------------------

This next example uses the ImplicitMillsDean force field and the *Analytic*
color to rescore a set of ROCS hits and add the color scores to SD tags.

..  oe:language:: c++

    .. oe:source:: colorscore.cpp
       :language: c++
       :caption: Using color to add scores to pre-aligned molecules.
       :refnum: 4


    .. only:: oehtml

      .. admonition:: Download code

         :download:`colorscore.cpp <../../../../sublibs/tklibs/shape/examples/colorscore.cpp>`


..  oe:language:: java

    .. oe:source:: ColorScore.java
       :language: java
       :caption: Using color to add scores to pre-aligned molecules.
       :refnum: 4

    .. only:: oehtml

      .. admonition:: Download code

         :download:`ColorScore.java <../../../../wrappers/java/examples/openeye/examples/oeshape/ColorScore.java>`

..  oe:language:: python

    .. oe:source:: colorscore.py
       :language: python
       :caption: Using color to add scores to pre-aligned molecules.
       :refnum: 4

    .. only:: oehtml

      .. admonition:: Download code

         :download:`colorscore.py <../../../../wrappers/python/examples/shape/colorscore.py>`


..  oe:language:: csharp

    .. oe:source:: ColorScore.cs
       :language: csharp
       :caption: Using color to add scores to pre-aligned molecules.
       :refnum: 4

    .. only:: oehtml

      .. admonition:: Download code

         :download:`ColorScore.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/ColorScore.cs>`


User Defined Color
-------------------

As a step toward writing a complete color force field, it is possible
to combine built-in rules for color atom assignment with user defined
interactions.  A new :ref:`OEColorForceField <OEShape_OEColorForceField>` object can be
created using one of the built-in types, then the interactions can be
cleared using :oe:meth:`OEShape::OEColorForceField::ClearInteractions` and subsequent user
interactions added with :oe:meth:`OEShape::OEColorForceField::AddInteraction`.

For example, to use the ImplicitMillsDean atom typing rules, but to
only consider donor-donor and acceptor-acceptor interactions, one can
use the following:

..  oe:language:: c++

    .. oe:source:: usercolor.cpp
       :language: c++
       :caption: Using ImplicitMillsDean with user interactions.
       :refnum: 5

    .. only:: oehtml

      .. admonition:: Download code

         :download:`usercolor.cpp <../../../../sublibs/tklibs/shape/examples/usercolor.cpp>`


..  oe:language:: java

    .. oe:source:: UserColor.java
       :language: java
       :caption: Using ImplicitMillsDean with user interactions.
       :refnum: 5

    .. only:: oehtml

      .. admonition:: Download code

         :download:`UserColor.java <../../../../wrappers/java/examples/openeye/examples/oeshape/UserColor.java>`

..  oe:language:: python

    .. oe:source:: usercolor.py
       :language: python
       :caption: Using ImplicitMillsDean with user interactions.
       :refnum: 5

    .. only:: oehtml

      .. admonition:: Download code

         :download:`/usercolor.py <../../../../wrappers/python/examples/shape/usercolor.py>`

..  oe:language:: csharp

    .. oe:source:: UserColor.cs
       :language: csharp
       :caption: Using ImplicitMillsDean with user interactions.
       :refnum: 5

    .. only:: oehtml

      .. admonition:: Download code

         :download:`UserColor.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/UserColor.cs>`

Shape and Color Overlap
------------------------

This example reads in a reference molecule and a few fit
molecules and prints out both the shape overlap and the color score
calculated. By default the OEOverlapFunc uses the *Grid* shape and
*Exact* color.


..  oe:language:: c++

    .. oe:source:: overlapcolor.cpp
       :language: c++
       :caption: Calculating both shape and color overlap
       :refnum: 5

    .. only:: oehtml

      .. admonition:: Download code

         :download:`overlapcolor.cpp <../../../../sublibs/tklibs/shape/examples/overlapcolor.cpp>`

..  oe:language:: java

    .. oe:source:: OverlapColor.java
       :language: java
       :caption: Calculating both shape and color overlap
       :refnum: 6

    .. only:: oehtml

      .. admonition:: Download code

         :download:`OverlapColor.java <../../../../wrappers/java/examples/openeye/examples/oeshape/OverlapColor.java>`


..  oe:language:: python

    .. oe:source:: overlapcolor.py
       :language: python
       :caption: Calculating both shape and color overlap
       :refnum: 6

    .. only:: oehtml

      .. admonition:: Download code

         :download:`overlapcolor.py  <../../../../wrappers/python/examples/shape/overlapcolor.py>`

..  oe:language:: csharp

    .. oe:source:: OverlapColor.cs
       :language: csharp
       :caption: Calculating both shape and color overlap
       :refnum: 6

    .. only:: oehtml

      .. admonition:: Download code

         :download:`OverlapColor.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/OverlapColor.cs>`


ROCS
=====

The high-level :ref:`OEROCS <OEShape_OEROCS>` provides the simplest way to
maximize shape and/or color between two objects. OEROCS uses the same
shape and color functions as used for static overlap calculation, but
optimizes the overlap between the reference and the fit objects.  By
default both shape and color optimization is performed, with shape
estimated with the *Grid* method and color estimated with the *Exact* method.

The fit object is not moved during the optimization. Part of the results
returned from the calculation are the transform required to move the
fit object into the final orientation.  The results also contain a
copy of the fit molecule conformer(s) in its final orientation.

A helper function OEROCSOverlay is created for the most simple usage of
the functionality that performs optimizations between a set of conformers
and returns the best hit.

Best Hit
---------

This example reads in a reference molecule and a fit
molecule, performs overlay optimization, finds the best hit
conformer and prints it out in final orientation.


..  oe:language:: c++

    .. oe:source:: besthit.cpp
       :language: c++
       :caption: Finding best hit conformer pair
       :refnum: 7

    .. only:: oehtml

      .. admonition:: Download code

         :download:`besthit.cpp <../../../../sublibs/tklibs/shape/examples/besthit.cpp>`



..  oe:language:: java

    .. oe:source:: BestHit.java
       :language: java
       :caption: Finding best hit conformer pair
       :refnum: 7

    .. only:: oehtml

      .. admonition:: Download code

         :download:`BestHit.java <../../../../wrappers/java/examples/openeye/examples/oeshape/BestHit.java>`


..  oe:language:: python


    .. oe:source:: besthit.py
       :language: python
       :caption: Finding best hit conformer pair
       :refnum: 7


    .. only:: oehtml

      .. admonition:: Download code

         :download:`besthit.py <../../../../wrappers/python/examples/shape/besthit.py>`


..  oe:language:: csharp

    .. oe:source:: BestHit.cs
       :language: csharp
       :caption: Finding best hit conformer pair
       :refnum: 7


    .. only:: oehtml

      .. admonition:: Download code

         :download:`BestHit.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/BestHit.cs>`


Top Hits
---------

This example reads in a reference molecule and a few fit
molecules, performs overlay optimization, finds the few top hits,
and prints them out in final orientation.


..  oe:language:: c++

    .. oe:source:: tophits.cpp
       :language: c++
       :caption: Finding top ROCS hits
       :refnum: 8

    .. only:: oehtml

      .. admonition:: Download code

         :download:`tophits.cpp <../../../../sublibs/tklibs/shape/examples/tophits.cpp>`


..  oe:language:: java

    .. oe:source:: TopHits.java
       :language: java
       :caption: Finding top ROCS hits
       :refnum: 8


    .. only:: oehtml

      .. admonition:: Download code

         :download:`TopHits.java <../../../../wrappers/java/examples/openeye/examples/oeshape/TopHits.java>`


..  oe:language:: python

    .. oe:source:: tophits.py
       :language: python
       :caption: Finding top ROCS hits
       :refnum: 8

    .. only:: oehtml

      .. admonition:: Download code

         :download:`tophits.py <../../../../wrappers/python/examples/shape/tophits.py>`


..  oe:language:: csharp

    .. oe:source:: TopHits.cs
       :language: csharp
       :caption: Finding top ROCS hits
       :refnum: 8


    .. only:: oehtml

      .. admonition:: Download code

         :download:`TopHits.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/TopHits.cs>`


Top Hits with Multiple Conformers
----------------------------------

This example repeats the Top Hits example above but fixes the number
of hits to 3 and asks for multiple best conformers for each hit reported.

..  oe:language:: c++

    .. oe:source:: tophitsconf.cpp
       :language: c++
       :caption: Finding top ROCS hits with multiple conformers
       :refnum: 9


    .. only:: oehtml

      .. admonition:: Download code

         :download:`tophitsconf.cpp <../../../../sublibs/tklibs/shape/examples/tophitsconf.cpp>`


..  oe:language:: java

    .. oe:source:: TopHitsConf.java
       :language: java
       :caption: Finding top ROCS hits with multiple conformers
       :refnum: 9


    .. only:: oehtml

      .. admonition:: Download code

         :download:`TopHitsConf.java <../../../../wrappers/java/examples/openeye/examples/oeshape/TopHitsConf.java>`

..  oe:language:: python

    .. oe:source:: tophitsconf.py
       :language: python
       :caption: Finding top ROCS hits with multiple conformers
       :refnum: 9

    .. only:: oehtml

      .. admonition:: Download code

         :download:`tophitsconf.py <../../../../wrappers/python/examples/shape/tophitsconf.py>`

..  oe:language:: csharp

    .. oe:source:: TopHitsConf.cs
       :language: csharp
       :caption: Finding top ROCS hits with multiple conformers
       :refnum: 9

    .. only:: oehtml

      .. admonition:: Download code

         :download:`TopHitsConf.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/TopHitsConf.cs>`

Overlay Optimization
=====================

The methods :ref:`OEOverlay <OEShape_OEOverlay>` and :ref:`OEMultiRefOverlay <OEShape_OEMultiRefOverlay>`,
compared to :ref:`OEROCS <OEShape_OEROCS>`, allow setting up a reference system
and process overlay optimization of multiple fit molecules. Another difference
is that both :ref:`OEOverlay <OEShape_OEOverlay>` and :ref:`OEMultiRefOverlay <OEShape_OEMultiRefOverlay>`,
in addition to providing the best overlay score, also give access to all the
results obtained during an overlay optimization. Methods
:ref:`OEOverlay <OEShape_OEOverlay>` and
:ref:`OEMultiRefOverlay <OEShape_OEMultiRefOverlay>`, which
provide all results, should  be used only when such a rigorous amount
of resulting data is desired.

.. _section_best_optimization_example:

Best Optimization Result
-------------------------

This example reads in a reference molecule and a few fit
molecules, performs overlay optimization, and returns only the best
result per reference to fit molecule overlay optimization.

..  oe:language:: c++

    .. oe:source:: overlaybestres.cpp
       :language: c++
       :caption: Getting the best scores from OEMultiRefOverlay.
       :refnum: 10

    .. only:: oehtml

      .. admonition:: Download code

         :download:`overlaybestres.cpp <../../../../sublibs/tklibs/shape/examples/overlaybestres.cpp>`

..  oe:language:: java


    .. oe:source:: OverlayBestRes.java
       :language: java
       :caption: Getting the best scores from OEMultiRefOverlay.
       :refnum: 10

    .. only:: oehtml

      .. admonition:: Download code

         :download:`OverlayBestRes.java <../../../../wrappers/java/examples/openeye/examples/oeshape/OverlayBestRes.java>`


..  oe:language:: python


    .. oe:source:: overlaybestres.py
       :language: python
       :caption: Getting the best scores from OEMultiRefOverlay.
       :refnum: 10

    .. only:: oehtml

      .. admonition:: Download code

         :download:`overlaybestres.py <../../../../wrappers/python/examples/shape/overlaybestres.py>`

    .. oe:source:: multicorebestoverlay.py
       :language: python
       :caption: Getting the best scores from OEMultiRefOverlay (multi-threaded version)
       :refnum: 10b

    .. only:: oehtml

      .. admonition:: Download code

         :download:`multicorebestoverlay.py <../../../../wrappers/python/examples/shape/multicorebestoverlay.py>`

..  oe:language:: csharp

    .. oe:source:: OverlayBestRes.cs
       :language: csharp
       :caption: Getting the best scores from OEMultiRefOverlay.
       :refnum: 10

    .. only:: oehtml

      .. admonition:: Download code

         :download:`OverlayBestRes.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/OverlayBestRes.cs>`

All Optimization Results
-------------------------

This example repeats the above, but uses
:oe:meth:`OEMultiRefOverlay::Overlay<OEShape::OEMultiRefOverlay::Overlay>`
to obtain all the results.

A single Overlay calculation will return N results, where N is the number of
ref conformers times the number of fit conformers times the number of starting
positions for each pair. So comparing 2 molecules with 10 conformers each could
return 400 or more results.

There are two helper classes designed solely to contain these results
and to make it easy to extract all or just the desired
subset. :ref:`OEBestOverlayResults <OEShape_OEBestOverlayResults>` holds the results of a
single pair of conformers. It contains a set of
:ref:`OEBestOverlayScore <OEShape_OEBestOverlayScore>` objects, one for each starting
position.

This example uses 2 iterators to show all the results.

..  oe:language:: c++

    .. oe:source:: overlayallres.cpp
       :language: c++
       :caption: Getting all the scores from OEMultiRefOverlay.
       :refnum: 11

    .. only:: oehtml

      .. admonition:: Download code

         :download:`overlayallres.cpp <../../../../sublibs/tklibs/shape/examples/overlayallres.cpp>`

..  oe:language:: java

    .. oe:source:: OverlayAllRes.java
       :language: java
       :caption: Getting all the scores from OEMultiRefOverlay.
       :refnum: 11

    .. only:: oehtml

      .. admonition:: Download code

         :download:`OverlayAllRes.java <../../../../wrappers/java/examples/openeye/examples/oeshape/OverlayAllRes.java>`


..  oe:language:: python

    .. oe:source:: overlayallres.py
       :language: python
       :caption: Getting all the scores from OEMultiRefOverlay.
       :refnum: 11

    .. only:: oehtml

      .. admonition:: Download code

         :download:`overlayallres.py <../../../../wrappers/python/examples/shape/overlayallres.py>`


..  oe:language:: csharp

    .. oe:source:: OverlayAllRes.cs
       :language: csharp
       :caption: Getting all the scores from OEMultiRefOverlay.
       :refnum: 11

    .. only:: oehtml

      .. admonition:: Download code

         :download:`OverlayAllRes.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/OverlayAllRes.cs>`

Manipulating all results
-------------------------

This example repeats the above to access all overlay results, and
shows how to navigate through the results to extract a specific set.
Here, the :oe:func:`OEShape::OESortOverlayScores` function is used to turn the
double iterator as shown in the example above into a single iterator
of :ref:`OEBestOverlayScore <OEShape_OEBestOverlayScore>`. Note that the third argument
is a functor used to sort the list, such that in this next example, we
get one :ref:`OEBestOverlayScore <OEShape_OEBestOverlayScore>` for each pair of
conformers, and they are returned in Tanimoto order.

OEOverlay or OEMultiRefOverlay does not actually move the fit molecule. Part of
OEBestOverlayScore is the rotation matrix and translation matrix
necessary to move the fit molecule into the final overlap
position. (Note well: the rotation matrix is left-multiplied so can be
regarded as left-handed.)  This example also shows how to apply these
transformations. The OpenEye standard is rotation then translation,
but as a convenience, OEBestOverlayScore has
:oe:meth:`OEShape::OEBestOverlayScore::Transform` method that will
apply the transforms in the proper order.

This example keeps the user specified number of scores, aligns each fit conformer
to the ref conformer it was overlaid on, and then write the pair to an output
file. If SD or OEB is used as the output file type, then scores will
also be stored in SD tags.

..  oe:language:: c++

    .. oe:source:: overlaystruct.cpp
       :language: c++
       :caption: Writing few aligned structures from OEMultiRefOverlay.
       :refnum: 12

    .. only:: oehtml

      .. admonition:: Download code

         :download:`overlaystruct.cpp <../../../../sublibs/tklibs/shape/examples/overlaystruct.cpp>`

..  oe:language:: java

    .. oe:source:: OverlayStruct.java
       :language: java
       :caption: Writing few aligned structures from OEMultiRefOverlay.
       :refnum: 12

    .. only:: oehtml

      .. admonition:: Download code

         :download:`OverlayStruct.java <../../../../wrappers/java/examples/openeye/examples/oeshape/OverlayStruct.java>`

..  oe:language:: python

    .. oe:source:: overlaystruct.py
       :language: python
       :caption: Writing few aligned structures from OEMultiRefOverlay.
       :refnum: 12

    .. only:: oehtml

      .. admonition:: Download code

         :download:`overlaystruct.py <../../../../wrappers/python/examples/shape/overlaystruct.py>`

..  oe:language:: csharp

    .. oe:source:: OverlayStruct.cs
       :language: csharp
       :caption: Writing few aligned structures from OEMultiRefOverlay.
       :refnum: 12

    .. only:: oehtml

      .. admonition:: Download code

         :download:`OverlayStruct.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/OverlayStruct.cs>`

Working with Shape Query
============================

This section of examples shows the use of a :ref:`OEShapeQuery <OEShape_OEShapeQuery>`,
and performs calculations where a shape query is used as the reference system
instead of a molecule as the reference.

Creating a shape query
-----------------------

This examples shows how to create a simple shape query that combines a molecule
with gaussians.  In this example, the molecule is added in the query to define
shape, and color is added separately in terms to gaussians. The created query is
then saved in a file.

..  oe:language:: c++

    .. oe:source:: createquery.cpp
       :language: c++
       :caption: Creating a shape query.
       :refnum: 13

    .. only:: oehtml

      .. admonition:: Download code

         :download:`createquery.cpp <../../../../sublibs/tklibs/shape/examples/createquery.cpp>`

.. oe:language:: java

    .. oe:source:: CreateQuery.java
       :language: java
       :caption: Creating a shape query.
       :refnum: 13

    .. only:: oehtml

      .. admonition:: Download code

         :download:`CreateQuery.java <../../../../wrappers/java/examples/openeye/examples/oeshape/CreateQuery.java>`

..  oe:language:: python

    .. oe:source:: createquery.py
       :language: python
       :caption: Creating a shape query.
       :refnum: 13

    .. only:: oehtml

      .. admonition:: Download code

         :download:`createquery.py <../../../../wrappers/python/examples/shape/createquery.py>`

..  oe:language:: csharp

    .. oe:source:: CreateQuery.cs
       :language: csharp
       :caption: Creating a shape query.
       :refnum: 13

    .. only:: oehtml

      .. admonition:: Download code

         :download:`CreateQuery.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/CreateQuery.cs>`

Overlap with shape query
-------------------------

This example reads in a reference shape query and a few fit
molecules and prints out both the shape overlap and the color score
calculated. By default the OEOverlapFunc uses the *Grid* shape and
*Exact* color.

..  oe:language:: c++

    .. oe:source:: overlapquery.cpp
       :language: c++
       :caption: Overlap with a shape query
       :refnum: 14

    .. only:: oehtml

      .. admonition:: Download code

         :download:`overlapquery.cpp <../../../../sublibs/tklibs/shape/examples/overlapquery.cpp>`

..  oe:language:: java

    .. oe:source:: OverlapQuery.java
       :language: java
       :caption: Overlap with a shape query
       :refnum: 14

    .. only:: oehtml

      .. admonition:: Download code

         :download:`OverlapQuery.java <../../../../wrappers/java/examples/openeye/examples/oeshape/OverlapQuery.java>`

..  oe:language:: python

    .. oe:source:: overlapquery.py
       :language: python
       :caption: Overlap with a shape query
       :refnum: 14

    .. only:: oehtml

      .. admonition:: Download code

         :download:`overlapquery.py <../../../../wrappers/python/examples/shape/overlapquery.py>`

..  oe:language:: csharp

    .. oe:source:: OverlapQuery.cs
       :language: csharp
       :caption: Overlap with a shape query
       :refnum: 14

    .. only:: oehtml

      .. admonition:: Download code

         :download:`OverlapQuery.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/OverlapQuery.cs>`

Top hit against shape query
-----------------------------
This example reads in a reference query and a few fit
molecules, performs overlay optimization, finds the few top hits,
and prints them out in final orientation.

..  oe:language:: c++

    .. oe:source:: tophitsquery.cpp
       :language: c++
       :caption: Finding top ROCS hits against a query
       :refnum: 15

    .. only:: oehtml

      .. admonition:: Download code

         :download:`tophitsquery.cpp <../../../../sublibs/tklibs/shape/examples/tophitsquery.cpp>`


..  oe:language:: java

    .. oe:source:: TopHitsQuery.java
       :language: java
       :caption: Finding top ROCS hits against a query
       :refnum: 15

    .. only:: oehtml

      .. admonition:: Download code

         :download:`TopHitsQuery.java <../../../../wrappers/java/examples/openeye/examples/oeshape/TopHitsQuery.java>`


..  oe:language:: python

    .. oe:source:: tophitsquery.py
       :language: python
       :caption: Finding top ROCS hits against a query
       :refnum: 15

    .. only:: oehtml

      .. admonition:: Download code

         :download:`tophitsquery.py <../../../../wrappers/python/examples/shape/tophitsquery.py>`

..  oe:language:: csharp

    .. oe:source:: TopHitsQuery.cs
       :language: csharp
       :caption: Finding top ROCS hits against a query
       :refnum: 15

    .. only:: oehtml

      .. admonition:: Download code

         :download:`TopHitsQuery.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/TopHitsQuery.cs>`

Grid-To-Gaussians Fit
---------------------

In this example, an input molecule is converted to a molecular grid. Next the resulting grid is fitted to
shape Gaussians.

..  oe:language:: python

    .. oe:source:: grid_to_gaussians_fit.py
       :language: python
       :caption: Grid to gaussians fit
       :refnum: 19

    .. only:: oehtml

      .. admonition:: Download code

         :download:`grid_to_gaussians_fit.py <../../../../wrappers/python/examples/shape/grid_to_gaussians_fit.py>`

.. _chapter_hermite_shape_examples:

Shape from Hermite expansion
============================

Using Hermite expansion we can obtain two functionalities: expand a molecule
into Hermite representation and compare two molecules that are in the Hermite
representation by computing their shape-Tanimoto coefficient. We illustrate
both functionalities below with two examples.

Hermite expansion
-----------------

In this example we input a molecule, set the level of Hermite expansion using NPolyMax variable,
determine the optimal parameters for :math:`\lambda_x, \lambda_y, \lambda_z`, and perform the
computation of the Hermite expansion. At the end we output the resulting Hermite representation of the
molecule as a grid, using CreateGrid method of the :ref:`OEHermite class <OEShape_OEHermite>`.
The user can vary NPolyMax from
low numbers, like 4 or 5, to higher numbers like 10–30 and observe convergence of the shape. Which value
to use in practice depends on the size of the input molecule. Input molecule can be drug-like as well as a
protein.

..  oe:language:: c++

    .. oe:source:: hermite-expansion.cpp
       :language: c++
       :caption: Expanding a molecular shape into Hermite polynomials
       :refnum: 16

    .. only:: oehtml

      .. admonition:: Download code

         :download:`hermite-expansion.cpp <../../../../sublibs/tklibs/shape/examples/hermite-expansion.cpp>`

..  oe:language:: python

    .. oe:source:: hermite-expansion.py
       :language: python
       :caption: Expanding a molecular shape into Hermite polynomials
       :refnum: 16

    .. only:: oehtml

      .. admonition:: Download code

         :download:`hermite-expansion.py <../../../../wrappers/python/examples/shape/hermite-expansion.py>`

..  oe:language:: java

    .. oe:source:: HermiteExpansion.java
       :language: java
       :caption: Expanding a molecular shape into Hermite polynomials
       :refnum: 16

    .. only:: oehtml

      .. admonition:: Download code

         :download:`HermiteExpansion.java <../../../../wrappers/java/examples/openeye/examples/oeshape/HermiteExpansion.java>`

..  oe:language:: csharp

    .. oe:source:: HermiteExpansion.cs
       :language: csharp
       :caption: Expanding a molecular shape into Hermite polynomials
       :refnum: 16

    .. only:: oehtml

      .. admonition:: Download code

         :download:`HermiteExpansion.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/HermiteExpansion.cs>`

Hermite Tanimoto comparison of shape
------------------------------------

In the second example below, we set up two molecules and compute the
Tanimoto shape similarity coefficient, using Hermite expansion. The Hermite
prep parameter NPolyMax is used to 
compute the shape-Tanimoto coefficient. First molecule in the reference
input file is used versus all molecules in the fit input file. Results are
attached as SD data to the moved fit molecule, as dictated by Hermite overlay,
and sent to the output file. One can observe convergence of the
Hermite Tanimoto coefficients as the level of expansion becomes more accurate.

..  oe:language:: c++

    .. oe:source:: hermite-tanimoto.cpp
       :language: c++
       :caption: Calculating shape Tanimoto using Hermite expansion
       :refnum: 17

    .. only:: oehtml

      .. admonition:: Download code

         :download:`hermite-tanimoto.cpp <../../../../sublibs/tklibs/shape/examples/hermite-tanimoto.cpp>`


..  oe:language:: python

    .. oe:source:: hermite-tanimoto.py
       :language: python
       :caption: Calculating shape Tanimoto using Hermite expansion
       :refnum: 17

    .. only:: oehtml

      .. admonition:: Download code

         :download:`hermite-tanimoto.py <../../../../wrappers/python/examples/shape/hermite-tanimoto.py>`


..  oe:language:: java

    .. oe:source:: HermiteTanimoto.java
       :language: java
       :caption: Calculating shape Tanimoto using Hermite expansion
       :refnum: 17

    .. only:: oehtml

      .. admonition:: Download code

         :download:`HermiteTanimoto.java <../../../../wrappers/java/examples/openeye/examples/oeshape/HermiteTanimoto.java>`


..  oe:language:: csharp

    .. oe:source:: HermiteTanimoto.cs
       :language: csharp
       :caption: Calculating shape Tanimoto using Hermite expansion
       :refnum: 17

    ..  only:: oehtml

        .. admonition:: Download code

         :download:`HermiteTanimoto.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/HermiteTanimoto.cs>`

Hermite Grid Overlay
------------------------------------

In this example, we perform grid-to-grid overlay optimization and compute the
Tanimoto coefficient between them using Hermite expansion. Hermite overlays 
between grids and molecules can also be evaluated in a similar way.

..  oe:language:: c++

    .. oe:source:: hermite-grid-overlay.cpp
       :language: c++
       :caption: Grid overlay using Hermite expansion
       :refnum: 22

    .. only:: oehtml

      .. admonition:: Download code

         :download:`hermite-grid-overlay.cpp <../../../../sublibs/tklibs/shape/examples/hermite-grid-overlay.cpp>`


..  oe:language:: python

    .. oe:source:: hermite-grid-overlay.py
       :language: python
       :caption: Grid overlay using Hermite expansion
       :refnum: 22

    .. only:: oehtml

      .. admonition:: Download code

         :download:`hermite-grid-overlay.py <../../../../wrappers/python/examples/shape/hermite-grid-overlay.py>`

.. _chapter_flexi_overlay_examples:

Flexible Overlay with Shape, Color, and Forcefield
======================================================

By incorporating Forcefield into the overlay optimization alongside Shape and Color, 
molecular flexibility can be introduced to the input fit molecule conformers. 
The flexible overlay optimization approach maintains rigidity in the reference molecule 
conformer while allowing for flexibility in the fit molecules. 
To illustrate the functionality of flexible overlay, we provide two examples. 
Note that, the default settings for the :ref:`OEFlexiOverlay<OEShape_OEFlexiOverlay>`  
perform optimization on both *Shape* and *Color* overlap while also considering 
*intra-molecular forcefield*. 

It is important to note that when running flexible overlay optimization of a molecule 
against itself, the user should not expect to obtain a tanimotocombo value of 2.0. 
This is because the fit molecules undergo flexible optimization, which includes 
intra-molecular force field, and thus may result in some deviation from 2.0.

Flexible Overlay
-----------------

In this example, Flexible overlay optimization of the fit molecules is performed against
a single reference molecule conformer.  Results of flexible overlay of all of the fit molecule
conformers are reported and saved.  

..  oe:language:: c++

    .. oe:source:: flexi_overlay.cpp
       :language: c++
       :caption: Flexible overlay optimization
       :refnum: 18

    .. only:: oehtml

      .. admonition:: Download code

         :download:`flexi_overlay.cpp <../../../../sublibs/tklibs/shape/examples/flexi_overlay.cpp>`

..  oe:language:: python

    .. oe:source:: flexi_overlay.py
       :language: python
       :caption: Flexible overlay optimization
       :refnum: 18

    .. only:: oehtml

      .. admonition:: Download code

         :download:`flexi_overlay.py <../../../../wrappers/python/examples/shape/flexi_overlay.py>`

Flexible Best Overlay
----------------------

In this example, Flexible overlay optimization of the fit molecules is performed against
a single reference molecule conformer.  The best overlaid conformers and the corresponding
results are reported and saved.

..  oe:language:: c++

    .. oe:source:: flexi_best_overlay.cpp
       :language: c++
       :caption: Flexible best overlay
       :refnum: 19

    .. only:: oehtml

      .. admonition:: Download code

         :download:`flexi_best_overlay.cpp <../../../../sublibs/tklibs/shape/examples/flexi_best_overlay.cpp>`

..  oe:language:: python

    .. oe:source:: flexi_best_overlay.py
       :language: python
       :caption: Flexible best overlay
       :refnum: 19

    .. only:: oehtml

      .. admonition:: Download code

         :download:`flexi_best_overlay.py <../../../../wrappers/python/examples/shape/flexi_best_overlay.py>`


Advanced Examples
===================

.. _section_nxnshape_example:

Calculating NxN scores
-----------------------

There are times when you want to have all the pairwise scores among a set of
molecules. Maintaining this 2D matrix of scores is more complicated than the
single set of scores from the *ref vs. set of fit molecules* examples shown
above.

This example takes a set of molecules and performs all the pairwise shape
optimizations with OEBestOverlay. It outputs a *spreadsheet* of the scores.

..  oe:language:: c++

    .. oe:source:: nxnshape.cpp
       :language: c++
       :caption: Calculating NxN scores.
       :refnum: 20

    .. only:: oehtml

      .. admonition:: Download code

         :download:`nxnshape.cpp <../../../../sublibs/tklibs/shape/examples/nxnshape.cpp>`


..  oe:language:: java

    .. oe:source:: NxNShape.java
       :language: java
       :caption: Calculating NxN scores.
       :refnum: 20

    .. only:: oehtml

      .. admonition:: Download code

         :download:`NxNShape.java <../../../../wrappers/java/examples/openeye/examples/oeshape/NxNShape.java>`

..  oe:language:: python

    .. oe:source:: nxnshape.py
       :language: python
       :caption: Calculating NxN scores.
       :refnum: 20

    .. only:: oehtml

      .. admonition:: Download code

         :download:`nxnshape.py <../../../../wrappers/python/examples/shape/nxnshape.py>`

..  oe:language:: csharp

    .. oe:source:: NxNShape.cs
       :language: csharp
       :caption: Calculating NxN scores.
       :refnum: 20

    .. only:: oehtml

      .. admonition:: Download code

         :download:`NxNShape.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/NxNShape.cs>`

Calculating shape characteristics
----------------------------------

While most functionality in the Shape Toolkit involves comparison of
pairs of molecules, there are a few fundamental properties that can be
calculated for a single molecule. All of these calculations are done
using the same basic Gaussian description of a molecule as described
above.

The simplest property to calculate is volume, using :oe:func:`OEShape::OECalcVolume`.

In addition to simple volume calculations, the steric multipoles of a
molecule can also be calculated. See section :oe:func:`OEShape::OECalcShapeMultipoles`.

This next example demonstrates the calculation of volume and shape multipoles.

..  oe:language:: c++

    .. oe:source:: shapeprops.cpp
       :language: c++
       :caption: Calculating shape properties.
       :refnum: 21

    .. only:: oehtml

      .. admonition:: Download code

         :download:`shapeprops.cpp <../../../../sublibs/tklibs/shape/examples/shapeprops.cpp>`

..  oe:language:: java

    .. oe:source:: ShapeProps.java
       :language: java
       :caption: Calculating shape properties.
       :refnum: 21

    .. only:: oehtml

      .. admonition:: Download code

         :download:`ShapeProps.java <../../../../wrappers/java/examples/openeye/examples/oeshape/ShapeProps.java>`

..  oe:language:: python

    .. oe:source:: shapeprops.py
       :language: python
       :caption: Calculating shape properties.
       :refnum: 21

    .. only:: oehtml

      .. admonition:: Download code

         :download:`shapeprops.py <../../../../wrappers/python/examples/shape/shapeprops.py>`

..  oe:language:: csharp

    .. oe:source:: ShapeProps.cs
       :language: csharp
       :caption: Calculating shape properties.
       :refnum: 21

    .. only:: oehtml

      .. admonition:: Download code

         :download:`ShapeProps.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/ShapeProps.cs>`

Calculating excluded volume
----------------------------

This code demonstrates how to use the Shape toolkit to do an overlay
to a crystallographic ligand, then calculate the overlap of the database
molecule to the cognate protein. The output includes a new score **Rescore**
which is the **ShapeTanimotoCombo** penalized by the fraction overlap.

A description of the command line interface can be obtained by
executing the program with the --help argument.

.. oe:language:: c++

   .. code-block:: console

      prompt> excludevolume --help

.. oe:language:: python

   .. code-block:: console

      prompt> python excludevolume.py --help

.. oe:language:: java

   .. code-block:: console

      prompt> java ExcludeVolume --help

.. oe:language:: csharp

   .. code-block:: console

      prompt> ExcludeVolume --help

will generate the following output:

.. code-block:: console

      -q : Query file name
      -e : Protein to use as exclusion volume
      -d : Database file name
      -o : Output file name


.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`excludevolume.cpp <../../../../sublibs/tklibs/shape/examples/excludevolume.cpp>`
         and
         :download:`excludevolume.txt <../../../../sublibs/tklibs/shape/examples/excludevolume.txt>`
         interface file

   .. only:: oepdf

      .. oe:source:: excludevolume.cpp
         :language: c++

      with interface file

      .. oe:source:: excludevolume.txt
         :language: c++

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`excludevolume.py <../../../../wrappers/python/examples/shape/excludevolume.py>`

   .. only:: oepdf

      .. oe:source:: excludevolume.py
         :language: python


.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ExcludeVolume.java <../../../../wrappers/java/examples/openeye/examples/oeshape/ExcludedVolume.java>`
         and
         :download:`ExcludeVolume.txt <../../../../wrappers/java/examples/openeye/examples/oeshape/ExcludedVolume.txt>`
         interface file

   .. only:: oepdf

      .. oe:source:: ExcludedVolume.java
         :language: java

      with interface file

      .. oe:source:: ExcludedVolume.txt
         :language: java

.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ExcludeVolume.cs <../../../../wrappers/csharp/Csharp-Examples/OEShape/ExcludeVolume.cs>`

   .. only:: oepdf

      .. oe:source:: ExcludeVolume.cs
         :language: csharp
