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.

Listing 1: Simple overlap using Exact Overlap

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.


from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 3:
        oechem.OEThrow.Usage("%s <reffile> <fitfile>" % argv[0])

    reffs = oechem.oemolistream(argv[1])
    fitfs = oechem.oemolistream(argv[2])

    refmol = oechem.OEGraphMol()
    oechem.OEReadMolecule(reffs, refmol)

    # Prepare reference molecule for calculation
    # With default options this will remove any explicit hydrogens present
    prep = oeshape.OEOverlapPrep()
    prep.Prep(refmol)

    # Get appropriate function to calculate exact shape
    shapeFunc = oeshape.OEExactShapeFunc()
    shapeFunc.SetupRef(refmol)

    res = oeshape.OEOverlapResults()
    for fitmol in fitfs.GetOEGraphMols():
        prep.Prep(fitmol)
        shapeFunc.Overlap(fitmol, res)
        print("title: %s  exact tanimoto = %.2f" %
              (fitmol.GetTitle(), res.GetTanimoto()))


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

simpleoverlap.py

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.

Listing 2: Rescoring pre-aligned structures

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.


from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 4:
        oechem.OEThrow.Usage("%s <reffile> <rocs_hits_file> <output.sdf>" % argv[0])

    reffs = oechem.oemolistream(argv[1])
    fitfs = oechem.oemolistream(argv[2])
    outfs = oechem.oemolostream(argv[3])

    refmol = oechem.OEGraphMol()
    oechem.OEReadMolecule(reffs, refmol)

    # Get appropriate function to calculate analytic shape
    shapeFunc = oeshape.OEAnalyticShapeFunc()
    shapeFunc.SetupRef(refmol)

    res = oeshape.OEOverlapResults()
    for fitmol in fitfs.GetOEGraphMols():
        shapeFunc.Overlap(fitmol, res)
        oechem.OESetSDData(fitmol, "AnalyticTanimoto", "%.2f" % res.GetTanimoto())
        oechem.OEWriteMolecule(outfs, fitmol)


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

rescore.py

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.

Listing 3: Calculating color score

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.


from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 3:
        oechem.OEThrow.Usage("%s <reffile> <fitfile>" % argv[0])

    reffs = oechem.oemolistream(argv[1])
    fitfs = oechem.oemolistream(argv[2])

    refmol = oechem.OEGraphMol()
    oechem.OEReadMolecule(reffs, refmol)

    # Prepare reference molecule for calculation
    # With default options this will remove any explicit
    # hydrogens present, and add required color atoms
    prep = oeshape.OEOverlapPrep()
    prep.Prep(refmol)

    # Get appropriate function to calculate exact color
    colorFunc = oeshape.OEExactColorFunc()
    colorFunc.SetupRef(refmol)

    res = oeshape.OEOverlapResults()
    fitmol = oechem.OEGraphMol()
    while oechem.OEReadMolecule(fitfs, fitmol):
        prep.Prep(fitmol)
        colorFunc.Overlap(fitmol, res)
        print("title: %s  color score = %.2f" %
              (fitmol.GetTitle(), res.GetColorScore()))


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

coloroverlap.py

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.

Listing 4: Using color to add scores to pre-aligned molecules.

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.


from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 4:
        oechem.OEThrow.Usage("%s <reffile> <rocs_hits_file> <output.sdf>" % argv[0])

    reffs = oechem.oemolistream(argv[1])
    fitfs = oechem.oemolistream(argv[2])
    outfs = oechem.oemolostream(argv[3])

    refmol = oechem.OEGraphMol()
    oechem.OEReadMolecule(reffs, refmol)

    # Prepare reference molecule for calculation
    # With default options this will add required color atoms
    prep = oeshape.OEOverlapPrep()
    prep.Prep(refmol)

    # Get appropriate function to calculate analytic color
    colorFunc = oeshape.OEAnalyticColorFunc()
    colorFunc.SetupRef(refmol)

    res = oeshape.OEOverlapResults()
    for fitmol in fitfs.GetOEGraphMols():
        prep.Prep(fitmol)
        colorFunc.Overlap(fitmol, res)
        oechem.OESetSDData(fitmol, "AnalyticColorTanimoto", "%.2f" % res.GetColorTanimoto())
        oeshape.OERemoveColorAtoms(fitmol)
        oechem.OEWriteMolecule(outfs, fitmol)
        print("Fit Title: %s  Color Tanimoto: %.2f" %
              (fitmol.GetTitle(), res.GetColorTanimoto()))


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

colorscore.py

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 OEColorForceField object can be created using one of the built-in types, then the interactions can be cleared using OEColorForceField.ClearInteractions and subsequent user interactions added with 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:

Listing 5: Using ImplicitMillsDean with user interactions.

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.


from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 3:
        oechem.OEThrow.Usage("%s <reffile> <overlayfile>" % argv[0])

    reffs = oechem.oemolistream(argv[1])
    fitfs = oechem.oemolistream(argv[2])

    refmol = oechem.OEGraphMol()
    oechem.OEReadMolecule(reffs, refmol)

    # Modify ImplicitMillsDean color force field by
    # adding user defined color interactions
    cff = oeshape.OEColorForceField()
    if not cff.Init(oeshape.OEColorFFType_ImplicitMillsDean):
        oechem.OEThrow.Error("Unable to inititialize color forcefield")
    cff.ClearInteractions()
    donorType = cff.GetType("donor")
    accepType = cff.GetType("acceptor")
    cff.AddInteraction(donorType, donorType, "gaussian", -1.0, 1.0)
    cff.AddInteraction(accepType, accepType, "gaussian", -1.0, 1.0)

    # Prepare reference molecule for calculation
    # With default options this will add required color atoms
    # Set the modified color force field for addignment
    prep = oeshape.OEOverlapPrep()
    if not prep.SetColorForceField(cff):
        oechem.OEThrow.Error("Unable to set color forcefield")
    prep.Prep(refmol)

    # Get appropriate function to calculate exact color
    # Set appropriate options to use the user defined color
    options = oeshape.OEColorOptions()
    if not options.SetColorForceField(cff):
        oechem.OEThrow.Error("Unable to set color forcefield")
    colorFunc = oeshape.OEExactColorFunc(options)
    colorFunc.SetupRef(refmol)

    res = oeshape.OEOverlapResults()
    for fitmol in fitfs.GetOEGraphMols():
        prep.Prep(fitmol)
        colorFunc.Overlap(fitmol, res)
        print("Fit Title: %s  Color Tanimoto: %.2f" %
              (fitmol.GetTitle(), res.GetColorTanimoto()))


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

/usercolor.py

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.

Listing 6: Calculating both shape and color overlap

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.


from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 3:
        oechem.OEThrow.Usage("%s <reffile> <fitfile>" % argv[0])

    reffs = oechem.oemolistream(argv[1])
    fitfs = oechem.oemolistream(argv[2])

    refmol = oechem.OEGraphMol()
    oechem.OEReadMolecule(reffs, refmol)

    # Prepare reference molecule for calculation
    # With default options this will remove any explicit
    # hydrogens present and add color atoms
    prep = oeshape.OEOverlapPrep()
    prep.Prep(refmol)

    # Get appropriate function to calculate both shape and color
    # By default the OEOverlapFunc contains OEGridShapeFunc for shape
    # and OEExactColorFunc for color
    func = oeshape.OEOverlapFunc()
    func.SetupRef(refmol)

    res = oeshape.OEOverlapResults()
    for fitmol in fitfs.GetOEGraphMols():
        prep.Prep(fitmol)
        func.Overlap(fitmol, res)
        print("title: %s  tanimoto combo = %.2f shape tanimoto = %.2f color tanimoto = %.2f" %
              (fitmol.GetTitle(), res.GetTanimotoCombo(),
               res.GetTanimoto(), res.GetColorTanimoto()))


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

overlapcolor.py

ROCS

The high-level 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.

Listing 7: Finding best hit conformer pair

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.


from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 4:
        oechem.OEThrow.Usage("%s <reffile> <fitfile> <outfile>" % argv[0])

    reffs = oechem.oemolistream(sys.argv[1])
    fitfs = oechem.oemolistream(sys.argv[2])
    outfs = oechem.oemolostream(sys.argv[3])

    refmol = oechem.OEMol()
    oechem.OEReadMolecule(reffs, refmol)

    fitmol = oechem.OEMol()
    oechem.OEReadMolecule(fitfs, fitmol)

    res = oeshape.OEROCSResult()
    oeshape.OEROCSOverlay(res, refmol, fitmol)
    outmol = res.GetOverlayConf()

    oechem.OEWriteMolecule(outfs, outmol)
    print("Tanimoto combo = %.2f" % res.GetTanimotoCombo())


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

besthit.py

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.

Listing 8: Finding top ROCS hits

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.


from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 5:
        oechem.OEThrow.Usage("%s <reffile> <fitfile> <outfile> <nhits>" % argv[0])

    reffs = oechem.oemolistream(sys.argv[1])
    fitfs = oechem.oemolistream(sys.argv[2])
    outfs = oechem.oemolostream(sys.argv[3])
    nhits = int(sys.argv[4])

    refmol = oechem.OEMol()
    oechem.OEReadMolecule(reffs, refmol)

    # Setup OEROCS with specified number of best hits
    options = oeshape.OEROCSOptions()
    options.SetNumBestHits(nhits)
    rocs = oeshape.OEROCS(options)
    rocs.SetDatabase(fitfs)
    for res in rocs.Overlay(refmol):
        outmol = res.GetOverlayConf()
        oechem.OEWriteMolecule(outfs, outmol)
        print("title: %s  tanimoto combo = %.2f" % (outmol.GetTitle(), res.GetTanimotoCombo()))


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

tophits.py

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.

Listing 9: Finding top ROCS hits with multiple conformers

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.


from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 5:
        oechem.OEThrow.Usage("%s <reffile> <fitfile> <outfile> <confsperhit>" % argv[0])

    reffs = oechem.oemolistream(sys.argv[1])
    fitfs = oechem.oemolistream(sys.argv[2])
    outfs = oechem.oemolostream(sys.argv[3])
    nconfs = int(sys.argv[4])

    refmol = oechem.OEMol()
    oechem.OEReadMolecule(reffs, refmol)

    # Setup OEROCS to provide 3 best hits
    # with the specified number of conformers per hit
    options = oeshape.OEROCSOptions()
    options.SetNumBestHits(3)
    options.SetConfsPerHit(nconfs)
    rocs = oeshape.OEROCS(options)
    rocs.SetDatabase(fitfs)
    for res in rocs.Overlay(refmol):
        outmol = res.GetOverlayConfs()
        oechem.OEWriteMolecule(outfs, outmol)
        print("title: %s  tanimoto combo = %.2f" % (outmol.GetTitle(), res.GetTanimotoCombo()))


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

tophitsconf.py

Overlay Optimization

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

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.

Listing 10: Getting the best scores from OEMultiRefOverlay.

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.

# This example reads in a reference molecule and a few fit
# molecules, performs overlay optimization, sorts the results
# in Tanimoto order, and shows the single best result.
# With the default options, OEOverlay optimizes both shape and color.


import sys

from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 3:
        oechem.OEThrow.Usage("%s <reffile> <fitfile>" % argv[0])

    reffs = oechem.oemolistream(argv[1])
    fitfs = oechem.oemolistream(argv[2])

    refmol = oechem.OEMol()
    oechem.OEReadMolecule(reffs, refmol)
    print("Ref. Title:", refmol.GetTitle(), "Num Confs:", refmol.NumConfs())

    # Prepare reference molecule for calculation
    # With default options this will remove any explicit
    # hydrogens present and add color atoms
    prep = oeshape.OEOverlapPrep()
    prep.Prep(refmol)

    overlay = oeshape.OEMultiRefOverlay()
    overlay.SetupRef(refmol)

    for fitmol in fitfs.GetOEMols():
        prep.Prep(fitmol)
        score = oeshape.OEBestOverlayScore()
        overlay.BestOverlay(score, fitmol, oeshape.OEHighestTanimoto())
        print("Fit Title: %-4s FitConfIdx: %-4d RefConfIdx: %-4d tanimoto combo: %.2f"
              % (fitmol.GetTitle(), score.GetFitConfIdx(),
                 score.GetRefConfIdx(), score.GetTanimotoCombo()))


if __name__ == "__main__":
    sys.exit(main(sys.argv))

Download code

overlaybestres.py

Listing 10b: Getting the best scores from OEMultiRefOverlay (multi-threaded version)

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.

# This is a multi-threaded version of the example that reads in a
# reference molecule and a few fit molecules, performs overlay optimization,
# and shows the single best result.
# With the default options, OEOverlay optimizes both shape and color.

import sys
from openeye import oechem
from openeye import oeshape
from threading import Thread


class MultiCoreOverlay(Thread):
    def __init__(self, refmol, ifs):
        Thread.__init__(self)
        self._prep = oeshape.OEOverlapPrep()
        self._prep.Prep(refmol)
        self._overlay = oeshape.OEMultiRefOverlay()
        self._overlay.SetupRef(refmol)
        self._ifs = ifs

    def run(self):
        for fitmol in self._ifs.GetOEMols():
            self._prep.Prep(fitmol)
            score = oeshape.OEBestOverlayScore()
            self._overlay.BestOverlay(score, fitmol, oeshape.OEHighestTanimoto())
            print("Fit Title: %-4s FitConfIdx: %-4d RefConfIdx: %-4d tanimoto combo: %.2f"
                  % (fitmol.GetTitle(), score.GetFitConfIdx(),
                     score.GetRefConfIdx(), score.GetTanimotoCombo()))


def main(argv=[__name__]):
    if len(argv) != 3:
        oechem.OEThrow.Usage("%s <reffile> <fitfile>" % argv[0])

    reffs = oechem.oemolistream(argv[1])
    refmol = oechem.OEMol()
    oechem.OEReadMolecule(reffs, refmol)
    print("Ref. Title:", refmol.GetTitle(), "Num Confs:", refmol.NumConfs())

    fitfs = oechem.oemolithread(sys.argv[2])

    thrds = []
    for i in range(oechem.OEGetNumProcessors()):
        thrd = MultiCoreOverlay(refmol, fitfs)
        thrd.start()
        thrds.append(thrd)

    for thrd in thrds:
        thrd.join()

    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

Download code

multicorebestoverlay.py

All Optimization Results

This example repeats the above, but uses 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. OEBestOverlayResults holds the results of a single pair of conformers. It contains a set of OEBestOverlayScore objects, one for each starting position.

This example uses 2 iterators to show all the results.

Listing 11: Getting all the scores from OEMultiRefOverlay.

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.

# This example reads in a reference molecule and a few fit
# molecules, performs overlay optimization, and uses 2 iterators to
# show all the results.
# With the default options, OEOverlay optimizes both shape and color.


from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 3:
        oechem.OEThrow.Usage("%s <reffile> <fitfile>" % argv[0])

    reffs = oechem.oemolistream(argv[1])
    fitfs = oechem.oemolistream(argv[2])

    refmol = oechem.OEMol()
    oechem.OEReadMolecule(reffs, refmol)
    print("Ref. Title:", refmol.GetTitle(), "Num Confs:", refmol.NumConfs())

    # Prepare reference molecule for calculation
    # With default options this will remove any explicit
    # hydrogens present and add color atoms
    prep = oeshape.OEOverlapPrep()
    prep.Prep(refmol)

    overlay = oeshape.OEMultiRefOverlay()
    overlay.SetupRef(refmol)

    for fitmol in fitfs.GetOEMols():
        print("Fit Title:", fitmol.GetTitle(), "Num Confs:", fitmol.NumConfs())

        prep.Prep(fitmol)
        resCount = 0

        # double loop over results and scores to obtain all scores
        for res in overlay.Overlay(fitmol):
            for score in res.GetScores():
                print("FitConfIdx: %-4d RefConfIdx: %-4d tanimoto combo: %.2f"
                      % (score.GetFitConfIdx(), score.GetRefConfIdx(), score.GetTanimotoCombo()))
                resCount += 1

        print(resCount, "results returned")


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

overlayallres.py

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 OESortOverlayScores function is used to turn the double iterator as shown in the example above into a single iterator of OEBestOverlayScore. Note that the third argument is a functor used to sort the list, such that in this next example, we get one 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 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.

Listing 12: Writing few aligned structures from OEMultiRefOverlay.

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.

# This example reads in a reference molecule and a few fit
# molecules, performs overlay optimization, sorts the results
# in tanimoto order, shows the user specified number of
# results, and saves the overlayed structures.
# With the default options, OEOverlay optimizes both shape and color.


from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 5:
        oechem.OEThrow.Usage("%s <reffile> <fitfile> <out.sdf> <keepsize>" % argv[0])

    reffs = oechem.oemolistream(argv[1])
    fitfs = oechem.oemolistream(argv[2])
    outfs = oechem.oemolostream(argv[3])
    keepsize = int(argv[4])

    refmol = oechem.OEMol()
    oechem.OEReadMolecule(reffs, refmol)
    print("Ref. Title:", refmol.GetTitle(), "Num Confs:", refmol.NumConfs())

    # Prepare reference molecule for calculation
    # With default options this will remove any explicit
    # hydrogens present and add color atoms
    prep = oeshape.OEOverlapPrep()
    prep.Prep(refmol)

    overlay = oeshape.OEMultiRefOverlay()
    overlay.SetupRef(refmol)

    for fitmol in fitfs.GetOEMols():
        print("Fit Title:", fitmol.GetTitle(), "Num Confs:", fitmol.NumConfs())

        prep.Prep(fitmol)
        resCount = 0

        # Sort all scores according to highest tanimoto
        scoreiter = oeshape.OEBestOverlayScoreIter()
        oeshape.OESortOverlayScores(scoreiter, overlay.Overlay(fitmol), oeshape.OEHighestTanimoto())

        for score in scoreiter:
            outmol = oechem.OEGraphMol(fitmol.GetConf(oechem.OEHasConfIdx(score.GetFitConfIdx())))
            score.Transform(outmol)

            oechem.OESetSDData(outmol, "RefConfIdx", "%-d" % score.GetRefConfIdx())
            oechem.OESetSDData(outmol, "tanimoto combo", "%-.3f" % score.GetTanimotoCombo())

            oechem.OEWriteMolecule(outfs,
                                   refmol.GetConf(oechem.OEHasConfIdx(score.GetRefConfIdx())))
            oeshape.OERemoveColorAtoms(outmol)
            oechem.OEWriteMolecule(outfs, outmol)

            resCount += 1

            # Break at the user specified size
            if resCount == keepsize:
                break

        print(resCount, "results returned")


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

overlaystruct.py

Working with Shape Query

This section of examples shows the use of a 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.

Listing 13: Creating a shape query.

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.


from openeye import oechem, oeshape


def main(argv=[__name__]):
    opts = oechem.OESimpleAppOptions("CreateQuery", oechem.OEFileStringType_Mol3D, "sq")
    if oechem.OEConfigureOpts(opts, argv, False) == oechem.OEOptsConfigureStatus_Help:
        return 0

    ifs = oechem.oemolistream()
    if not ifs.open(opts.GetInFile()):
        oechem.OEThrow.Fatal("Unable to open %s for reading" % opts.GetInFile())

    ofs = oechem.oeofstream()
    if not ofs.open(opts.GetOutFile()):
        oechem.OEThrow.Fatal("Unable to open %s for writing" % opts.GetOutFile())

    cff = oeshape.OEColorForceField()
    cff.Init(oeshape.OEColorFFType_ImplicitMillsDean)

    mol = oechem.OEGraphMol()
    while oechem.OEReadMolecule(ifs, mol):
        query = oeshape.OEShapeQuery()
        if oeshape.OEMol2Query(query, mol, cff):
            oeshape.OEWriteShapeQuery(ofs, query)
        else:
            oechem.OEThrow.Warning("Failed to create query from: %s" % mol.GetTitle())

    return 0


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

createquery.py

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.

Listing 14: Overlap with a shape query

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.


from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 3:
        oechem.OEThrow.Usage("%s <queryfile> <fitfile>" % argv[0])

    if oechem.OEGetFileExtension(sys.argv[1]) != "sq":
        oechem.OEThrow.Fatal("Requires a shape query .sq input file format")

    query = oeshape.OEShapeQuery()
    oeshape.OEReadShapeQuery(argv[1], query)

    # Get appropriate function to calculate both shape and color
    # By default the OEOverlapFunc contains OEGridShapeFunc for shape
    # and OEExactColorFunc for color
    func = oeshape.OEOverlapFunc()
    func.SetupRef(query)

    res = oeshape.OEOverlapResults()
    fitfs = oechem.oemolistream(argv[2])
    prep = oeshape.OEOverlapPrep()
    for fitmol in fitfs.GetOEGraphMols():
        prep.Prep(fitmol)
        func.Overlap(fitmol, res)
        print("title: %s  tanimoto combo = %.2f shape tanimoto = %.2f color tanimoto = %.2f" %
              (fitmol.GetTitle(), res.GetTanimotoCombo(),
               res.GetTanimoto(), res.GetColorTanimoto()))


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

overlapquery.py

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.

Listing 15: Finding top ROCS hits against a query

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.


from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 5:
        oechem.OEThrow.Usage("%s <queryfile> <fitfile> <outfile> <nhits>" % argv[0])

    if oechem.OEGetFileExtension(sys.argv[1]) != "sq":
        oechem.OEThrow.Fatal("Requires a shape query .sq input file format")

    fitfs = oechem.oemolistream(sys.argv[2])
    outfs = oechem.oemolostream(sys.argv[3])
    nhits = int(sys.argv[4])

    query = oeshape.OEShapeQuery()
    oeshape.OEReadShapeQuery(sys.argv[1], query)

    # Setup OEROCS with specified number of best hits
    options = oeshape.OEROCSOptions()
    options.SetNumBestHits(nhits)
    rocs = oeshape.OEROCS(options)

    rocs.SetDatabase(fitfs)
    for res in rocs.Overlay(query):
        outmol = res.GetOverlayConf()
        oechem.OEWriteMolecule(outfs, outmol)
        print("title: %s  tanimoto combo = %.2f" % (outmol.GetTitle(), res.GetTanimotoCombo()))


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

tophitsquery.py

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 \(\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 OEHermite class. 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.

Listing 16: Expanding a molecular shape into Hermite polynomials

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.

import sys
from openeye import oechem
from openeye import oeshape
from openeye import oegrid


def main(argv=[__name__]):
    itf = oechem.OEInterface(InterfaceData, argv)

    NPolyMax = itf.GetInt("-NPolyMax")
    gridspacing = itf.GetFloat("-gridspacing")

    ifname = itf.GetString("-inputfile")
    ofname = itf.GetString("-outputgrid")\

    ifs = oechem.oemolistream()
    if (not ifs.open(ifname)):
        oechem.OEThrow.Fatal("Unable to open %s for reading" % ifname)

    if (not ofname.endswith(".grd")):
        oechem.OEThrow.Fatal("Output grid file extension hast to be '.grd' ")

    mol = oechem.OEMol()

    if (not oechem.OEReadMolecule(ifs, mol)):
        oechem.OEThrow.Fatal("Unable to read molecule in %s" % ifname)

    prep = oeshape.OEOverlapPrep()
    prep.SetAssignColor(False)
    prep.Prep(mol)
    transfm = oechem.OETrans()
    oeshape.OEOrientByMomentsOfInertia(mol, transfm)

    hermiteoptions = oeshape.OEHermiteOptions()
    hermiteoptions.SetNPolyMax(NPolyMax)
    hermiteoptions.SetUseOptimalLambdas(True)

    hermite = oeshape.OEHermite(hermiteoptions)

    if (not hermite.Setup(mol)):
        oechem.OEThrow.Fatal("Was not able to Setup the molecule for the OEHermite class.")

    hopts = hermite.GetOptions()
    print("Best lambdas found X=" + str(hopts.GetLambdaX()) + "  Y="
          + str(hopts.GetLambdaY()) + "  Z=" + str(hopts.GetLambdaZ()))

    print("Hermite self-overlap=", hermite.GetSelfOverlap())

    basis_size = int((NPolyMax+1)*(NPolyMax+2)*(NPolyMax+3)/6)
    coeffs = oechem.OEDoubleVector(basis_size)
    hermite.GetCoefficients(coeffs)
    NPolyMaxstring = str(NPolyMax)
    print("Hermite coefficients f_{l,m,n} in the following order l = 0..."
          + NPolyMaxstring + ", m = 0..." + NPolyMaxstring+"-l, n = " + NPolyMaxstring + "-l-m :")

    for x in coeffs:
        print(str(x) + " "),

    grid = oegrid.OEScalarGrid()

    hermite.CreateGrid(grid, gridspacing, transfm)

    if (not oegrid.OEWriteGrid(ofname, grid)):
        oechem.OEThrow.Fatal("Unable to write grid file")

    return 0


#############################################################################
InterfaceData = '''
!BRIEF [-inputfile] <InputFileName> [-outputgrid] <OutputGridFileName> [-NPolyMax] <NPolyMax> \
[-numgridpoints] <numgridpoints> [-gridspacing] <gridspacing>

!CATEGORY "input/output options :" 1

  !PARAMETER -inputfile 1
    !ALIAS -in
    !TYPE string
    !REQUIRED true
    !BRIEF Filename of the input molecule
    !KEYLESS 1
  !END

  !PARAMETER -outputgrid 2
  !ALIAS -out
    !TYPE string
    !REQUIRED true
    !BRIEF Filename of the output Hermite grid (needs to have .grd file extension)
    !KEYLESS 2
  !END

!END

!CATEGORY "Hermite options :" 2

  !PARAMETER -NPolyMax 3
    !ALIAS -NP
    !TYPE int
    !REQUIRED false
    !DEFAULT 5
    !LEGAL_RANGE 0 30
    !BRIEF Resolution parameter of Hermite Prep
    !KEYLESS 3
  !END


  !PARAMETER -gridspacing 4
    !ALIAS -gs
    !TYPE float
    !REQUIRED false
    !DEFAULT 1.0
    !LEGAL_RANGE 0.01 10.0
    !BRIEF Grid spacing of the output Hermite grid
    !KEYLESS 4
  !END

!END
'''

#############################################################################
if __name__ == "__main__":
    sys.exit(main(sys.argv))

Download code

hermite-expansion.py

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_MAX is used to vary the NPolyMax parameter and 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.

Listing 17: Calculating shape Tanimoto using Hermite expansion

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.

import sys
from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    itf = oechem.OEInterface(InterfaceData, argv)

    NPolyMax_MAX = itf.GetInt("-NPolyMax_MAX")

    ifrefname = itf.GetString("-inputreffile")
    iffitname = itf.GetString("-inputfitfile")
    ofname = itf.GetString("-outputfile")

    ifsref = oechem.oemolistream()
    if not ifsref.open(ifrefname):
        oechem.OEThrow.Fatal("Unable to open %s for reading" % ifrefname)

    ifsfit = oechem.oemolistream()
    if not ifsfit.open(iffitname):
        oechem.OEThrow.Fatal("Unable to open %s for reading" % iffitname)

    refmol = oechem.OEMol()

    if not oechem.OEReadMolecule(ifsref, refmol):
        oechem.OEThrow.Fatal("Unable to read molecule in %s" % ifrefname)

    prep = oeshape.OEOverlapPrep()
    prep.SetAssignColor(False)
    prep.Prep(refmol)
    reftransfm = oechem.OETrans()
    oeshape.OEOrientByMomentsOfInertia(refmol, reftransfm)

    hermiteoptionsref = oeshape.OEHermiteOptions()
    hermiteoptionsref.SetNPolyMax(NPolyMax_MAX)
    hermiteoptionsref.SetUseOptimalLambdas(True)

    hermiteoptionsfit = oeshape.OEHermiteOptions()
    hermiteoptionsfit.SetNPolyMax(NPolyMax_MAX)
    hermiteoptionsfit.SetUseOptimalLambdas(True)

    hermitefunc = oeshape.OEHermiteShapeFunc(hermiteoptionsref, hermiteoptionsfit)

    options = oeshape.OEOverlayOptions()
    options.SetOverlapFunc(hermitefunc)
    overlay = oeshape.OEOverlay(options)
    overlay.SetupRef(refmol)

    ofs = oechem.oemolostream()
    if not ofs.open(ofname):
        oechem.OEThrow.Fatal("Unable to open %s for writing" % ofname)

    transfm = oechem.OETrans()
    fitmol = oechem.OEMol()
    while oechem.OEReadMolecule(ifsfit, fitmol):
        prep.Prep(fitmol)
        oeshape.OEOrientByMomentsOfInertia(fitmol, transfm)

        score = oeshape.OEBestOverlayScore()
        overlay.BestOverlay(score, fitmol)
        print("Hermite Tanimoto = ", score.GetTanimoto())

        oechem.OESetSDData(fitmol, "HermiteTanimoto_"+str(NPolyMax_MAX), str(score.GetTanimoto()))
        score.Transform(fitmol)

        # Transform from the inertial frame to the original reference mol frame
        reftransfm.Transform(fitmol)
        oeshape.OERemoveColorAtoms(fitmol)
        oechem.OEWriteMolecule(ofs, fitmol)


#############################################################################
InterfaceData = '''
!BRIEF [-inputreffile] <InputReferenceFileName> [-inputfitfile] <InputFitFileName> \
[-outputfile] <OutputFileName> [-NPolyMax_MAX] <NPolyMax_MAX>

!CATEGORY "input/output options :" 1

  !PARAMETER -inputreffile 1
    !ALIAS -inref
    !TYPE string
    !REQUIRED true
    !BRIEF Input file name with reference molecule (will only read the first molecule).
    !KEYLESS 1
  !END
  !PARAMETER -inputfitfile 2
    !ALIAS -infit
    !TYPE string
    !REQUIRED true
    !BRIEF Input file name with fit molecules
    !KEYLESS 2
  !END
  !PARAMETER -outputfile 3
    !ALIAS -out
    !TYPE string
    !REQUIRED true
    !BRIEF Output file name
    !KEYLESS 3
  !END

!END

!CATEGORY "Hermite options :" 2

  !PARAMETER -NPolyMax_MAX 4
    !ALIAS -NP_MAX
    !TYPE int
    !REQUIRED false
    !DEFAULT 5
    !LEGAL_RANGE 0 30
    !BRIEF Maximum value of the parameter of the NPolyMax parameter of the Hermite prep
    !KEYLESS 4
  !END

!END
'''

#############################################################################
if __name__ == "__main__":
    sys.exit(main(sys.argv))

Download code

hermite-tanimoto.py

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 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.

Listing 18: Flexible overlay optimization

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.

# This example reads in a reference molecule and a few fit
# molecules, performs overlay optimization, sorts the results
# in Tanimoto order, and shows the single best result.
# With the default options, OEOverlay optimizes both shape and color.


import sys

from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    overlayOpts = oeshape.OEFlexiOverlayOptions()
    opts = oechem.OERefInputAppOptions(overlayOpts, "FlexiOverlay", oechem.OEFileStringType_Mol3D,
                                       oechem.OEFileStringType_Mol3D, oechem.OEFileStringType_Mol3D, "-refmol")
    if oechem.OEConfigureOpts(opts, argv, False) == oechem.OEOptsConfigureStatus_Help:
        return 0
    overlayOpts.UpdateValues(opts)

    ifs = oechem.oemolistream()
    if not ifs.open(opts.GetInFile()):
        oechem.OEThrow.Fatal("Unable to open %s for reading" % opts.GetInFile())

    rfs = oechem.oemolistream()
    if not rfs.open(opts.GetRefFile()):
        oechem.OEThrow.Fatal("Unable to open %s for reading" % opts.GetRefFile())

    ofs = oechem.oemolostream()
    if not ofs.open(opts.GetOutFile()):
        oechem.OEThrow.Fatal("Unable to open %s for writing" % opts.GetOutFile())

    refmol = oechem.OEMol()
    oechem.OEReadMolecule(rfs, refmol)
    print("Ref. Title:", refmol.GetTitle())

    overlay = oeshape.OEFlexiOverlay(overlayOpts)
    overlay.SetupRef(refmol)

    for fitmol in ifs.GetOEMols():
        results = overlay.Overlay(fitmol)
        for res, conf in zip(results, fitmol.GetConfs()):
            print("Fit Title: %-4s Tanimoto Combo: %.2f Energy: %2f"
                  % (fitmol.GetTitle(), res.GetTanimotoCombo(), res.GetInternalEnergy()))
            oechem.OESetSDData(conf, "Tanimoto Combo", "%.2f" % res.GetTanimotoCombo())
            oechem.OESetSDData(conf, "Energy", "%.2f" % res.GetInternalEnergy())
        oechem.OEWriteMolecule(ofs, fitmol)



if __name__ == "__main__":
    sys.exit(main(sys.argv))

Download code

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.

Listing 19: Flexible best overlay

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.

# This example reads in a reference molecule and a few fit
# molecules, performs overlay optimization, sorts the results
# in Tanimoto order, and shows the single best result.
# With the default options, OEOverlay optimizes both shape and color.


import sys

from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    overlayOpts = oeshape.OEFlexiOverlayOptions()
    opts = oechem.OERefInputAppOptions(overlayOpts, "FlexiBestOverlay", oechem.OEFileStringType_Mol3D,
                                       oechem.OEFileStringType_Mol3D, oechem.OEFileStringType_Mol3D, "-refmol")
    if oechem.OEConfigureOpts(opts, argv, False) == oechem.OEOptsConfigureStatus_Help:
        return 0
    overlayOpts.UpdateValues(opts)

    ifs = oechem.oemolistream()
    if not ifs.open(opts.GetInFile()):
        oechem.OEThrow.Fatal("Unable to open %s for reading" % opts.GetInFile())

    rfs = oechem.oemolistream()
    if not rfs.open(opts.GetRefFile()):
        oechem.OEThrow.Fatal("Unable to open %s for reading" % opts.GetRefFile())

    ofs = oechem.oemolostream()
    if not ofs.open(opts.GetOutFile()):
        oechem.OEThrow.Fatal("Unable to open %s for writing" % opts.GetOutFile())

    refmol = oechem.OEMol()
    oechem.OEReadMolecule(rfs, refmol)
    print("Ref. Title:", refmol.GetTitle())

    overlay = oeshape.OEFlexiOverlay(overlayOpts)
    overlay.SetupRef(refmol)

    for fitmol in ifs.GetOEMols():
        results = oeshape.OEFlexiOverlapResults()
        if overlay.BestOverlay(results, fitmol):
            print("Fit Title: %-4s Tanimoto Combo: %.2f Energy: %2f"
                  % (fitmol.GetTitle(), results.GetTanimotoCombo(), results.GetInternalEnergy()))
            oechem.OESetSDData(fitmol, "Tanimoto Combo", "%.2f" % results.GetTanimotoCombo())
            oechem.OESetSDData(fitmol, "Energy", "%.2f" % results.GetInternalEnergy())
            oechem.OEWriteMolecule(ofs, fitmol)
        else:
            print("Failed Title: %-4s" % (fitmol.GetTitle()))


if __name__ == "__main__":
    sys.exit(main(sys.argv))

Download code

flexi_overlay.py

Advanced Examples

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.

Listing 20: Calculating NxN scores.

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.


from openeye import oechem
from openeye import oeshape


def oneConf(conf, prep, filename, csvfile):
    csvfile.write("%s_%d" % (conf.GetTitle(), conf.GetIdx()))
    refmol = oechem.OEGraphMol(conf)

    options = oeshape.OEOverlayOptions()
    options.SetOverlapFunc(oeshape.OEGridShapeFunc())
    overlay = oeshape.OEOverlay(options)
    overlay.SetupRef(refmol)

    bfs = oechem.oemolistream(filename)
    fitmol = oechem.OEMol()
    while oechem.OEReadMolecule(bfs, fitmol):
        prep.Prep(fitmol)
        scoreiter = oeshape.OEBestOverlayScoreIter()
        oeshape.OESortOverlayScores(scoreiter, overlay.Overlay(fitmol), oeshape.OEHighestTanimoto(), 1, True)

        for score in scoreiter:
            csvfile.write(",%.2f" % score.GetTanimoto())
    csvfile.write("\n")


def genHeader(filename, csvfile):
    csvfile.write("name")
    ifs = oechem.oemolistream(filename)
    mol = oechem.OEMol()
    while oechem.OEReadMolecule(ifs, mol):
        for conf in mol.GetConfs():
            csvfile.write(",%s_%d" % (conf.GetTitle(), conf.GetIdx()))
    csvfile.write("\n")


def main(argv=[__name__]):
    if len(argv) != 3:
        oechem.OEThrow.Usage("%s <infile> <csvfile>" % argv[0])

    csvfile = open(argv[2], "w")
    genHeader(sys.argv[1], csvfile)

    prep = oeshape.OEOverlapPrep()
    prep.SetAssignColor(False)
    afs = oechem.oemolistream(argv[1])
    for molA in afs.GetOEMols():
        prep.Prep(molA)
        print(molA.GetTitle())
        for conf in molA.GetConfs():
            oneConf(conf, prep, sys.argv[1], csvfile)


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

nxnshape.py

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 OECalcVolume.

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

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

Listing 21: Calculating shape properties.

#!/usr/bin/env python
# (C) 2022 Cadence Design Systems, Inc. (Cadence) 
# All rights reserved.
# TERMS FOR USE OF SAMPLE CODE The software below ("Sample Code") is
# provided to current licensees or subscribers of Cadence products or
# SaaS offerings (each a "Customer").
# Customer is hereby permitted to use, copy, and modify the Sample Code,
# subject to these terms. Cadence claims no rights to Customer's
# modifications. Modification of Sample Code is at Customer's sole and
# exclusive risk. Sample Code may require Customer to have a then
# current license or subscription to the applicable Cadence offering.
# THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED.  OPENEYE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
# liable for any damages or liability in connection with the Sample Code
# or its use.

from openeye import oechem
from openeye import oeshape


def main(argv=[__name__]):
    if len(argv) != 2:
        oechem.OEThrow.Usage("%s <infile>" % argv[0])

    ifs = oechem.oemolistream(argv[1])

    for mol in ifs.GetOEGraphMols():
        oechem.OEThrow.Info("              Title: %s" % mol.GetTitle())
        oechem.OEThrow.Info("             Volume: %8.2f" % oeshape.OECalcVolume(mol))
        oechem.OEThrow.Info("Volume: (without H): %8.2f\n" % oeshape.OECalcVolume(mol, False))

        smult = oeshape.OECalcShapeMultipoles(mol)

        oechem.OEThrow.Info("  Steric multipoles:")
        oechem.OEThrow.Info("           monopole: %8.2f" % smult[0])
        oechem.OEThrow.Info("        quadrupoles: %8.2f %8.2f %8.2f"
                            % (smult[1], smult[2], smult[3]))
        oechem.OEThrow.Info("          octopoles:")
        oechem.OEThrow.Info("                xxx: %8.2f  yyy: %8.2f  zzz: %8.2f"
                            % (smult[4], smult[5], smult[6]))
        oechem.OEThrow.Info("                xxy: %8.2f  xxz: %8.2f  yyx: %8.2f"
                            % (smult[7], smult[8], smult[9]))
        oechem.OEThrow.Info("                yyz: %8.2f  zzx: %8.2f  zzy: %8.2f"
                            % (smult[10], smult[11], smult[12]))
        oechem.OEThrow.Info("                xyz: %8.2f\n" % smult[13])


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv))

Download code

shapeprops.py

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.

prompt> python excludevolume.py --help

will generate the following output:

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

Download code

excludevolume.py