OEShapeDatabaseOptions

class OEShapeDatabaseOptions

This class is used to control the behavior of OEShapeDatabase.GetScores and OEShapeDatabase.GetSortedScores. It allows setting options on a per-search basis.

Note

It is possible for the options selected in this class to not match the settings of the constructed OEShapeDatabase causing an error to be thrown.

Constructors

OEShapeDatabaseOptions()
OEShapeDatabaseOptions(const OEShapeDatabaseOptions &)

Default constructor for creating a new instance with default options. The copy constructor will copy all the options into a new object.

operator=

OEShapeDatabaseOptions &operator=(const OEShapeDatabaseOptions &)

Assignment operator for making a copy of the options.

ClearCutoff

void ClearCutoff()

Removes the cutoff from this set of options. The default is to have no cutoff value specified.

See also

ClearTracer

void ClearTracer()

Removes the progress bar tracer from this set of options.

Note

This does not release the memory of the OEDBTracerBase previously passed to OEShapeDatabaseOptions.SetTracer.

See also

OEShapeDatabaseOptions.SetTracer

ClearUserStarts

void ClearUserStarts()

Removes any user inertial starts that have been previously set.

See also

OEShapeDatabaseOptions.SetUserStarts OEShapeDatabaseOptions.GetUserStarts OEShapeDatabaseOptions.GetNumStarts

GetColorOptimization

bool GetColorOptimization() const;

Returns true if color score is being optimized in addition to shape score.

See also

GetCutoff

float GetCutoff() const

Returns the cutoff currently set in this set of options. The default is a cutoff of 0.0, i.e., no cutoff, all scores will be returned. This is mutually exclusive to OEShapeDatabaseOptions.GetCutoffLT.

Note

This cutoff is applied to the final ranking score used. For a OEShapeDatabaseType_Shape database, that means only the “shape” score. For the default database type, OEShapeDatabaseType_Default, the cutoff is applied to the sum of the shape and color components (OEShapeDatabaseScore.GetTanimotoCombo).

See also

GetCutoffGT

float GetCutoffGT() const

This method is identical in functionality to OEShapeDatabaseOptions.GetCutoff and is mutually exclusive to OEShapeDatabaseOptions.GetCutoffLT.

See also

GetCutoffLT

float GetCutoffLT() const

Returns the cutoff currently set in this set of options. The default is no cutoff, all scores will be returned. This method applies to a cutoff set using OEShapeDatabaseOptions.SetCutoffLT to retrieve results less than or equal to the cutoff value.

Note

This cutoff is applied to the final ranking score used. For a OEShapeDatabaseType_Shape database, that means only the “shape” score. For the default database type, OEShapeDatabaseType_Default, the cutoff is applied to the sum of the shape and color components (OEShapeDatabaseScore.GetTanimotoCombo).

See also

GetInitialOrientation

unsigned int GetInitialOrientation() const

Returns the initial orientation to be used for the overlay optimization drawn from the OEFastROCSOrientation namespace. The default orientation is OEFastROCSOrientation_Inertial

See also

GetFastROCSMode

unsigned int GetFastROCSMode() const

Returns the calculation mode to be used for the overlay optimization drawn from the OEFastROCSMode namespace. The default mode is OEFastROCSMode_FastROCS

See also

GetLimit

unsigned int GetLimit() const

Returns the number of individual molecule “hits” that will be returned from OEShapeDatabase.GetSortedScores, i.e., the number of individual OEShapeDatabaseScore objects that will be returned.

Note

This method has no effect on the OEShapeDatabase.GetScores method.

GetMaxConfs

unsigned int GetMaxConfs() const

Returns the maximum number of conformers to return per molecule. By default this value is 1 indicating only the best conformer of a molecule that matched the query molecule will be returned as a single OEShapeDatabaseScore object. The conformer with the highest score will be indicated by the OEShapeDatabaseScore.GetConfIdx method.

GetMaxOverlays

unsigned int GetMaxOverlays() const

Returns the maximum number of starting points per conformer overlaid. By default this value is 1 indicating only the best of all optimizations performed will be returned.

GetNumInertialStarts

unsigned int GetNumInertialStarts() const

Returns the number of inertial starts used as starting points for the shape optimization. The default value is 4 starting points oriented along the principle moment of inertia.

GetNumStarts

unsigned int GetNumStarts() const
unsigned int GetNumStarts(const OEChem::OEMolBase &query) const

Returns the number of alternative starting points set for shape optimization. When using OEFastROCSOrientation_InertialAtHeavyAtoms or OEFastROCSOrientation_InertialAtColorAtoms the query molecule is required by the method. If alternative starts have not been set or OEFastROCSOrientation_AsIs is set, these methods will return a value of 1.

See also

GetNumColorAtomStarts

unsigned int GetNumColorAtomStarts(const OEChem::OEMolBase &query) const

Returns the number of color atom starting points set for shape optimization. This method requires OEShapeDatabaseOptions.SetInitialOrientation to be set to OEFastROCSOrientation_InertialAtColorAtoms and the query molecule. If the query molecule does not have color atoms the search will throw a warning and default to OEFastROCSOrientation_Inertial.

See also

GetNumHeavyAtomStarts

unsigned int GetNumHeavyAtomStarts(const OEChem::OEMolBase &query) const

Returns the number of heavy atom starting points set for shape optimization. This method requires OEShapeDatabaseOptions.SetInitialOrientation to be set to OEFastROCSOrientation_InertialAtHeavyAtoms and the query molecule.

See also

GetNumUserStarts

unsigned int GetNumUserStarts() const

Returns the number of user-defined starting points set for shape optimization. This method requires OEShapeDatabaseOptions.SetInitialOrientation to be set to OEFastROCSOrientation_UserInertialStarts and user-starts to have been set with OEShapeDatabaseOptions.SetUserStarts.

See also

GetScoreType

unsigned int GetScoreType() const

Returns the score type drawn from the OEShapeDatabaseType namespace to be used for the search.

GetSimFunc

unsigned int GetSimFunc() const

Returns the type of similarity function to be used to score the search results. The constant type returned is either ‘Tanimoto’ or ‘Tversky’ which is drawn from the OEShapeSimFuncType namespace.

GetTracer

OEDBTracerBase *GetTracer() const

Returns a pointer to the OEDBTracerBase to be used to track the progress of this search. Returns a NULL pointer to indicate that no tracer has been registered.

GetTverskyAlpha

float GetTverskyAlpha() const

Returns the alpha coefficient used in the Tversky similarity calculation. See OEShapeDatabaseOptions.SetTverskyCoeffs for details of how to set alpha. The default value is 0.95.

GetTverskyBeta

float GetTverskyBeta() const

Returns the beta coefficient used in the Tversky similarity calculation. See OEShapeDatabaseOptions.SetTverskyCoeffs for details of how to set beta. The default value is 0.05.

GetUserStarts

bool GetUserStarts(vector<float> &startsCoords) const

Fills a float vector of size number of starts * 3 with the starting coordinates previously set with OEShapeDatabaseOptions.SetUserStarts. To ensure vector of the correct size is passed in as an argument, the OEShapeDatabaseOptions.GetNumStarts method can be used to retrieve the number of starts set. If successful the return value will be true. The following code snippet shows example usage in python.

coords = oechem.OEFloatVector(opts.GetNumStarts() * 3)
opts.GetUserStarts(coords)

Warning

Code is not available. FastROCS TK is only supported in Python.

See also

HasCutoff

bool HasCutoff() const

Returns a boolean value indicating whether a cutoff value, at which all scores greater than or equal to the value will be saved and all scores less than the value will be discarded, has been previously registered with this set of options. By default this is false, no cutoff. If OEShapeDatabaseOptions.SetCutoff or OEShapeDatabaseOptions.SetCutoffGT has been called already, this will return true. OEShapeDatabaseOptions.ClearCutoff will set this back to false again. This method is mutually exclusive to OEShapeDatabaseOptions.HasCutoffLT

See also

HasCutoffLT

bool HasCutoffLT() const

Returns a boolean value indicating whether a cutoff value, at which all scores less than or equal to the value will be saved and all scores greater than the value will be discarded, has been previously registered with this set of options. By default this is false, no cutoffLT. If OEShapeDatabaseOptions.SetCutoffLT has been called already, this will return true. OEShapeDatabaseOptions.ClearCutoff will set this back to false again. This method is mutually exclusive to OEShapeDatabaseOptions.HasCutoffGT

See also

SetColorOptimization

void SetColorOptimization(bool ColorOptimization);

Set to true to optimize over color score in addition to shape score. Default is false.

Note

optimizing over color will impact performance. A decrease in 5-20% can be expected.

See also

SetCutoff

void SetCutoff(float cutoff)

Sets the cutoff to use when filtering the results of OEShapeDatabase.GetScores and OEShapeDatabase.GetSortedScores. Only OEShapeDatabaseScore objects greater than or equal to cutoff depending on the score type will be returned. This method is mutually exclusive to OEShapeDatabaseOptions.SetCutoffLT

Note

This cutoff is applied to the final ranking score used. For a OEShapeDatabaseType_Shape database, that means only the “shape” score. For the default database type, OEShapeDatabaseType_Default, the cutoff is applied to the sum of the shape and color components (OEShapeDatabaseScore.GetTanimotoCombo).

See also

SetCutoffGT

void SetCutoffGT(float cutoff)

This method is identical in functionality to OEShapeDatabaseOptions.SetCutoff and is mutually exclusive to OEShapeDatabaseOptions.SetCutoffLT.

See also

SetCutoffLT

void SetCutoffLT(float cutoff)

Sets the cutoff to use when filtering the results of OEShapeDatabase.GetScores and OEShapeDatabase.GetSortedScores. Only OEShapeDatabaseScore objects less than or equal to cutoff depending on the score type will be returned.

This method is mutually exclusive to OEShapeDatabaseOptions.SetCutoff.

Note

This cutoff is applied to the final ranking score used. For a OEShapeDatabaseType_Shape database, that means only the “shape” score. For the default database type, OEShapeDatabaseType_Default, the cutoff is applied to the sum of the shape and color components (OEShapeDatabaseScore.GetTanimotoCombo).

See also

SetFastROCSMode

unsigned int SetFastROCSMode(unsigned int ) const

Sets the calculation mode to be used for the overlay optimization drawn from the OEFastROCSMode namespace. The default mode is OEFastROCSMode_FastROCS

See also

SetInitialOrientation

bool SetInitialOrientation(unsigned int orient=OEFastROCSOrientation::Default)

Set the initial orientation to be used for optimization of the overlap. The options are drawn from the OEFastROCSOrientation and the default is OEFastROCSOrientation_Inertial. If user-defined inertial starts are to be used then the starting coordinates must be set using the OEShapeDatabaseOptions.SetUserStarts method. Returns true if successful.

See also

SetNumRandomStarts

bool SetNumRandomStarts(unsigned int numStarts)

Set the number of random starting orientations when using the OEFastROCSOrientation_Random alternative start. The default value is 10.

Warning

Search speed and the amount of RAM required are proportional to the number of starting orientations therefore speed & memory degradation are to be expected if searching with a large number of random starting orientations.

See also

SetLimit

void SetLimit(unsigned int limit)

Set the number of individual OEShapeDatabaseScore objects that will be returned by OEShapeDatabase.GetSortedScores. This is a hard limit regardless of the multiplicative effect of also setting the OEShapeDatabaseOptions.SetMaxConfs and OEShapeDatabaseOptions.SetMaxOverlays methods to values greater than 1.

Note

This method has no effect on the OEShapeDatabase.GetScores method.

SetMaxConfs

void SetMaxConfs(unsigned int maxConfs)

Set how many conformers per molecule should be returned in the results. The default value is 1, only the best conformer for each database molecule will be returned as an OEShapeDatabaseScore object. The conformer with the highest score will be indicated by the OEShapeDatabaseScore.GetConfIdx method.

Setting this value to 0 means all database conformers will be returned for every molecule in the database.

SetMaxOverlays

void SetMaxOverlays(unsigned int maxOverlaysToReturn)

Set how many starting points to return per conformer in the database. The default value is 1, only the best starting point for the conformer will be returned as an OEShapeDatabaseScore object.

Setting this value to 0 means all the starting points will be returned, i.e., there will be OEShapeDatabaseOptions.GetNumInertialStarts objects returned.

SetNumInertialStarts

void SetNumInertialStarts(unsigned int numStarts)

Set how many starting points the shape optimization will use. Currently, only values between 1 and 8 inclusive can be set. The default value is 4, i.e., assume there is a dominant moment of inertia for both the query and database conformer. Setting this value higher can yield better global overlays. However, there is a direct linear relation between the performance of FastROCS TK and the number of starting points.

SetScoreType

void SetScoreType(unsigned int type)

Sets which scores to perform during the search. The constant type should be drawn from the OEShapeDatabaseType namespace.

Note

The score type must be a proper subset of the score enabled during OEShapeDatabase construction. That means if the database was started in “shape only” mode, this value can not include OEShapeDatabaseType_Color.

SetSimFunc

void SetSimFunc(unsigned int type)

Sets which type of similarity function to use to score search results. The constant type should be either “Tanimoto” or “Tversky” and should be drawn from the OEShapeSimFuncType.

SetTracer

void SetTracer(OEDBTracerBase &tracer)

Register a progress bar tracer with this set of options. The tracer will be updated with a count as chunks of the database are processed. It is very important that the implementation of OEDBTracerBase is thread-safe as it will be updated from multiple threads simultaneously. It is also expected that the consumer of the progress bar will be operating in a separate thread to avoid wasting search thread time on progress update overhead.

Warning

The user must take care to keep the tracer in scope during the full duration of the OEShapeDatabase.GetScores or OEShapeDatabase.GetSortedScores call. The options object will not make a copy of the tracer at all, merely storing a pointer to the tracer. If the tracer is prematurely deleted, this will very likely result in a crash. Probably in a non-deterministic way due to the threading involved.

SetTverskyCoeffs

void SetTverskyCoeffs(float alpha, float beta)

Sets the alpha and beta coefficients to be used in the Tversky similarity calculation. See the Molecular Shape section in the Shape TK theory documentation for a description of how this is calculated. Default values for alpha and beta are 0.95 and 0.05, respectively. Any new values of alpha and beta can be chosen provided they add up to 1.00.

SetUserStarts

bool SetUserStarts(vector<float> &startsCoords, unsigned int numStarts)

Sets the user-defined starting coordinates. The arguments are a vector of floats of length 3 * the number of starting points (x, y and z coordinates for each start) - startsCoords and the number of starting coordinates in an unsigned int variable - numStarts.

Warning

Currently, error checking is not performed for user-defined starting coordinates that fall out of scope of the molecule’s coordinate range therefore, bad starting coordinates will yield zero shape/color overlap. It is the responsibility of the user to ensure sensible starting coordinates.

The following code snippet shows how to use OEShapeDatabaseOptions.SetInitialOrientation and OEShapeDatabaseOptions.SetUserStarts in a python example.

opts = oefastrocs.OEShapeDatabaseOptions()
opts.SetInitialOrientation(oefastrocs.OEFastROCSOrientation_UserInertialStarts)

startsCoords = oechem.OEFloatVector()

startsCoords.append(float(1.45))
startsCoords.append(float(6.78))
startsCoords.append(float(-3.21))

opts.SetUserStarts(startsCoords, len(startsCoords) / 3)

See also