Shape Toolkit, C++ Programming Manual
Shape Toolkit, C++ Programming Manual
Shape Toolkit, C++ Programming Manual
Create successful ePaper yourself
Turn your PDF publications into a flip-book with our unique Google optimized e-Paper software.
<strong>Shape</strong> <strong>Toolkit</strong><strong>C++</strong> <strong>Programming</strong> <strong>Manual</strong>version 1.7.0OpenEye Scientific Software, Inc.June 4, 20089 Bisbee Ct, Suite DSanta Fe, NM 87508www.eyesopen.comsupport@eyesopen.com
Copyright c○ 1997-2008 OpenEye Scientific Software, Santa Fe, New Mexico. All rights reserved.All rights reserved. This material contains proprietary information of OpenEye Scientific Software. Use of copyrightnotice is precautionary only and does not imply publication or disclosure.The information supplied in this document is believed to be true but no liability is assumed for its use or theinfringement of the rights of others resulting from its use. Information in this document is subject to changewithout notice and does not represent a commitment on the part of OpenEye Scientific Software.This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise,be lent, re-sold, hired out or otherwise circulated without OpenEye Scientific Software’s prior consent, in anyform of packaging or cover other than that in which it was produced. No part of this manual or accompanyingdocumentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD orother medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording orotherwise for any purpose other than for the purchaser’s personal use without a legal agreement or other writtenpermission granted by OpenEye.This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facilitynor the flight, navigation or communication of aircraft or ground support equipment. OpenEye Scientific software,shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreakof war.Windows is a registered trademark of Microsoft Corporation. Apple and Macintosh are registered trademarks ofApple Computer, Inc. AIX and IBM are registered trademarks of International Business Machines Corporation.UNIX is a registered trademark of the Open Group. RedHat is a registered trademark of RedHat, Inc. Linux isa registered trademark of Linus Torvalds. Alpha is a trademark of Digital Equipment Corporation. SPARC is aregistered trademark of SPARC International Inc.SYBYL is a registered trademark of TRIPOS, Inc. MDL is a registered trademark and ISIS is a trademark ofMDL Information Systems, Inc. SMILES, SMARTS, and SMIRKS may be trademarks of Daylight ChemicalInformation Systems. Macromodel is a trademark of Schrödinger, Inc. Schrödinger, Inc may be a wholly ownedsubsidiary of the Columbia University, New York.Python is a trademark of the Python Software Foundation. Java is a trademark or registered trademark of SunMicrosystems, Inc. in the U.S. and other countries.“The forefront of chemoinformatics” is a trademark of Daylight Chemical Information Systems, Inc.Other products and software packages referenced in this document are trademarks and registered trademarks oftheir respective vendors or manufacturers.
CONTENTSI OE<strong>Shape</strong> <strong>Programming</strong> <strong>Manual</strong> 11 Introduction 21.1 History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Theory 32.1 Molecular <strong>Shape</strong> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2 <strong>Shape</strong> Characteristics and the Use of Gaussians . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Calculating simple overlap 83.1 Overlap methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.2 Radii approximations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.3 Using hydrogens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.4 Adding scores to molecules using SD data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Color overlap 114.1 Overlap of color atoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.2 Using built-in color force fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.3 OEColorForceField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Best Overlay 165.1 Starting positions for optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165.2 Ways to deal with OEBestOverlay results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165.3 Saving aligned structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205.4 Using color along with shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Calculating shape characteristics 23II OE<strong>Shape</strong> API 257 Classes 267.1 OEBestOverlay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267.2 OEBestOverlayResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317.3 OEBestOverlayScore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337.4 OEColorForceField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357.5 OEColorOverlap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377.6 OEColorResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39ii
7.7 OEHighestColorTanimoto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397.8 OEHighestComboScore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407.9 OEHighestFitColorTversky . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407.10 OEHighestFitTversky . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407.11 OEHighestFitTverskyCombo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417.12 OEHighestOverlap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417.13 OEHighestRefColorTversky . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417.14 OEHighestRefTversky . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427.15 OEHighestRefTverskyCombo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427.16 OEHighestScaledColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427.17 OEHighestTanimoto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437.18 OEHighestTanimotoCombo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437.19 OEOverlap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437.20 OEOverlapResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 OE<strong>Shape</strong> Functions 488.1 OEAddColorAtoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488.2 OECalc<strong>Shape</strong>Multipoles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488.3 OECalcVolume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488.4 OECountColorAtoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488.5 OEHasColorAtoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498.6 OERemoveColorAtoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498.7 OESelfColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498.8 OE<strong>Shape</strong>GetRelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498.9 OE<strong>Shape</strong>GetPlatform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498.10 OE<strong>Shape</strong>GetVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498.11 OE<strong>Shape</strong>IsLicensed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498.12 OESortOverlayScores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 OE<strong>Shape</strong> Namespaces 519.1 OEBOMinType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519.2 OEBOOrientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519.3 OEColorFFType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519.4 OEOverlapMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519.5 OEOverlapRadii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529.6 OEOverlapRepresentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5210 Release Notes 5310.1 OE<strong>Shape</strong> 1.7.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5310.2 OE<strong>Shape</strong> 1.6.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5410.3 OE<strong>Shape</strong> 1.6.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5410.4 OE<strong>Shape</strong> 1.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5410.5 OE<strong>Shape</strong> 1.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55A Bibliography 56Index 57iii
LISTINGS3.1 Simple overlap using Exact overlap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83.2 Rescoring pre-aligned structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.1 Using color to add scores to pre-aligned molecules. . . . . . . . . . . . . . . . . . . . . . . . . . 114.2 Using ImplicitMillsDean with user interactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . 135.1 Getting all the scores from OEBestOverlay. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175.2 Getting all the best scores from OEBestOverlay. . . . . . . . . . . . . . . . . . . . . . . . . . . . 185.3 Keeping a few top scores from OEBestOverlay. . . . . . . . . . . . . . . . . . . . . . . . . . . . 195.4 Writing aligned structures from OEBestOverlay. . . . . . . . . . . . . . . . . . . . . . . . . . . . 205.5 Using color with OEBestOverlay. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216.1 Calculating shape properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Part IOE<strong>Shape</strong> <strong>Programming</strong> <strong>Manual</strong>1
CHAPTERONEIntroductionThis is the documentation for the OpenEye <strong>Shape</strong> toolkit. <strong>Shape</strong> and associated color functions allow a rigorousand rapid comparison of the shape of 2 molecules to get similarity. This comparison can be in an arbitrary alignmentprovided by some outside source, or the optimum overlap between the 2 molecules can be maximized thenthe resulting overlap properties can be calculated.Also, while most discussions will involve the comparison of two small molecules, most of the algorithms work ongrids as well.In all the examples below, when considering the two species to be compared, we will use the following namingconvention. The object that is stationary will be known as the reference and the object being compared will becalled the fit object. This technology is the same as found in OpenEye’s application, ROCS, where these 2 objectsare also sometimes referred to as the query and dbase molecule, respectively.1.1 HistoryInitially, the first versions of the <strong>Shape</strong> toolkit were written in C, using a handle-like system for objects. Sincethe completion of OEChem, all OpenEye applications and toolkits have migrated to using OEChem for theirinformatics infrastructure.This version of the <strong>Shape</strong> toolkit encapsulates all the algorithms present in previous versions, but uses OEChemmolecule objects. As such this and future versions of the <strong>Shape</strong> toolkit also require OEChem to be installed.2
CHAPTERTWOTheory2.1 Molecular <strong>Shape</strong>What do we mean by shape? The word is often used without consideration of precise meaning but in this documentwe shall be very clear as to the definition of shape. Two entities will have the same shape if their volumes exactlycorrespond. The more the volumes differ, the more the shapes will differ. We will give a precise mathematicalexposition below, but it is worth noting even at this most basic level shape is defined as a relative quantity, dependingon references to other shapes. In this we differ from approaches that attempt to provide absolute, canonical,“shapes” by which to categorize molecules.What do we mean by “volume”? A volume is any scalar field. This means a function that has a single number, or“scalar”, value at each point in space. The “special case” for the common understanding of volume is a specificscalar field that has a value of one inside an object and zero outside. The volume of a scalar field is:∫V (volume) = f(x, y, z)dv (2.1)The volume function, f, is also referred to as the “characteristic” function. When the characteristic functioncorresponds to the common definition of a volume field this integral corresponds to what is commonly expectedby volume. However, we are not restricted to such simple functions and can still calculate a V. In general thevolume of a scalar field is a “contraction” of the information represented by that characteristic function. It is moreprecisely referred to as the zeroth-order contraction, or “moment”. We will discuss other moments and their useslater, but one immediate observation is that two objects can not have the same shape if their volumes are not thesame. The converse is obviously not true. Rather, two objects can have the same volume and not have the sameshape. Volume is typical, therefore, of most contractions of information.We can now write down a precise definition of shape similarity. Consider the integral:∫S 1 = |f(x, y, z) − g(x, y, z)|dV (2.2)where f and g are different characteristic functions. If this integral is zero then f and g are actually the samefunction and therefore correspond to the same shape. The larger the integral, the more different the shapes definedby f and g. It defines a metric quantity between the two fields f and g. The word “metric” is used loosely to mean“shape”, but here we mean the precise mathematical definition: i.e. a distance that is 1) always positive, 2) zero ifand only if two entities are identical and 3) that obeys the triangle inequality. The triangle inequality states that ifentity A is distance x from entity B and B is distance y from entity C then the distance between A and C is bounded3
4 Chapter 2. Theoryby |x − y| and |x + y|. The type of comparison shown in S 1 is referred to as an L 1 metric. Another metric is theL 2 metric:S 2 =√ ∫[f(x, y, z) − g(x, y, z)] 2 dV (2.3)This integral is the standard one we will use to define shape similarlity The primary advantage, computationally,of 2.3 over 2.2 is that 2.3 does not involve the absolute value function that is not analytic.Multiplying the terms in the integral out gives:∫S2 2 =∫f(x, y, z) 2 dV +∫g(x, y, z) 2 dV − 2This is the fundamental equation for shape comparison. We rewrite it as:f(x, y, z)g(x, y, z)dV (2.4)S f,g = I f + I g − 2O f,g (2.5)The I terms are the self-volume overlaps of each entity (for our purposes - molecule), while the O term is theoverlap between the two functions. They constitute the three terms we need to calculate to compare the shapes oftwo fields. The I terms are independent of orientation but not O. Finding the orientation that maximizes O, andhence minimizes S f,g , is equivalent to finding the best overlay between the two objects (a quantity that has its own,distinct metric properties). We also note here that the quantity referred to as a Tanimoto coefficient may be derivedby recombining I’s and O so:T animoto f,g =O f,gI f + I g − O f,g(2.6)Tanimoto coefficients will be familiar to those who use them for bitvector fingerprint comparison. An alternativemeasure is the Tversky coefficient, also mostly used for similarity between bitvector fingerprints. Similarly to theTanimoto coefficient above, we can define a shape Tversky measure. The base equation for the Tversky coefficientis:T versky f,g =O f,gα(I f − O f,g ) + β(I g − O f,g ) + O f,g(2.7)This equation has a couple of versions, depending on the values chosen for α and β. For the special case where:we get the Tanimoto equation:α = β = 1.0 (2.8)T versky f,g (α, β) ==O f,gα(I f − O f,g ) + β(I g − O f,g ) + O f,g(2.9)O f,gI f + I g − O f,g(2.10)A more common constraint on Tversky is the case, α + β = 1.
2.2. <strong>Shape</strong> Characteristics and the Use of Gaussians 5T versky f,g (α, β) ==O f,gα(I f − O f,g ) + β(I g − O f,g ) + O f,g(2.11)O f,gαI f + βI g(2.12)Since this introduces an assymmetry, the Tversky calculation depends on which molecule’s self-overlap has the αpre-factor. The <strong>Shape</strong> toolkit calculates two Tversky values, one with the reference molecule with α pre-factor anda second with the fit molecule with α as the pre-factor. Also, note that since shape is a field property, instead ofa simple scalar like a bitvector, shape Tversky can be larger than 1.0 since the overlap O f,g can be larger than amolecule’s self-overlap, I f .The OpenEye <strong>Shape</strong> <strong>Toolkit</strong> is a set of calculational objects designed to facilitate the calculation of these fieldmetricquantities. ROCS is an application built on top of the <strong>Shape</strong> toolkit.2.2 <strong>Shape</strong> Characteristics and the Use of GaussiansMolecules are traditionally viewed as a set of fused spheres, sometimes referred to as the CPK model. The commonview of molecular volume is then of a characteristic function that is one (1) inside at least one sphere and zero (0)outside. How do we calculate the volume of such a seemingly simple function? The volume of a single sphere is4πr 3 /3 but the complication for two fused spheres is that we have to account for the shared volume and not countit twice. For more than two atoms, there are triple intersections that must be added back in if we have removed thethree pairs of intersections. The general formula for N spheres that explicitly calculates the volume of every levelof overlap and it’s correct contribution is:∫V = 1 −N∏i(1 − f i )dv (2.13)This is easy to write, not so easy to solve because the analytic formulae for overlaps of increasing order arehighly non-trivial (although they have been derived to arbitrary order). It is fair to say that this has hindered thedevelopment of shape comparison in many ways. Attempts to use analytic formulae led to very slow programsand approximate methods, for instance using grids of points that are turned “in” or “out” by each sphere, do notgive smooth gradients required for minimization. Brian Masek (AstraZeneca) was the first to attempt to optimizeoverlaps of molecules using the analytic approach. His program would take several minutes per minimization.In addition it would often suffer from a common problem when using functions that vary sharply (such as solidspheres): it would often get stuck in local mimina. Nevertheless, Brian did have encouraging success using thismethod to find similarities not obvious from chemical structure.The conceptual breakthrough in shape comparison came in 1992 in a paper by Andrew Grant (AstraZeneca) andBarry Pickup (University of Sheffield). They showed that if one let go of the concept of the characteristic functionbeing binary, and instead use a sum of continuous functions, i.e. a Gaussian, that the solid-sphere volume, could berecovered to high accuracy (typically ≈0.1%). A sphere has one defining parameter, its radius, whereas a Gaussianhas two defining parameters, its prefactor, p, and its width, w:pe −wx2 (2.14)Grant and Pickup found that by fixing p to 2.7 and setting w for each atom such that the volume integral foreach atom agreed with its solid-sphere volume, they achieved remarkable precision. In addition, the overlap terms
6 Chapter 2. Theorybetween any two atoms, and hence any higher-order overlaps, are all Gaussian functions themselves because of theGaussian Contraction formula (shown here for one spatial variable):∫∫e a(x−xi)2 e b(x−xi)2 =e (a+b)(x−xi)2 (2.15)i.e. two atomic-gaussians overlap to produce another gaussian. Likewise, a three atomic-Gaussian overlap is thatof an overlap-Gaussian with an atomic-Gaussian, hence another Gaussian. The simplicity of these formulae andthe formula for the volume of each individual Gaussian leads to very efficient algorithms for the calculation of thevolume of a molecule so represented (the OpenEye method calculates several thousand volumes per second whilecalculating intersections up to sixth order).In addition to simple calculation of molecular volume, which is the zeroth-order moment of the characteristicfunction, the ease of evaluation of intersections allows for accurate calculation of high-order moments: what Andycalls the “steric multipoles”. For instance, if the product formulae for atomic and intersection Gaussians yields nGaussians, the first order moments are:M 1,x =M 1,y =M 1,z =n∑∫i=1n∑∫i=1n∑∫i=1xe ai|(x−xi)2 +(y−y i) 2 +(z−z i) 2 |ye ai|(x−xi)2 +(y−y i) 2 +(z−z i) 2 |ze ai|(x−xi)2 +(y−y i) 2 +(z−z i) 2 |(2.16)(2.17)(2.18)These integrals are easy to solve and their sum can be set to zero by an appropriate choice of origin: the center of“mass” for the sum of Gaussians. Second-order moments are found from integrals of the type:n∑∫M 2,P Q =i=1P Qe ai|(x−xi)2 +(y−y i) 2 +(z−z i) 2 |(2.19)where P and Q are chosen from (x,y,z), e.g. x 2 , xy etc. These moments can be thought of as a symmetric 3*3matrix which we refer to as the “mass matrix”. Rotating or translating the molecule will change the momentsand the transform that sets the first-order moments to zero and diagonalizes the mass-matrix puts the moleculeinto its “inertial frame”. By convention we assign the x-axis to the largest eigenvector of the mass matrix, y-axisto the median eigenvector, z-axis to the smallest. Note that this orientation is still not uniquely defined: 180degree rotations around any axis also diagonalize the mass-matrix. The eight (2 3 ) possible transforms that can begenerated by combinations of such rotations actually lead to four unique inertial orientations.If a molecule is aligned to its inertial frame, all higher-order steric multipoles become invariant, ignoring certainsign-changes from the four-fold degeneracy of the inertial frame. As such they, as well as the second-order moments,are shape “descriptors”. They are still contractions of the information contained in the characteristic field,i.e. two molecules can have the same steric moments and yet have different shapes. (Moments are “complete” inthat if we calculate them to infinite order they do exactly define volume but this is seldom a practical approach!)Nevertheless, they do contain useful information and can be used as a rapid, approximate, filter for shape similarity.The same advantages that allow for the calculation of molecular volume carry over to the calculation of molecularvolume overlap. The overlap of volumes are Gaussian contractions, easily tabulated and efficiently retrieved. Andyre-wrote Brian’s program and obtained an order-of-magnitude improvement in performance as well as anotherremarkable observation: if the starting orientation of each molecule is that given from the inertial frame then very
2.2. <strong>Shape</strong> Characteristics and the Use of Gaussians 7few ”false” minima are produced. The smoothness of the Gaussian characteristic function is enough to overcomethe problems with convergence in Brian’s program. The four possible ”inertial” starting points were enough to findthe best, global, overlay between two molecules. This observation and the Gaussian approach are the basis of theOpenEye <strong>Shape</strong> <strong>Toolkit</strong> and ROCS program for rapid shape overlay.But note, despite the algorithmic advantages, a correlation with common perception has been lost. Because thepre-factor of each atomic Gaussian is not unity, the characteristic function does not correspond to the inside/outsidedescription with which we are most comfortable. In the Gaussian model all points in space are to some degreeinside and to some degree outside. That is, the Gaussian model typically shows about 0.1% error with respect tothe solid sphere model due to the fact that is includes a portion of all points in space inside the volume.
CHAPTERTHREECalculating simple overlapThe simplest object in the <strong>Shape</strong> toolkit, OEOverlap, is used to calculate simple, static, overlap between twoobjects (molecules or grids). Note that static means that the two input species (ref and fit) are not moved at all.This object simply calculate the overlap given the input positions. Performing calculations that actually optimizethe alignment/overlap are done with the OEBestOverlay object (see chapter 5).This first example reads in a reference molecule and a few fit molecules and prints out the overlap calculated. Notethat this example uses all default settings for OEOverlap (discussed in the following sections).1 /**********************************************************************2 Copyright (C) 2005,2006,2007,2008 OpenEye Scientific Software, Inc.3 ***********************************************************************/4 #include "openeye.h"56 #include "oeplatform.h"7 #include "oesystem.h"8 #include "oechem.h"9 #include "oeshape.h"1011 using namespace OEPlatform ;12 using namespace OESystem ;13 using namespace OEChem ;14 using namespace OE<strong>Shape</strong> ;15 using namespace std ;161718 int main ( int , char∗∗)19 {20 oemolistream reffs ( "a.mol2" ) ;21 oemolistream fitfs ( "rocs_hits_1.sdf" ) ;2223 OEGraphMol refmol ;24 OEReadMolecule ( reffs , refmol ) ;2526 OEOverlap ov ;27 ov . SetRefMol ( refmol ) ;2829 OEOverlapResults res ;30 OEGraphMol fitmol ;31 while ( OEReadMolecule ( fitfs , fitmol ) )32 {33 oeout
3.1. Overlap methods 938 }Listing 3.1: Simple overlap using Exact overlap3.1 Overlap methodsThis nature of the algorithm used to calculate overlap is determined by the SetMethod() member of OEOverlap.At present there are four types of algorithms implemented: Exact, Analytic, Analytic2, and Grid. These are definedin the OEOverlapMethod namespace.The Exact option is as detailed above: all pairs are considered and the gaussian overlaps are calculated exactly.The two Analytic options use an approximation to the overlap between two gaussians that is accurate to about onepart in a thousand. In addition, Analytic2 uses a proximity grid to only calculate those atoms pairs that are within acertain threshold distance (by default 4.5Å). This approximation adds another one part in a thousand average errorbut is faster for larger molecules. The final option, Grid, uses a grid representation of the volume of the targetmolecule. It requires significant set-up time relative to the cost of a single overlap calculation ( 0.01s compared to0.0001s) but is significantly faster than other methods for the evaluation of each overlap once set. Grid suffers afew caveats and drawbacks. First is that, currently, although reference radii are all treated as given, fit atoms are alltreated as if they have one radius (that assigned to carbon, and setable via SetCarbonRadius()). The second is thatthe approximation is slightly worse, typically a few parts in a thousand, at typical grid resolutions. Both Analytic2and Grid improve performance when the fit molecule is large (>20 atoms) because, if there are n atoms in the fitand m in the reference, the work per atom in the fit is proportional to a constant not n.By default, OEOverlap performs an Exact overlap calculation. The OEBestOverlay object (used in ROCS) usesGrid for speed.3.2 Radii approximationsSince we are considering molecular volume overlap as a measure, the radii used for each atom is important. Thereare essentially 2 settings. A radii approximation of All means each atom will be treated with the radius as passedin. Alternatively, one can treat all heavy atoms as similar and apply the Carbon radius approximation. With this,all heavy atoms will be assigned the same radius, regardless of the value attached to each atom. As noted above, ifthe Grid method is chosen, the Carbon radius approximation is also turned on.3.3 Using hydrogens<strong>Shape</strong> is a heavy atom property and most OpenEye uses (as well as the defaults for OEOverlap and OEBestOverlay)ignore hydrogens. Hydrogens can be present or not, if OEOverlap is told to not use them, they will not affect theoverlap scores.
10 Chapter 3. Calculating simple overlap3.4 Adding scores to molecules using SD dataThis next example program switches on the Analytic overlap method and also uses a little extra OEChem to attachthe overlap scores to each molecule as SD data. This can be used to rescore a set of ROCS hits or to measure theoverlap of ROCS alignments against an exlcusion region in the binding site.1 /**********************************************************************2 Copyright (C) 2005,2006,2007,2008 OpenEye Scientific Software, Inc.3 ***********************************************************************/4 #include "openeye.h"56 #include "oeplatform.h"7 #include "oesystem.h"8 #include "oechem.h"9 #include "oeshape.h"1011 using namespace OEPlatform ;12 using namespace OESystem ;13 using namespace OEChem ;14 using namespace OE<strong>Shape</strong> ;15 using namespace std ;1617 int main ( int argc , char ∗argv [ ] )18 {19 if ( argc ! = 4 )20 OEThrow . Usage ( "rescore " ) ;2122 oemolistream reffs ( argv [ 1 ] ) ;23 oemolistream fitfs ( argv [ 2 ] ) ;24 oemolostream outfs ( argv [ 3 ] ) ;2526 OEGraphMol refmol ;27 OEReadMolecule ( reffs , refmol ) ;2829 OEOverlap ov ;30 ov . SetMethod ( OEOverlapMethod : : Analytic ) ;31 ov . SetRefMol ( refmol ) ;3233 OEOverlapResults res ;34 OEGraphMol fitmol ;35 while ( OEReadMolecule ( fitfs , fitmol ) )36 {37 ov . Overlap ( fitmol , res ) ;38 char buffer [ 1 0 ] ;39 sprintf ( buffer , "%-6.3f" , res . tanimoto ) ;40 OESetSDData ( fitmol , "AnalyticTanimoto" , buffer ) ;41 OEWriteMolecule ( outfs , fitmol ) ;42 }43 return 0 ;44 }Listing 3.2: Rescoring pre-aligned structures
CHAPTERFOURColor overlap4.1 Overlap of color atomsAs a way of comparing chemical functionality, the <strong>Shape</strong> toolkit also provides a color overlap function, OEColorOverlap.The underlying algorithm is similar to pure shape, but instead of overlapping all heavy atoms, in thiscase we overlap similarly tagged color atoms. The decision of what becomes a color atom is done using SMARTSpattern matching. And the radius and weight of color interactions is completely user-definable.4.2 Using built-in color force fieldsTwo color force fields, ImplicitMillsDean and ExplicitMillsDean, are built into the <strong>Shape</strong> toolkit. (The OEColor-ForceField class is defined in the next section.) Both of these force fields define similar 6 TYPE color force-fields.The types are hydrogen-bond donors, hydrogen-bond acceptors, hydrophobes, anions, cations, and rings. TheImplicitMillsDean force field is recommended.ImplicitMillsDean includes a simple pKa model that assumes pH=7. It defines cations, anions, donors and acceptorsin such a way that they will be assigned the appropriate value independent of the protonation state in thereference or fit molecule. For example, if a molecule contains a carboxylate, ImplicitMillsDean will consider it ananionic center independent of whether it is protonated or deprotonated. This is convenient for searching databaseswhich have not had careful curation of their protonation states. The ExplicitMillsDean file has a similar overallinteraction model, however, it does not include a pKa model. It interprets the protonation and charge state of eachmolecule exactly. Thus, if a sulfate is protonated and neutral, it will not be considered an anion.The hydrogen-bond models in both ImplicitMillsDean and ExplicitMillsDean are extensions of the original modelpresented by Mills and Dean(1). They both have donors and acceptors segregated into strong, moderate and weakcategories.This next example uses the ImplicitMillsDean force field to rescore a set of ROCS hits and add the color scores toSD tags.1 /**********************************************************************2 Copyright (C) 2005,2006,2007,2008 OpenEye Scientific Software, Inc.3 ***********************************************************************/4 #include "openeye.h"511
12 Chapter 4. Color overlap6 #include "oeplatform.h"7 #include "oesystem.h"8 #include "oechem.h"9 #include "oeshape.h"1011 using namespace OEPlatform ;12 using namespace OESystem ;13 using namespace OEChem ;14 using namespace OE<strong>Shape</strong> ;15 using namespace std ;1617 int main ( int argc , char ∗argv [ ] )18 {19 if ( argc ! = 4 )20 OEThrow . Usage ( "colorscore " ) ;2122 oemolistream reffs ( argv [ 1 ] ) ;23 oemolistream fitfs ( argv [ 2 ] ) ;24 oemolostream outfs ( argv [ 3 ] ) ;2526 OEGraphMol refmol ;27 OEReadMolecule ( reffs , refmol ) ;2829 OEColorOverlap ov ;30 ov . SetColorForceField ( OEColorFFType : : ImplicitMillsDean ) ;31 ov . SetRefMol ( refmol ) ;3233 oeerr
4.3. OEColorForceField 134.3.1 User-defined interactionsAs a step toward writing a complete color force field, it is possible to combine built-in rules for color atom assignmentwith user defined interactions. A new OEColorForceField object can be created using one of the built-intypes, then the interactions can be cleared using ClearInteractions() (section ?? and subsequent userinteractions added (section ??).For example, to use the ImplicitMillsDean atom typing rules, but to only consider donor-donor and acceptoracceptorinteractions, one can use the following:1 /**********************************************************************2 Copyright (C) 2005,2006,2007,2008 OpenEye Scientific Software, Inc.3 ***********************************************************************/4 #include "openeye.h"56 #include "oeplatform.h"7 #include "oesystem.h"8 #include "oechem.h"9 #include "oeshape.h"1011 using namespace OEPlatform ;12 using namespace OESystem ;13 using namespace OEChem ;14 using namespace OE<strong>Shape</strong> ;15 using namespace std ;1617 int main ( int argc , char ∗argv [ ] )18 {19 if ( argc ! = 4 )20 OEThrow . Usage ( "usercolor " ) ;2122 oemolistream reffs ( argv [ 1 ] ) ;23 oemolistream fitfs ( argv [ 2 ] ) ;24 oemolostream outfs ( argv [ 3 ] ) ;2526 OEGraphMol refmol ;27 OEReadMolecule ( reffs , refmol ) ;2829 OEColorForceField cff ;30 cff . Init ( OEColorFFType : : ImplicitMillsDean ) ;31 cff . ClearInteractions ( ) ;32 unsigned int donorType = cff . GetType ( "donor" ) ;33 unsigned int accepType = cff . GetType ( "acceptor" ) ;34 cff . AddInteraction ( donorType , donorType , "gaussian" , −1.0 , 1 . 0 ) ;35 cff . AddInteraction ( accepType , accepType , "gaussian" , −1.0 , 1 . 0 ) ;3637 OEColorOverlap ov ;38 ov . SetColorForceField ( cff ) ;39 ov . SetRefMol ( refmol ) ;4041 oeerr
14 Chapter 4. Color overlap54 OEWriteMolecule ( outfs , fitmol ) ;5556 oeerr
4.3. OEColorForceField 15PATTERN will be taken as the atomic position of the first matching atom in the pattern. In order to simplify bothreading and writing SMARTS, intermediate SMARTS can be associated with words using the DEFINE keyword.Once defined, these words can then be used as atom primitives in subsequent SMARTS patterns with the $ prefix(see ”DEFINE hetero” and ”PATTERN donor” above).Interactions between types are associated with the INTERACTION keyword. Two user-defined TYPES must belisted, and whether their interaction is attractive or repulsive. By default the interaction decays as a Gaussian ofweight 1.0Åand radius (decay to 1/e) 1.0Å. The weight and radius can be modified by keywords WEIGHT andRADIUS. At present, the only alternative to a Gaussian decay is invoked by the DISCRETE keyword. A discreteinteraction contributes all of WEIGHT if the inter-type distance is less than RADIUS, or zero. Since it is notdifferentiable it makes no contribution to optimization (i.e. because the gradient of a DISCRETE function is 0 orinfinite).
CHAPTERFIVEBest OverlayOEBestOverlay is the object use to maximize shape (and color) overlap between two objects. OEBestOverlayuses the same overlap function and color function as described earlier, but it optimizes the overlap between thereference and fit object. For speed, the default overlap settings for OEBestOverlay are to use the Grid overlapmethod (which implies the Carbon radius approximation) and hydrogens are ignored.5.1 Starting positions for optimizationSince OEBestOverlay performs an optimization, the starting point of the optimization is important. By default,OEBestOverlay uses an inertial frame alignment method to decide on starting positions. The reference structureis aligned by its principal moments of inertia, then the fit object is aligned in 4 positions with the primary andsecondary moments of inertia in both possible directions.Thus, for any given optimization, there are 4 results returned, usually only one of which is useful. In order to dealwith structures with symmetrical moments of inertia, OEBestOverlay may perform additional starting points. Fora reference or fit where the 2 major moments of inertia are equal (to a user-defined percent, nominally 15%), 4extra starting positions are generated. In the rare case of a molecule with all 3 moments of inertia essentially equal,20 random starting translations and rotations are chosen as starting positions.Alternatively, the user may desire to start the optimization from a single, pre-aligned position. For this case, theuser can specify AsIs as a starting position.And finally, there is a method to generate N random starting positions where N is user-defined as well as themaximum translation allowed between random starts. In most cases, the default Inertial frame starting positionsare completely sufficient to find optimal overlap.Note that the fit object is not moved during the optimization. Part of the results returned from the calculation arethe transforms necessary to move the fit object into the final orientation. This allows the user to skip this step ifonly scores are desired. It also allows application of the same transform to other objects.5.2 Ways to deal with OEBestOverlay resultsUnlike OEOverlap and OEColorOverlap, OEBestOverlay uses multi-conformer molecules as the reference and fit(mostly for efficiency). As such, a single OEBestOverlay calculation can return numerous results. Basically, each16
5.2. Ways to deal with OEBestOverlay results 17calculation will return N results where N is the number of ref conformers times the number of fit conformers timesthe number of starting positions for each pair. So comparing 2 molecules with 10 conformers each could return400 or more results.There are two helper classes designed solely to contain these results and to make it easy to extract all or just thedesired subset. OEBestOverlayResults (section ??) holds the results of a single pair of conformers. It contains theset of OEBestOverlayScore objects (section ??), one for each starting position.The first example, uses 2 iterators to show all the results.1 /**********************************************************************2 Copyright (C) 2005,2006,2007,2008 OpenEye Scientific Software, Inc.3 ***********************************************************************/4 #include "openeye.h"56 #include "oeplatform.h"7 #include "oesystem.h"8 #include "oechem.h"9 #include "oeshape.h"1011 using namespace OEPlatform ;12 using namespace OESystem ;13 using namespace OEChem ;14 using namespace OE<strong>Shape</strong> ;15 using namespace std ;1617 int main ( int argc , char ∗argv [ ] )18 {19 if ( argc ! = 3 )20 OEThrow . Usage ( "bestoverlay1 " ) ;2122 oemolistream reffs ( argv [ 1 ] ) ;23 oemolistream fitfs ( argv [ 2 ] ) ;2425 OEMol refmol ;26 OEReadMolecule ( reffs , refmol ) ;2728 OEBestOverlay best ;29 best . SetRefMol ( refmol ) ;3031 oeerr
18 Chapter 5. Best Overlay55 }56 oeerr
5.2. Ways to deal with OEBestOverlay results 1951 ++resCount ;52 }53 }54 oeerr
20 Chapter 5. Best Overlay53 if ( resCount==keepsize )54 break ;55 }56 }57 oeerr
5.4. Using color along with shape 2138 OEMol fitmol ;39 while ( OEReadMolecule ( fitfs , fitmol ) )40 {41 oeerr
22 Chapter 5. Best Overlay14 using namespace OE<strong>Shape</strong> ;15 using namespace std ;1617 int main ( int argc , char ∗argv [ ] )18 {19 if ( argc ! = 5 )20 OEThrow . Usage ( "bestoverlay-color " ) ;2122 oemolistream reffs ( argv [ 1 ] ) ;23 oemolistream fitfs ( argv [ 2 ] ) ;24 oemolostream outfs ( argv [ 3 ] ) ;25 unsigned int keepsize = atoi ( argv [ 4 ] ) ;2627 OEMol refmol ;28 OEReadMolecule ( reffs , refmol ) ;2930 OEBestOverlay best ;31 best . SetRefMol ( refmol ) ;32 best . SetColorForceField ( OEColorFFType : : ImplicitMillsDean ) ;33 best . SetColorOptimize ( true ) ;3435 oeerr
CHAPTERSIXCalculating shape characteristicsWhile most functionality in the <strong>Shape</strong> <strong>Toolkit</strong> involves comparison of pairs of molecules, there are a few fundamentalproperties that can be calculated for a single molecule. All of these calculations are done using the samebasic Gaussian description of a molecule as described above.The simplest property to calculate is volume, using OECalcVolume (section ??.float vol = OECalcVolume ( mol ) ;Note that in general <strong>Shape</strong> is a heavy-atom property and as such hydrogens are ignored by default in most <strong>Shape</strong>toolkit functions. To calculate the volume including hydrogens:float vol = OECalcVolume ( mol , true ) ;In addition to simple volume calculations, the steric multipoles of a molecule can also be calculated. See section??.float smult [ 1 4 ] ;bool OECalc<strong>Shape</strong>Multipoles ( mol , smult ) ;This next example demonstrates the calculation of volume and shape multipoles.1 /**********************************************************************2 Copyright (C) 2005,2006,2007,2008 OpenEye Scientific Software, Inc.3 ***********************************************************************/4 #include "openeye.h"56 #include "oeplatform.h"7 #include "oesystem.h"8 #include "oechem.h"9 #include "oeshape.h"1011 using namespace OEPlatform ;12 using namespace OESystem ;13 using namespace OEChem ;14 using namespace OE<strong>Shape</strong> ;15 using namespace std ;1617 int main ( int argc , char ∗argv [ ] )18 {19 if ( argc ! = 3 )20 OEThrow . Usage ( "shapeprops " ) ;2122 oemolistream ifs ( argv [ 1 ] ) ;23 oemolostream ofs ( argv [ 2 ] ) ;2425 OEGraphMol mol ;23
24 Chapter 6. Calculating shape characteristics26 while ( OEReadMolecule ( ifs , mol ) )27 {28 OEThrow . Info ( " Title: %s" , mol . GetTitle ( ) ) ;29 OEThrow . Info ( " Volume: %8.2f" , OECalcVolume ( mol ) ) ;30 OEThrow . Info ( "Volume: (without H): %8.2f" , OECalcVolume ( mol , false ) ) ;3132 float smult [ 1 4 ] ;33 OECalc<strong>Shape</strong>Multipoles ( mol , smult ) ;3435 OEThrow . Info ( " Steric multipoles:" ) ;36 OEThrow . Info ( " monopole: %8.2f" , smult [ 0 ] ) ;37 OEThrow . Info ( " quadrupoles: %8.2f %8.2f %8.2f" ,38 smult [ 1 ] , smult [ 2 ] , smult [ 3 ] ) ;39 OEThrow . Info ( " octopoles:" ) ;40 OEThrow . Info ( " xxx: %8.2f yyy: %8.2f zzz: %8.2f" ,41 smult [ 4 ] , smult [ 5 ] , smult [ 6 ] ) ;42 OEThrow . Info ( " xxy: %8.2f xxz: %8.2f yyx: %8.2f" ,43 smult [ 7 ] , smult [ 8 ] , smult [ 9 ] ) ;44 OEThrow . Info ( " yyz: %8.2f zzx: %8.2f zzy: %8.2f" ,45 smult [ 1 0 ] , smult [ 1 1 ] , smult [ 1 2 ] ) ;46 OEThrow . Info ( " xyz: %8.2f" , smult [ 1 3 ] ) ;4748 OEThrow . Info ( "" ) ;4950 }5152 return 0 ;53 }Listing 6.1: Calculating shape properties.
Part IIOE<strong>Shape</strong> API25
CHAPTERSEVENClasses7.1 OEBestOverlayclass OEBestOverlayThis class is used to optimize the overlap between 2 molecules. Both molecules can contain one or more conformers.The reference molecule is held rigid and the fit molecule orientation is calculated to maximize overlap. Eachconformer of the fit molecule is optimized against each conformer of the reference molecule, resulting in a largenumber of results that can be returned. The OEBestOverlayResults and OEBestOverlayScore classesare used to make handling this large amount of results easier.Additionally, the reference or fit shape can be a grid instead of a molecule.7.1.1 ConstructorsOEBestOverlay ( )OEBestOverlay ( const OEBestOverlay &)OEBestOverlay ( const OEChem : : OEMCMolBase &refmol )OEBestOverlay ( const OESystem : : OEScalarGrid &refgrid , float interpolate=0.5f )An empty OEBestOverlay class instance can be created, or a new instance can take the reference molecule orgrid as an argument. Note that by default, grids that have a resolution larger that 0.5Åwill be interpolated to thatresolution.7.1.2 operator=OEBestOverlay &operator=(const OEBestOverlay &)Assignment operator. The contents of the passed OEBestOverlay reference are copied into an OEBestOverlayinstance.7.1.3 ClearColorForceFieldvoid ClearColorForceField ( )26
7.1. OEBestOverlay 27Clear out any color force field. No color scores will be calculated.7.1.4 GetAllColorbool GetAllColor ( )const7.1.5 GetCarbonRadiusfloat GetCarbonRadius ( )constReturn the current value for the carbon radius approximation.7.1.6 GetInertialAxialDivisionsunsigned int GetInertialAxialDivisions ( )const7.1.7 GetInitialOrientationunsigned int GetInitialOrientation ( )constGet the current value for initial orientation. Possible values are from the OEBOOrientation namespace (section9.2).7.1.8 GetMaxRandomTranslationfloat GetMaxRandomTranslation ( )constGet the value in Åof maximum random translation.7.1.9 GetMethodunsigned int GetMethod ( )constReturn the current value of overlap method.7.1.10 GetMinimizeTypeunsigned int GetMinimizeType ( )constGet the current value for minimize type. Possible values are from the OEBOMinType namespace (section 9.1).7.1.11 GetNumRandomStartsunsigned int GetNumRandomStarts ( )const
28 Chapter 7. ClassesGet the current number of random starts.7.1.12 GetRadiiApproximationunsigned int GetRadiiApproximation ( )constReturn the current value of the radii approximation.7.1.13 GetRandomSeedunsigned int GetRandomSeed ( )constGet the current value of the random seed.7.1.14 GetRefGridconst OESystem : : OEScalarGrid ∗GetRefGrid ( )const7.1.15 GetRefMolconst OEChem : : OEMCMolBase ∗GetRefMol ( )const7.1.16 GetRefSelfColorfloat GetRefSelfColor ( )Return the self color score of the reference molecule.7.1.17 GetRefSymmetryunsigned int GetRefSymmetry ( unsigned int confIdx ) const7.1.18 GetRepresentationLevelunsigned int GetRepresentationLevel ( )constReturn the current representation level.7.1.19 GetSymmetryThresholdfloat GetSymmetryThreshold ( )const7.1.20 GetUseHydrogens
7.1. OEBestOverlay 29bool GetUseHydrogens ( )constReturn the status of hydrogen use in OEBestOverlay.7.1.21 OverlayOESystem : : OEIterBase< OEBestOverlayResults >∗Overlay ( const OEChem : : OEMCMolBase &fitmol )OESystem : : OEIterBase< OEBestOverlayResults >∗Overlay ( const OESystem : : OEScalarGrid &fitgrid )Perform the calculation and return the an iterator of the results.7.1.22 SetAllColorvoid SetAllColor ( bool state )7.1.23 SetCarbonRadiusvoid SetCarbonRadius ( float cradius )Set the radius to use when using OEOverlapRadii::Carbon. By default this is set to 1.7Å.7.1.24 SetColorForceFieldSet the color force field to be used. Once set, color scores will be calculated and included in the results. Colorgradients will not be included in the optimization unless specifically set using SetColorOptimize(true)bool SetColorForceField ( const OEColorForceField &cff )Set using an existing instance of OEColorForceField. This should already have types and interactions set up.bool SetColorForceField ( unsigned int type )Set using one of the built-in color force fields as defined in the OEColorFFType namespace (section 9.3).bool SetColorForceField ( OEPlatform : : oeistream &is )bool SetColorForceField ( const std : : string &filename )Read in a color force field from an input stream or from a given filename.7.1.25 SetColorOptimizevoid SetColorOptimize ( bool state )Add color gradients to shape gradients in the optimization. Has no effect unless a color force field is also set viaSetColorForceField.7.1.26 SetInertialAxialDivisions
30 Chapter 7. Classesvoid SetInertialAxialDivisions ( unsigned int divisions )7.1.27 SetInitialOrientationvoid SetInitialOrientation ( unsigned int orient )Determines the initial orientation (starting position) for each optimization. The default is OEBOOrientation::Inertial.Alternatives are defined in the OEBOOrientation namespace (section 9.2).7.1.28 SetMaxRandomTranslationvoid SetMaxRandomTranslation ( float trans )If using random starts, this set the maximum distance (in Å) that the center of mass of the fit molecule will bemoved away from the center calculated for inertial frame alignment.7.1.29 SetMethodvoid SetMethod ( unsigned int method )Set the method used to calculate overlap. The default for OEBestOverlay is OEOverlapMethod::Grid. Alternativesare defined in the OEOverlapMethod namespace (section 9.47.1.30 SetMinimizeTypevoid SetMinimizeType ( unsigned int type )Set the score to use in the optimization. Options are in the OEBOMinType namespace (section 9.1).7.1.31 SetNumRandomStartsvoid SetNumRandomStarts ( unsigned int n )If SetInitialOrientation is set to OEBOOrientation::Random, this method sets the number of random starting positionsthat will be used.7.1.32 SetRadiiApproximationvoid SetRadiiApproximation ( unsigned int type )Set the radius approximation used to calculate overlap. The default for OEBestOverlay is OEOverlapRadii::Carbon.Alternatives are defined in the OEOverlapRadii namespace (section 9.57.1.33 SetRandomSeedvoid SetRandomSeed ( unsigned int seed )
7.2. OEBestOverlayResults 31Set a random seed value to allow reproducible random searches.7.1.34 SetRefGridbool SetRefGrid ( const OESystem : : OEScalarGrid &refgrid , float interpolate=0.5f )Set a reference grid for the calculation. OEBestOverlay makes an internal copy. Pre-existing reference moleculesor grids are replaced.7.1.35 SetRefMolbool SetRefMol ( const OEChem : : OEMCMolBase &refmol )Set a reference molecule for the calculation. OEBestOverlay makes an internal copy. Pre-existing referencemolecules or grids are replaced.7.1.36 SetRepresentationLevelvoid SetRepresentationLevel ( unsigned int type )Set the representation level for the gaussians in OEBestOverlay. The default is OEOverlapRepresentation::Atomic.Alternatives are defined in the OEOverlapRepresentation namespace (section 9.6).7.1.37 SetSymmetryThresholdvoid SetSymmetryThreshold ( float threshold )7.1.38 SetUseHydrogensvoid SetUseHydrogens ( bool state )Boolean to determine whether hydrogens are included in the shape calculation. By default this is false and hydrogensare ignored.7.2 OEBestOverlayResultsclass OEBestOverlayResultsSince an OEBestOverlay optimization can result in numerous final results, one for each starting position, thisclass is a container to hold all the results for a fit conformer against a reference conformer. This class is essentiallya container for one or more OEBestOverlayScore instances. The actual number of scores depends on theOEBOOrientation used in the OEBestOverlay.For OEBOOrientation::Inertial, there will be 4, 8 or 20 scores per ref-fit conformer pair, depending on the symmetryof each conformer. For OEBOOrientation::AsIs, there will be just 1 OEBestOverlayScore inside eachOEBestOverlayResults instance. And for OEBOOrientation::Random, the there will be 1 OEBestOverlayScorefor each of the N random starts. See section ?? for more information.
32 Chapter 7. ClassesMost users will not create instances of OEBestOverlayResults, but will simply receive an OEIter of OEBestOverlayResultsas output from the OEBestOverlay::Overlay method.When dealing with the results from OEBestOverlay, the user can either use a double loop, i.e. loop over all theOEBestOverlayResults instances for each ref-fit conformer pair then loop over each OEBestOverlayScore insideeach OEBestOverlayResults instance. In this case, the results also come out in conformer order.OEIter resiter = best . Overlay ( fitmol ) ;for ( ; resiter;++resiter ){OEIter scoreiter = resiter−>GetScores ( ) ;for ( ; scoreiter;++scoreiter ){// do something with score}}Or, there is a free function OESortOverlayScores (see section ??), that takes an iterator of OEBestOverlayResultsand returns a single, sorted iterator of OEBestOverlayScores that can be used in a single loop.OEIter resiter = best . Overlay ( fitmol ) ;OEIter scoreiter ;OESortOverlayScores ( scoreiter , resiter , OEHighestTanimoto ( ) ) ;for ( ; scoreiter;++scoreiter ){// do something with score}7.2.1 ConstructorsOEBestOverlayResults ( )OEBestOverlayResults ( const OEBestOverlayResults &rhs )Default and copy constructors.7.2.2 operator=OEBestOverlayResults &operator=(const OEBestOverlayResults &rhs )7.2.3 AddScorebool AddScore ( const OEBestOverlayScore &sc )7.2.4 Clearbool Clear ( )7.2.5 GetScoresOESystem : : OEIterBase< OEBestOverlayScore > ∗GetScores ( ) constOESystem : : OEIterBase< OEBestOverlayScore > ∗GetScores( const OESystem : : OEBinaryPredicate< OEBestOverlayScore ,OEBestOverlayScore > &sorter ,int nbest=1) const
7.3. OEBestOverlayScore 337.3 OEBestOverlayScoreclass OEBestOverlayScoreThis small class is used to contain all the results from a single optimization of a fit molecule conformer with areference molecule conformer. The user will not normally construct an instance of OEBestOverlayScore, but willinstead iterate over a set of instances as contained in an instance of OEBestOverlayresults (see section ??) .Much of the data is contained in public member variables:unsigned int refconfidx Index of the reference conformer. You can get the actual OEConfBase viarefMol.GetConf(OEHasConfIdx(refconfidx)).unsigned int fitconfidx Index of the fit conformer.Mol.GetConf(OEHasConfIdx(fitconfidx)).You can get the actual OEConfBase via fit-float tanimoto <strong>Shape</strong> tanimoto score for this alignment.float overlap Overlap score for this alignment.float refSelfOverlap Self overlap of reference conformer.float fitSelfOverlap Self overlap of fit conformer.float refSelfColor Self color score of reference conformer.float fitSelfColor Self color score of fit conformer.float colorscore Absolute color score of this alignment.float scaledcolor Color scaled to ref self color score.float rmat[9] Rotation matrix to move fit conformer into this alignment. Use with OERotate to manipulatethe conformer. Note that OpenEye standard is to perform rotation then translation.float trans[3] Translation matrix to move fit conformer into this alignment.OEBestOverlay also has a few member methods to access data calculable from the contained data.7.3.1 ConstructorsOEBestOverlayScore ( )Default and copy constructors.7.3.2 GetColorTanimotofloat GetColorTanimoto ( )const7.3.3 GetColorTverskyfloat GetColorTversky ( float alpha=0.95f ,float beta=0.05f ) const
34 Chapter 7. Classes7.3.4 GetComboScorefloat GetComboScore ( )constReturn combo score, defined as the sum of <strong>Shape</strong> Tanimoto and scaled color score. Value ranges from 0.0 to 2.0.7.3.5 GetTanimotoCombofloat GetTanimotoCombo ( )constReturn TanimotoCombo score, defined as the sum of <strong>Shape</strong> Tanimoto and Color Tanimoto. Value ranges from 0.0to 2.0.7.3.6 GetFitColorTverskyfloat GetFitColorTversky ( )const7.3.7 GetFitTverskyfloat GetFitTversky ( )constReturn the Tversky score using an alpha of 0.05 and beta of 0.95, where alpha is the prefactor for the ref moleculeself overlap.7.3.8 GetFitTverskyCombofloat GetFitTverskyCombo ( )constReturn FitTverskyCombo score, defined as the sum of <strong>Shape</strong> FitTversky and Color FitTversky. Value ranges from0.0 to 2.0.7.3.9 GetRefColorTverskyfloat GetRefColorTversky ( )constReturn RefTverskyCombo score, defined as the sum of <strong>Shape</strong> RefTversky and Color RefTversky. Value rangesfrom 0.0 to 2.0.7.3.10 GetRefTverskyfloat GetRefTversky ( )constReturn the Tversky score using an alpha of 0.95 and beta of 0.05, where alpha is the prefactor for the ref moleculeself overlap.7.3.11 GetRefTverskyCombo
7.4. OEColorForceField 35float GetRefTverskyCombo ( )const7.3.12 GetTverskyfloat GetTversky ( float alpha=0.95f ,float beta=0.05f ) constReturn the Tversky score for user-defined values of alpha and beta, where alpha is the prefactor for the ref moleculeself overlap. Note that calling GetTversky with the default arguments returns the same value as GetRefTversky.7.3.13 Transformbool Transform ( OEChem : : OEMolBase &mol ) constbool Transform ( OEChem : : OEConfBase &mol ) constPerform the proper rotation and translation to move the passed-in molecule or conformer into the final orientationas calculated in the best overlay optimization. This provides the same feature as manually calling OERotate thenOETranslate using the rmat and trans, but to lessen the chance of doing them in the improper order.7.4 OEColorForceFieldclass OEColorForceFieldThe OEColorForceField class contains atom types and interactions used by both OEColorOverlap andOEBestOverlay to calculate color interactions.7.4.1 ConstructorsOEColorForceField ( )OEColorForceField ( const OEColorForceField &rhs )OEColorForceField ( const OEColorForceFieldImpl ∗impl )Default and copy constructors.7.4.2 operator=OEColorForceField &operator=(const OEColorForceField &rhs )Assignment operator. The contents of the passed OEColorForceField reference are copied into an OEColorForce-Field instance.7.4.3 AddColorerbool AddColorer ( unsigned int type , const std : : string &smarts )bool AddColorer ( unsigned int type , const char ∗smarts )Add a SMARTS pattern that maps an atom or set of atoms to a pre-defined atom type, created with AddType.Note that you can use something like:
36 Chapter 7. ClassesOEColorForceField cff ;cff . AddType ( "donor" ) ;cff . AddColorer ( cff . GetType ( "donor" ) , "[#7,#8;H]" ) ;7.4.4 AddInteractionbool AddInteraction ( unsigned int type1 , unsigned int type2 ,const std : : string &interaction_type , float weight ,float range )Add an interaction between 2 pre-defined atom types (using AddType). The interaction type can be either “gaussian”or “discrete”. Weight and radius are the 2 gaussian parameters. Weight corresponds to the height of thegaussian and radius is the distance where the gaussian drops to (1/e). Note that since in most cases the color forcefield is used to match like with like, we need an attractive force, which means we use a negative weight. In thebuilt-in color force fields, the weights default to -1.0 and the radius default is 1.0.7.4.5 AddTypeunsigned int AddType ( const char ∗name )unsigned int AddType ( const std : : string &name )Add a new atom type to the list of named types. Examples might be “donor”, “acceptor”, etc.7.4.6 Clearvoid Clear ( )Clear all atom types and interactions.7.4.7 ClearInteractionsvoid ClearInteractions ( )Clear on the interactions while leaving the atom types in place. Useful for setting up a force field with one of thebuilt-in types, but then adding a different set of interactions.7.4.8 GetTitleconst char ∗GetTitle ( )constReturn the title from this force field.7.4.9 GetTypeunsigned int GetType ( std : : string k ) constReturn the unsigned int corresponding to a given type.7.4.10 GetTypeName
7.5. OEColorOverlap 37std : : string GetTypeName ( unsigned int type ) constGet the name back, given the unsigned int atom type.7.4.11 InitSet up the atom types and interactions.bool Init ( unsigned int cffType ) ;This sets up one of the built-color force field defintions as described above and outlined in the OEColorFFTypenamespace (section 9.3).bool Init ( OEPlatform : : oeistream &is , bool verbose=false ) ;bool Init ( const std : : string &filename , bool verbose=false ) ;Set up the internal definitions by reading a color force field file from an input stream or directly from a file. Settingverbose to true prints information to stderr as the file is parsed. This can be useful when writing a new color forcefield file from scratch.7.4.12 Readybool Ready ( )constReturns true when the object is set up with atom types and interactions.7.4.13 SetTitlebool SetTitle ( const char ∗title )Set the force field title.7.4.14 Writebool Write ( OEPlatform : : oeostream &os )Write the current color force field out to a stream. If this is placed into a file, the subsequent file can be used withInit as well as with ROCS.7.5 OEColorOverlapclass OEColorOverlapOEColorOverlap calculates the static color score for a given orientation of a reference molecule and a fit molecule.Note that this does not move the fit molecule nor does it optimize the color overlap. It simply calculates the scorefor the provided orientation.7.5.1 Constructors
38 Chapter 7. ClassesOEColorOverlap ( )OEColorOverlap ( const OEColorOverlap &rhs )Default and copy constructors.7.5.2 operator=OEColorOverlap &operator=(const OEColorOverlap &rhs )Assignment operator. The contents of the passed OEColorOverlap reference are copied into an OEColorOverlapinstance.7.5.3 ColorScorebool ColorScore ( OEColorResults &res )bool ColorScore ( const OEChem : : OEMolBase &fitmol , OEColorResults &res )Calculate the color score of the fit molecule and place the results into the passed in OEColorResults instance.7.5.4 GetAllColorbool GetAllColor ( )const7.5.5 GetSelfColorfloat GetSelfColor ( )constGet the self color score of the reference molecule.7.5.6 SetAllColorvoid SetAllColor ( bool state )7.5.7 SetColorForceFieldbool SetColorForceField ( unsigned int cffType )bool SetColorForceField ( const OEColorForceField &cff )bool SetColorForceField ( const std : : string &filename )bool SetColorForceField ( OEPlatform : : oeistream &is )Set the color force field to use in the calculation. This can be from an existing OEColorForceField instance, fromone of the built-in force fields (section 9.3), or from an input stream or input file.7.5.8 SetFitMolbool SetFitMol ( const OEChem : : OEMolBase &fitmol )
7.6. OEColorResults 397.5.9 SetRefMolbool SetRefMol ( const OEChem : : OEMolBase &refmol )Set the reference molecule for the calculation.7.6 OEColorResultsclass OEColorResultsOEColorResults is a small struct that contains the results of a color overlap calculation.float colorscore Absolute color score.float scaledcolor Color score normalized against the reference molecule self color.float refSelfColor Self color of the reference molecule.float fitSelfColor Self color of the fit molecule.7.6.1 ConstructorsOEColorResults ( )Default and copy constructors.7.6.2 GetFitTverskyfloat GetFitTversky ( )const7.6.3 GetRefTverskyfloat GetRefTversky ( )const7.6.4 GetTanimotofloat GetTanimoto ( )const7.6.5 GetTverskyfloat GetTversky ( float alpha ,float beta ) const7.7 OEHighestColorTanimoto
40 Chapter 7. Classesstruct OEHighestColorTanimoto :public OESystem : : OEBinaryPredicate{bool operator ( ) ( const OEBestOverlayScore &s1 ,const OEBestOverlayScore &s2 ) const{return s2 . GetColorTanimoto ( ) < s1 . GetColorTanimoto ( ) ;}OESystem : : OEBinaryFunction∗CreateCopy ( ) const{return ( OESystem : : OEBinaryFunction∗) new OEHighestColorTanimoto(∗this ) ;}} ;7.8 OEHighestComboScorestruct OEHighestComboScore :public OESystem : : OEBinaryPredicate{bool operator ( ) ( const OEBestOverlayScore &s1 ,const OEBestOverlayScore &s2 ) const{return s2 . GetComboScore ( ) < s1 . GetComboScore ( ) ;}OESystem : : OEBinaryFunction∗CreateCopy ( ) const{return ( OESystem : : OEBinaryFunction∗) new OEHighestComboScore(∗this ) ;}} ;7.9 OEHighestFitColorTverskystruct OEHighestFitColorTversky :public OESystem : : OEBinaryPredicate{bool operator ( ) ( const OEBestOverlayScore &s1 ,const OEBestOverlayScore &s2 ) const{return s2 . GetFitColorTversky ( ) < s1 . GetFitColorTversky ( ) ;}OESystem : : OEBinaryFunction∗CreateCopy ( ) const{return ( OESystem : : OEBinaryFunction∗) new OEHighestFitColorTversky(∗this ) ;}} ;7.10 OEHighestFitTversky
7.11. OEHighestFitTverskyCombo 41struct OEHighestFitTversky :public OESystem : : OEBinaryPredicate{bool operator ( ) ( const OEBestOverlayScore &s1 ,const OEBestOverlayScore &s2 ) const{return s2 . GetFitTversky ( ) < s1 . GetFitTversky ( ) ;}OESystem : : OEBinaryFunction∗CreateCopy ( ) const{return ( OESystem : : OEBinaryFunction∗) new OEHighestFitTversky(∗this ) ;}} ;7.11 OEHighestFitTverskyCombostruct OEHighestFitTverskyCombo :public OESystem : : OEBinaryPredicate{bool operator ( ) ( const OEBestOverlayScore &s1 ,const OEBestOverlayScore &s2 ) const{return s2 . GetFitTverskyCombo ( ) < s1 . GetFitTverskyCombo ( ) ;}OESystem : : OEBinaryFunction∗CreateCopy ( ) const{return ( OESystem : : OEBinaryFunction∗) new OEHighestFitTverskyCombo(∗this ) ;}} ;7.12 OEHighestOverlapstruct OEHighestOverlap :public OESystem : : OEBinaryPredicate{bool operator ( ) ( const OEBestOverlayScore &s1 ,const OEBestOverlayScore &s2 ) const{return s2 . overlap < s1 . overlap ;}OESystem : : OEBinaryFunction∗CreateCopy ( ) const{return ( OESystem : : OEBinaryFunction∗) new OEHighestOverlap(∗this ) ;}} ;7.13 OEHighestRefColorTversky
42 Chapter 7. Classesstruct OEHighestRefColorTversky :public OESystem : : OEBinaryPredicate{bool operator ( ) ( const OEBestOverlayScore &s1 ,const OEBestOverlayScore &s2 ) const{return s2 . GetRefColorTversky ( ) < s1 . GetRefColorTversky ( ) ;}OESystem : : OEBinaryFunction∗CreateCopy ( ) const{return ( OESystem : : OEBinaryFunction∗) new OEHighestRefColorTversky(∗this ) ;}} ;7.14 OEHighestRefTverskystruct OEHighestRefTversky :public OESystem : : OEBinaryPredicate{bool operator ( ) ( const OEBestOverlayScore &s1 ,const OEBestOverlayScore &s2 ) const{return s2 . GetRefTversky ( ) < s1 . GetRefTversky ( ) ;}OESystem : : OEBinaryFunction∗CreateCopy ( ) const{return ( OESystem : : OEBinaryFunction∗) new OEHighestRefTversky(∗this ) ;}} ;7.15 OEHighestRefTverskyCombostruct OEHighestRefTverskyCombo :public OESystem : : OEBinaryPredicate{bool operator ( ) ( const OEBestOverlayScore &s1 ,const OEBestOverlayScore &s2 ) const{return s2 . GetRefTverskyCombo ( ) < s1 . GetRefTverskyCombo ( ) ;}OESystem : : OEBinaryFunction∗CreateCopy ( ) const{return ( OESystem : : OEBinaryFunction∗) new OEHighestRefTverskyCombo(∗this ) ;}} ;7.16 OEHighestScaledColor
7.17. OEHighestTanimoto 43struct OEHighestScaledColor :public OESystem : : OEBinaryPredicate{bool operator ( ) ( const OEBestOverlayScore &s1 ,const OEBestOverlayScore &s2 ) const{return s2 . scaledcolor < s1 . scaledcolor ;}OESystem : : OEBinaryFunction∗CreateCopy ( ) const{return ( OESystem : : OEBinaryFunction∗) new OEHighestScaledColor(∗this ) ;}} ;7.17 OEHighestTanimotostruct OEHighestTanimoto :public OESystem : : OEBinaryPredicate{bool operator ( ) ( const OEBestOverlayScore &s1 ,const OEBestOverlayScore &s2 ) const{return s2 . tanimoto < s1 . tanimoto ;}OESystem : : OEBinaryFunction∗CreateCopy ( ) const{return ( OESystem : : OEBinaryFunction∗) new OEHighestTanimoto(∗this ) ;}} ;7.18 OEHighestTanimotoCombostruct OEHighestTanimotoCombo :public OESystem : : OEBinaryPredicate{bool operator ( ) ( const OEBestOverlayScore &s1 ,const OEBestOverlayScore &s2 ) const{return s2 . GetTanimotoCombo ( ) < s1 . GetTanimotoCombo ( ) ;}OESystem : : OEBinaryFunction∗CreateCopy ( ) const{return ( OESystem : : OEBinaryFunction∗) new OEHighestTanimotoCombo(∗this ) ;}} ;7.19 OEOverlap
44 Chapter 7. Classesclass OEOverlapOEOverlap calculates the static shape overlap between a reference molecule or grid and a fit molecule or grid.Note that this does not move the fit molecule(grid) nor does it optimize the overlap. It simply calculates the scorefor the provided orientation.7.19.1 ConstructorsOEOverlap ( )OEOverlap ( const OEOverlap &rhs )OEOverlap ( const OEChem : : OEMolBase &refmol )OEOverlap ( const OESystem : : OEScalarGrid &refmol )Default and copy constructors.7.19.2 operator=OEOverlap &operator=(const OEOverlap &rhs )Assignment operator. The contents of the passed OEColorOverlap reference are copied into an OEColorOverlapinstance.7.19.3 GetCarbonRadiusfloat GetCarbonRadius ( )constReturn the current value for the carbon radius approximation.7.19.4 GetHandleint GetHandle ( )const7.19.5 GetMethodunsigned int GetMethod ( )constReturn the current value of overlap method.7.19.6 GetRadiiApproximationunsigned int GetRadiiApproximation ( )constReturn the current value of the radii approximation.7.19.7 GetRepresentationLevelunsigned int GetRepresentationLevel ( )const
7.19. OEOverlap 45Return the current representation level.7.19.8 GetUseHydrogensbool GetUseHydrogens ( )constReturn the status of hydrogen use in OEOverlap.7.19.9 Overlapbool Overlap ( OEOverlapResults &res , float ∗atomOverlaps=0)bool Overlap ( const OEChem : : OEMolBase &fitmol , OEOverlapResults &res ,float ∗atomOverlaps=0)bool Overlap ( const OESystem : : OEScalarGrid &fitgrid , OEOverlapResults &res )Calculate the overlap of the passed in fit molecule or fit grid and place the results into the passed instance ofOEOverlapResults.7.19.10 SetCarbonRadiusbool SetCarbonRadius ( float cradius )Set the radius to use when using OEOverlapRadii::Carbon. By default this is set to 1.7Å.7.19.11 SetFitGridbool SetFitGrid ( const OESystem : : OEScalarGrid &fitgrid )7.19.12 SetFitMolbool SetFitMol ( const OEChem : : OEMolBase &fitmol )7.19.13 SetMethodbool SetMethod ( unsigned int m )Set the method used to calculate overlap. The default for OEOverlap is OEOverlapMethod::Exact. Alternativesare defined in the OEOverlapMethod namespace (section 9.4).7.19.14 SetRadiiApproximationbool SetRadiiApproximation ( unsigned int type )Set the radius approximation used to calculate overlap. The default for OEOverlap is OEOverlapRadii::Carbon.Alternatives are defined in the OEOverlapRadii namespace (section 9.5).7.19.15 SetRefGrid
46 Chapter 7. Classesbool SetRefGrid ( const OESystem : : OEScalarGrid &refgrid )Set a reference grid for the calculation. An internal copy is made. Any previous reference molecule or grid iscleared.7.19.16 SetRefMolbool SetRefMol ( const OEChem : : OEMolBase &refmol )Set a reference molecule for the calculation. An internal copy is made. Any previous reference molecule or grid iscleared.7.19.17 SetRepresentationLevelbool SetRepresentationLevel ( unsigned int type )Set the representation level for the gaussians in OEOverlap. The default is OEOverlapRepresentation::Atomic.Alternatives are defined in the OEOverlapRepresentation namespace (section 9.6).7.19.18 SetUseHydrogensbool SetUseHydrogens ( bool state )Boolean to determine whether hydrogens are included in the shape calculation. By default this is false and hydrogensare ignored.7.20 OEOverlapResultsclass OEOverlapResultsOEOverlapResults is a small struct that contains the results of a shape overlap calculation.float refSelfOverlap Reference molecule self overlap.float fitSelfOverlap Fit molecule self overlap.float tanimoto <strong>Shape</strong> tanimoto score.float overlap Overlap score for this overlap.7.20.1 ConstructorsOEOverlapResults ( )7.20.2 GetFitTversky
7.20. OEOverlapResults 47float GetFitTversky ( )const7.20.3 GetRefTverskyfloat GetRefTversky ( )const7.20.4 GetTverskyfloat GetTversky ( float alpha=0.95f ,float beta=0.05f ) const
CHAPTEREIGHTOE<strong>Shape</strong> Functions8.1 OEAddColorAtomsunsigned int OEAddColorAtoms ( OEChem : : OEMCMolBase &mol ,const OEColorForceField &cff )unsigned int OEAddColorAtoms ( OEChem : : OEMolBase &mol ,const OEColorForceField &cff )Add color atom to the passed in molecule. Note that this is not normally required as both OEColorOverlap andOEBestOverlay make internal copies of molecules and add color atoms automatically.8.2 OECalc<strong>Shape</strong>Multipolesbool OECalc<strong>Shape</strong>Multipoles ( const OEChem : : OEMolBase &mol , float ∗smult ,unsigned int type=OEOverlapRepresentation : : Atoms ,bool useHydrogens=false )Calculate the shape (steric) multipoles. See the example in chapter 6.8.3 OECalcVolumefloat OECalcVolume ( const OEChem : : OEMolBase &mol , bool useHydrogens=true )Calculate the shape volume. See the example in chapter 6.8.4 OECountColorAtomsunsigned int OECountColorAtoms ( const OEChem : : OEMolBase &mol )48
8.5. OEHasColorAtoms 49Return the number of color atoms attached to a molecule.8.5 OEHasColorAtomsbool OEHasColorAtoms ( const OEChem : : OEMolBase &mol )Returns true if a molecule has color atoms attached, false otherwise.8.6 OERemoveColorAtomsvoid OERemoveColorAtoms ( OEChem : : OEMolBase &mol )Removes all color atoms from a molecule.8.7 OESelfColorfloat OESelfColor ( const OEChem : : OEMolBase &mol , const OEColorForceField &cff ,bool allcolor=false )8.8 OE<strong>Shape</strong>GetReleaseconst char ∗OE<strong>Shape</strong>GetRelease ( )8.9 OE<strong>Shape</strong>GetPlatformconst char ∗OE<strong>Shape</strong>GetPlatform ( )8.10 OE<strong>Shape</strong>GetVersionunsigned int OE<strong>Shape</strong>GetVersion ( )8.11 OE<strong>Shape</strong>IsLicensedbool OE<strong>Shape</strong>IsLicensed ( const char ∗feature=0 , unsigned int ∗expdate=0)Determine whether a valid license file is present. This function may be called without a legitimate run-time licenseto determine whether it is safe to call any of OE<strong>Shape</strong>’s functionality.
50 Chapter 8. OE<strong>Shape</strong> FunctionsThe “features” argument can be used to check for a valid license to OE<strong>Shape</strong> along with that feature. For example,to verify that OE<strong>Shape</strong> can be used from Python:if ( ! OE<strong>Shape</strong>IsLicensed ( "python" ) )OEThrow . Warning ( "OE<strong>Shape</strong> is not licensed for the python feature" ) ;The second argument can be used to get the expiration date of the license. This is an array of size three with thedate returned as {day, month, year}. Even if the function returns false due to an expired license, the expdatewill show that expiration date. A value of a zeroes implies that no license or date was found.unsigned int expdate [ 3 ] ;if ( OE<strong>Shape</strong>IsLicensed ( 0 , expdate ) ){OEThrow . Info ( "License expires: day: %d month: %d year: %d" ,expdate [ 0 ] , expdate [ 1 ] , expdate [ 2 ] ) ;}8.12 OESortOverlayScoresvoid OESortOverlayScores ( OESystem : : OEIter< OEBestOverlayScore > &dst ,OESystem : : OEIter< OEBestOverlayResults > &scores ,const OESystem : : OEBinaryPredicate< OEBestOverlayScore ,OEBestOverlayScore > &sorter , int nbest=1 ,bool conforder=false )Sort the scores from multiple sets of OEBestOverlayResults into a single iterator of OEBestOverlayScores. Thesorting function can be one of the pre-defined functors in chapter ?? or a user-defined version.The nbest default value of “1” implies that on the best overlay for each ref-fit conformer pair is returned. A valuegreater than one will mean multiple overlays for each ref-fit conformer pair will be kept.Setting conforder to “true” forces the results to come out in conformer index order. If nbest is greater than ’1”and conforder is “true”, then for each ref-fit conformer pair, the scores will be sorted by the sorting function,but each set of ref-fit results will come out together.Several of the OEBestOverlay examples show variations of these values. Perhaps the easiest way to understandthem is to modify one of the examples and observe the change in the number and order of the scores.
CHAPTERNINEOE<strong>Shape</strong> Namespaces9.1 OEBOMinTypenamespace OEBOMinType{const unsigned int Tanimoto = 1 ;const unsigned int Overlap = 2 ;const unsigned int Autoscale = 3 ; iconst unsigned int Default = Tanimoto ;}9.2 OEBOOrientationnamespace OEBOOrientation{const unsigned int Inertial = 1 ;const unsigned int AsIs = 2 ;const unsigned int Random = 3 ;const unsigned int Default = Inertial ;}9.3 OEColorFFTypenamespace OEColorFFType{const unsigned int Undefined = 0 ;const unsigned int OEDefault = 1 ;const unsigned int ImplicitMillsDean = 1 ;const unsigned int ExplicitMillsDean = 2 ;const unsigned int Max = 3 ;}9.4 OEOverlapMethod51
52 Chapter 9. OE<strong>Shape</strong> Namespacesnamespace OEOverlapMethod{const unsigned int Grid = 1 ;const unsigned int Analytic = 2 ;const unsigned int Analytic2 = 3 ;const unsigned int Exact = 4 ;const unsigned int Max = 5 ;}9.5 OEOverlapRadiinamespace OEOverlapRadii{const unsigned int Carbon = 1 ;const unsigned int Dual = 2 ;const unsigned int All = 3 ;const unsigned int Default = Carbon ;const unsigned int Max = 4 ;}9.6 OEOverlapRepresentationnamespace OEOverlapRepresentation{const unsigned int Atomic = 1 ;const unsigned int Atoms = 1 ;const unsigned int Bonding = 2 ;const unsigned int Bonds = 2 ;const unsigned int Full = 3 ;const unsigned int All = 3 ;const unsigned int Default = Atomic ;const unsigned int Max = 4 ;}
CHAPTERTENRelease Notes10.1 OE<strong>Shape</strong> 1.7.010.1.1 New Features1. Color Tanimoto is calculated just like shape Tanimoto by using the self color scores of each molecule combinedwith the actual color score. The end result is to better match molecules of the same color, penalizing amolecule for having too much as well as too little color. Color Tversky scores can be calculated as well. Wenow calculate these extra color scores in OEColorOverlap and OEBestOverlay.• OEColorResults now has Tanimoto, Tversky, RefTversky and FitTversky.• OEBestOverlayScore now has ColorTanimoto, ColorTversky, RefColorTversky, FitColorTversky andadds three new combo scores based on these:– TanimotoCombo - the sum of <strong>Shape</strong> Tanimoto and Color Tanimoto– RefTverskyCombo - the sum of Ref <strong>Shape</strong> Tversky and Ref Color Tversky– FitTverskyCombo - the sum of Fit <strong>Shape</strong> Tversky and Fit Color Tversky2. OEOverlapResults now has Tversky, RefTversky and FitTversky.10.1.2 Bug Fixes1. Fixed an internal memory leak in OEColorOverlap/OEBestOverlap color objects.2. Fixed a bug where in some cases the user-supplied value for carbon radius in OEOverlap was ignored.53
54 Chapter 10. Release Notes10.2 OE<strong>Shape</strong> 1.6.210.2.1 New Features1. Added the ability to get the expiration date from OE<strong>Shape</strong>IsLicensed function.10.2.2 Bug Fixes1. Fixed a memory leak in the calculation of self color in OEColorFunc.2. Fixed a bug that prevented pre-colored molecules from being used in OEColorFunc.3. Replace old error messages that just went to stderr and routed all errors and warnings via OEThrow.10.3 OE<strong>Shape</strong> 1.6.1This is the first release as part of the consolidated toolkits release.New features:1. Added functions to retrieve the version and build date of the library.Bug fixes:1. Changed to a stable sort inside OESortOverlayScores to prevent crashes with a very large number of results.2. Fixes to OEOverlap that in some cases could result in slow behavior when internal grids were rebuilt instead ofbeing cached.3. Fix a subtle bug that could resulted in erroneous behavior if reusing the same OEOverlap object and changingthe fit object from a grid to a molecule or from a molecule to a grid.10.4 OE<strong>Shape</strong> 1.6This release depends on OEChem 1.4.New features:1. Added new functions to calculate steric volume (OECalcVolume) and steric multipoles (OECalc<strong>Shape</strong>Multipoles).Bug Fixes:1. Fixed a bug where OEAddColorAtoms would not correctly add color atoms to a molecule that had the IntTypefield on atoms filled from a previous calculation. IntType is scratch space on atoms, so OEAddColorAtoms nowclears the IntType before adding color atoms to a molecule.
10.5. OE<strong>Shape</strong> 1.5 552. Changed one of the cation definitions in ImplicitMillsDean force field from from the too general (”n:1anaa1”)to to the more specific (”n:1cncc1”).3. Fixed a bug that caused OEBOOrientation::AsIs to not always start from the passed in positions.10.5 OE<strong>Shape</strong> 1.5First release in <strong>C++</strong>, Java and Python.
APPENDIXABibliography1. J.E.J. Mills and P.M. Dean, “Three-dimensional hydrogen-bond geometry and probability information froma crystal survey”, J Comput-Aided Mol Des, 10:607, 1996.56
INDEXAAddColorerOEColorForceField, 35AddInteractionOEColorForceField, 36AddScoreOEBestOverlayResults, 32AddTypeOEColorForceField, 36CClearOEBestOverlayResults, 32OEColorForceField, 36ClearColorForceFieldOEBestOverlay, 26ClearInteractionsOEColorForceField, 36ColorScoreOEColorOverlap, 38ConstructorsOEBestOverlay, 26OEBestOverlayResults, 32OEBestOverlayScore, 33OEColorForceField, 35OEColorOverlap, 37OEColorResults, 39OEOverlap, 44OEOverlapResults, 46GGetAllColorOEBestOverlay, 27OEColorOverlap, 38GetCarbonRadiusOEBestOverlay, 27OEOverlap, 44GetColorTanimotoOEBestOverlayScore, 33GetColorTverskyOEBestOverlayScore, 33GetComboScoreOEBestOverlayScore, 34GetFitColorTverskyOEBestOverlayScore, 34GetFitTverskyOEBestOverlayScore, 34OEColorResults, 39OEOverlapResults, 46GetFitTverskyComboOEBestOverlayScore, 34GetHandleOEOverlap, 44GetInertialAxialDivisionsOEBestOverlay, 27GetInitialOrientationOEBestOverlay, 27GetMaxRandomTranslationOEBestOverlay, 27GetMethodOEBestOverlay, 27OEOverlap, 44GetMinimizeTypeOEBestOverlay, 27GetNumRandomStartsOEBestOverlay, 27GetRadiiApproximationOEBestOverlay, 28OEOverlap, 44GetRandomSeedOEBestOverlay, 28GetRefColorTverskyOEBestOverlayScore, 34GetRefGridOEBestOverlay, 28GetRefMolOEBestOverlay, 28GetRefSelfColor57
58 IndexOEBestOverlay, 28GetRefSymmetryOEBestOverlay, 28GetRefTverskyOEBestOverlayScore, 34OEColorResults, 39OEOverlapResults, 47GetRefTverskyComboOEBestOverlayScore, 34GetRepresentationLevelOEBestOverlay, 28OEOverlap, 44GetScoresOEBestOverlayResults, 32GetSelfColorOEColorOverlap, 38GetSymmetryThresholdOEBestOverlay, 28GetTanimotoOEColorResults, 39GetTanimotoComboOEBestOverlayScore, 34GetTitleOEColorForceField, 36GetTverskyOEBestOverlayScore, 35OEColorResults, 39OEOverlapResults, 47GetTypeOEColorForceField, 36GetTypeNameOEColorForceField, 36GetUseHydrogensOEBestOverlay, 28OEOverlap, 45IInitOEColorForceField, 37OOEAddColorAtoms, 48OEBestOverlay, 26ClearColorForceField, 26Constructors, 26GetAllColor, 27GetCarbonRadius, 27GetInertialAxialDivisions, 27GetInitialOrientation, 27GetMaxRandomTranslation, 27GetMethod, 27GetMinimizeType, 27GetNumRandomStarts, 27GetRadiiApproximation, 28GetRandomSeed, 28GetRefGrid, 28GetRefMol, 28GetRefSelfColor, 28GetRefSymmetry, 28GetRepresentationLevel, 28GetSymmetryThreshold, 28GetUseHydrogens, 28operator=, 26Overlay, 29SetAllColor, 29SetCarbonRadius, 29SetColorForceField, 29SetColorOptimize, 29SetInertialAxialDivisions, 29SetInitialOrientation, 30SetMaxRandomTranslation, 30SetMethod, 30SetMinimizeType, 30SetNumRandomStarts, 30SetRadiiApproximation, 30SetRandomSeed, 30SetRefGrid, 31SetRefMol, 31SetRepresentationLevel, 31SetSymmetryThreshold, 31SetUseHydrogens, 31OEBestOverlayResults, 31AddScore, 32Clear, 32Constructors, 32GetScores, 32operator=, 32OEBestOverlayScore, 33Constructors, 33GetColorTanimoto, 33GetColorTversky, 33GetComboScore, 34GetFitColorTversky, 34GetFitTversky, 34GetFitTverskyCombo, 34GetRefColorTversky, 34GetRefTversky, 34GetRefTverskyCombo, 34GetTanimotoCombo, 34GetTversky, 35Transform, 35OEBOMinType, 51
Index 59OEBOOrientation, 51OECalc<strong>Shape</strong>Multipoles, 48OECalcVolume, 48OEColorFFType, 51OEColorForceField, 35AddColorer, 35AddInteraction, 36AddType, 36Clear, 36ClearInteractions, 36Constructors, 35GetTitle, 36GetType, 36GetTypeName, 36Init, 37operator=, 35Ready, 37SetTitle, 37Write, 37OEColorOverlap, 37ColorScore, 38Constructors, 37GetAllColor, 38GetSelfColor, 38operator=, 38SetAllColor, 38SetColorForceField, 38SetFitMol, 38SetRefMol, 39OEColorResults, 39Constructors, 39GetFitTversky, 39GetRefTversky, 39GetTanimoto, 39GetTversky, 39OECountColorAtoms, 48OEHasColorAtoms, 49OEHighestColorTanimoto, 39OEHighestComboScore, 40OEHighestFitColorTversky, 40OEHighestFitTversky, 40OEHighestFitTverskyCombo, 41OEHighestOverlap, 41OEHighestRefColorTversky, 41OEHighestRefTversky, 42OEHighestRefTverskyCombo, 42OEHighestScaledColor, 42OEHighestTanimoto, 43OEHighestTanimotoCombo, 43OEOverlap, 43Constructors, 44GetCarbonRadius, 44GetHandle, 44GetMethod, 44GetRadiiApproximation, 44GetRepresentationLevel, 44GetUseHydrogens, 45operator=, 44Overlap, 45SetCarbonRadius, 45SetFitGrid, 45SetFitMol, 45SetMethod, 45SetRadiiApproximation, 45SetRefGrid, 45SetRefMol, 46SetRepresentationLevel, 46SetUseHydrogens, 46OEOverlapMethod, 51OEOverlapRadii, 52OEOverlapRepresentation, 52OEOverlapResults, 46Constructors, 46GetFitTversky, 46GetRefTversky, 47GetTversky, 47OERemoveColorAtoms, 49OESelfColor, 49OE<strong>Shape</strong>GetPlatform, 49OE<strong>Shape</strong>GetRelease, 49OE<strong>Shape</strong>GetVersion, 49OE<strong>Shape</strong>IsLicensed, 49OESortOverlayScores, 50operator=OEBestOverlay, 26OEBestOverlayResults, 32OEColorForceField, 35OEColorOverlap, 38OEOverlap, 44OverlapOEOverlap, 45OverlayOEBestOverlay, 29RReadyOEColorForceField, 37SSetAllColorOEBestOverlay, 29OEColorOverlap, 38
60 IndexSetCarbonRadiusOEBestOverlay, 29OEOverlap, 45SetColorForceFieldOEBestOverlay, 29OEColorOverlap, 38SetColorOptimizeOEBestOverlay, 29SetFitGridOEOverlap, 45SetFitMolOEColorOverlap, 38OEOverlap, 45SetInertialAxialDivisionsOEBestOverlay, 29SetInitialOrientationOEBestOverlay, 30SetMaxRandomTranslationOEBestOverlay, 30SetMethodOEBestOverlay, 30OEOverlap, 45SetMinimizeTypeOEBestOverlay, 30SetNumRandomStartsOEBestOverlay, 30SetRadiiApproximationOEBestOverlay, 30OEOverlap, 45SetRandomSeedOEBestOverlay, 30SetRefGridOEBestOverlay, 31OEOverlap, 45SetRefMolOEBestOverlay, 31OEColorOverlap, 39OEOverlap, 46SetRepresentationLevelOEBestOverlay, 31OEOverlap, 46SetSymmetryThresholdOEBestOverlay, 31SetTitleOEColorForceField, 37SetUseHydrogensOEBestOverlay, 31OEOverlap, 46OEBestOverlayScore, 35WWriteOEColorForceField, 37TTransform