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

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

## ClearUserStarts¶

void ClearUserStarts()


Removes any user inertial starts that have been previously set.

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

## GetCutoffGT¶

float GetCutoffGT() const


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

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

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

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

## GetMaxRandomTranslation¶

float GetMaxRandomTranslation() const


Returns the maximum allowed translation when using random starting orientations. The default maximum is 2 angstroms.

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

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

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

## GetNumRandomStarts¶

unsigned int GetNumRandomStarts()


Returns the number of random starting orientations when using the OEFastROCSOrientation.Random alternative start. The default value is 10.

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

## GetRandomSeed¶

unsigned int GetRandomSeed() const


Returns the random seed to be used with OEFastROCSOrientation.Random. The default random seed is set based on the time.

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

Warning

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

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

## HasCutoffGT¶

bool HasCutoffGT() const


This method is identical in functionality to OEShapeDatabaseOptions.HasCutoff and is mutually exclusive to OEShapeDatabaseOptions.HasCutoffLT.

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

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

## SetCutoffGT¶

void SetCutoffGT(float cutoff)


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

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

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

Warning

If attempting to use OEShapeDatabaseOptions.SetNumInertialStarts with OEShapeDatabaseOptions.SetInitialOrientation please ensure the number of inertial starts is set after the initial orientation otherwise the number of inertial starts will be overridden with the default value of 4.

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

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

## SetMaxRandomTranslation¶

bool SetMaxRandomTranslation(float trans)


Set the maximum allowed translation for each random orientation. The default is 2 angstroms. This method requires OEShapeDatabaseOptions.SetInitialOrientation to be set to OEFastROCSOrientation.Random.

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

Warning

If attempting to use OEShapeDatabaseOptions.SetNumInertialStarts with OEShapeDatabaseOptions.SetInitialOrientation please ensure the number of inertial starts is set after the initial orientation otherwise the number of inertial starts will be overridden with the default value of 4.

## SetRandomSeed¶

bool SetRandomSeed(unsigned int seed)


Sets the random seed to be used with OEFastROCSOrientation.Random. Returns true if successfully set. The default random seed is set based on the time.

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