OEShapeDatabaseScore¶

class OEShapeDatabaseScore

This object is used to represent the result of a FastROCS TK calculation returned by the OEShapeDatabase::GetSortedScores and OEShapeDatabase::GetScores methods.

It encapsulates the following information:

Score information:
Overlay recreation:
Molecule retrieval: * OEShapeDatabaseScore::GetMolIdx * OEShapeDatabaseScore::GetConfIdx

Warning

The molecular transforms returned by OEShapeDatabaseScore::GetQuat, OEShapeDatabaseScore::GetRotMatrix, and OEShapeDatabaseScore::GetTranslation assume the conformer has already been aligned by OESetCoordsToInertialFrame.

While it was definitely in-elegant to require calling OESetCoordsToInertialFrame in order to reproduce overlays, this allows OEShapeDatabase to not store 28 bytes of memory per conformer, a significant space savings, especially when conformers are stored in rotor-compressed form.

Overlays are usually only required for a small number of conformations, so re-calculating this for only the “hits” is a small price to pay for potentially saving gigabytes of memory on an already memory constrained problem.

Users should prefer to use the OEShapeDatabaseScore::Transform directly to avoid having to deal with this subtlety, it will automatically do all the transformations necessary to generate overlays.

Constructors¶

OEShapeDatabaseScore(size_t molIdx, unsigned int confIdx, float shapeTani,
                     float colorTani, const float *quat,
                     unsigned int csimFunc=OEShapeSimFuncType::Default,
                     unsigned int orient=OEFastROCSOrientation::Default)
OEShapeDatabaseScore(size_t molIdx, unsigned int confIdx, float shapeTani,
                     float colorTani, const double *quat,
                     unsigned int csimFunc=OEShapeSimFuncType::Default,
                     unsigned int orient=OEFastROCSOrientation::Default)

Constructs a new score object with the specified data. Typically only used by the internals of FastROCS TK in order to populate the hitlist.

Warning

The constructor has changed in order to support OEFastROCSOrientation::AsIs. The constant OEFastROCSOrientation::Default, drawn from the OEFastROCSOrientation namespace, has been added to the argument list. The default is OEFastROCSOrientation::Inertial and the last argument should be left blank unless it is intended to use OEFastROCSOrientation::AsIs starts on the database being loaded, in which case unsigned int orient=OEFastROCSOrientation::AsIs should be passed to the constructor.

Warning

The constructor has changed in order to support Tversky scoring. The constant “OEShapeSimFuncType::Default”, drawn from the OEShapeSimFuncType namespace, has been added to the argument list. The default is “Tanimoto”. “Tversky” scoring is chosen by passing OEShapeSimFuncType::Tversky and setting OEShapeDatabaseOptions::SetSimFunc to “Tversky”.

GetColorScore¶

float GetColorScore() const

Returns the “color” component of the score used for ranking molecules by FastROCS TK. See the Molecular Shape section of the ShapeTK theory documentation for a description of the calculation. This function should be used in conjunction with OEShapeDatabaseOptions::GetSimFunc in order to determine which similarity function (“Tanimoto” or “Tversky”) was used to calculate the scores. This function will return 0.0 if the search was requested to be “shape only”, i.e., only OEShapeDatabaseType::Shape was specified.

GetColorTanimoto¶

float GetColorTanimoto() const

Returns the “color” component of the Tanimoto score used for ranking molecules by FastROCS TK. See the Color Features section in the Shape TK theory documentation for a description of what the “color” term is. This function will return 0.0 if the search was requested to be “shape only”, i.e., only OEShapeDatabaseType::Shape was specified.

Note

A color tanimoto of 0.0 is also possible if either the query or database molecule does not contain any color atoms. Even more surprising is that this value can sometimes exceed 1.0, which appears to violate the definition of “tanimoto”. This is due to the first-order-gaussian approximation used, i.e, intersection volumes are not actually subtracted out since they have little effect on virtual screening performance and would be significantly more costly to calculate. Typically, these cases are limited to complex cage systems like cubane that have many overlapping “ring” color atoms that heavily overlap. The use of the “ring” color term can be customized by using a custom color field specified through the OEShapeDatabase constructor.

GetColorTversky¶

float GetColorTversky() const

Returns the “color” component of the Tversky score used for ranking molecules by FastROCS TK. See the Color Features section in the Shape TK theory documentation for a description of what the “color” term is. This function will return 0.0 if the search was requested to be “shape only”, i.e., only OEShapeDatabaseType::Shape was specified. If “Tversky” scoring was not set using OEShapeDatabaseOptions::SetSimFunc prior to the search this function will return with an error.

GetConfIdx¶

unsigned int GetConfIdx() const

Returns the conformer’s index of the matching conformer for this particular score. This index will match the index returned by the OEConfBase::GetIdx method. This allows retrieving the conformer from the OEMCMolBase::GetConf method using the OEHasConfIdx predicate like the following:

conf = mol.GetConf(OEHasIdx(score.GetConfIdx()))

GetMolIdx¶

size_t GetMolIdx() const

Returns the molecule index that returned this particular “score”. This index maps to the indices used by OEMolDatabase to retrieve molecules assuming the OEShapeDatabase was initialized with the OEShapeDatabase::Open method. This allows FastROCS TK to rely on disk-based storage through OEMolDatabase to retrieve overlays and provide connection tables, a significant memory space savings. However, this does come at the added latency and computational expense of the OEMolDatabase::GetMolecule method.

To allow for use cases other than virtual screening where only a small number of “hits” need to be sent on for further processing. This index may map to the index returned by the OEShapeDatabase::AddMol method. It is up to the user to decide how to store the OEMCMolBase for later access. Previously versions of FastROCS TK used OEMCMolType::OEDBMCMol molecules for this purpose.

GetQuat¶

const float *GetQuat() const

Warning

It will be easier to use the OEShapeDatabaseScore::Transform method than to use figure out how to use the data from this function.

Returns a pointer to a 7-element quaternion that can be used to overlay the database conformer represented by this score with the query conformation. This 7-element quaternion contains both the rotation and translational components: the first 4 elements being the quaternion rotation; the second 3 elements are the translational component.

Warning

Read FastROCS transforms warning above about performing overlays with these more advanced methods.

GetRotMatrix¶

bool GetRotMatrix(float *rmat) const

Warning

It will be easier to use the OEShapeDatabaseScore::Transform method than to use figure out how to use the data from this function.

Fills in the 9-element rotation matrix rmat with the rotation component needed to overlay the database conformer represented by this score with the query conformation. Returns false if the rotation matrix is ill-defined, i.e., the conversion from the underlying quaternion failed.

Warning

Read FastROCS transforms warning above about performing overlays with these more advanced methods.

GetScore¶

float GetScore() const

Returns the sum of the “shape” and “color” scores. This function should be used in conjunction with OEShapeDatabaseOptions::GetSimFunc in order to determine which similarity function (“Tanimoto” or “Tversky”) was used to calculate the scores.

GetShapeScore¶

float GetShapeScore() const

Returns the “shape” component of the score used for ranking molecules by FastROCS TK. See the Molecular Shape section of the Shape TK theory documentation for a description of the calculation. This function should be used in conjunction with OEShapeDatabaseOptions::GetSimFunc in order to determine which similarity function (“Tanimoto” or “Tversky”) was used to calculate the scores.

Currently, it is not possible to request a “color only” calculation from FastROCS TK. Therefore, this function should always be greater than 0.0. A value of 0.0 would be a molecule with no volume, which is impossible.

GetShapeTanimoto¶

float GetShapeTanimoto() const

Returns the “shape” component of the tanimoto score used for ranking molecules by FastROCS TK. See the Molecular Shape section in the Shape TK theory documentation for a description of how this is calculated.

Currently, it is not possible to request a “color only” calculation from FastROCS TK. Therefore, this function should always be greater than 0.0. A value of 0.0 would be a molecule with no volume, which is impossible.

Note

It is possible, though rare, to see values slightly greater than 1.0 in the 2nd decimal place. This is due to the approximation FastROCS TK uses for performance and can be disregarded, especially since they usually only occur whenever a molecule is matched against itself.

GetShapeTversky¶

float GetShapeTversky() const

Returns the “shape” component of the tversky score used for ranking molecules by FastROCS TK. See the Molecular Shape section in the Shape TK theory documentation for a description of how this is calculated. If “Tversky” scoring was not set using OEShapeDatabaseOptions::SetSimFunc prior to the search this function will return with an error.

As with the “Tanimoto” scoring option, it is not currently possible to request a “color only” calculation from FastROCS TK. Therefore, this function should always be greater than 0.0. If this is not the case an error has occurred.

Note

It is possible, though rare, to see values slightly greater than 1.0 in the 2nd decimal place. This is due to the approximation FastROCS TK uses for performance and can be disregarded, especially since they usually only occur whenever a molecule is matched against itself.

GetSimFunc¶

unsigned int GetSimFunc() const

Returns a constant from the OEShapeSimFuncType namespace indicating what type of similarity function, “Tanimoto” or “Tversky”, is being used for scoring.

GetTanimotoCombo¶

float GetTanimotoCombo() const

Returns the sum of the “color” and “shape” tanimotos.

GetTranslation¶

bool GetTranslation(float *trans) const

Warning

It will be easier to use the OEShapeDatabaseScore::Transform method than to use figure out how to use the data from this function.

Fills in the 3-element vector trans with the translation component needed to overlay the database conformer represented by this score with the query conformation. Returns false if the translation is ill-defined, i.e., something went horribly wrong.

Warning

Read FastROCS transforms warning above about performing overlays with these more advanced methods.

ExtractTransform¶

bool ExtractTransform(OETrans &transform, OEChem::OEMolBase &mol) const

Fills in the OETrans object with the translation and rotation matrix necessary to transform mol onto the query. Note that OEShapeDatabaseScore::Transform is the preferred method for visualizing overlays. This method is available for the case in which you need to know exactly what transform was performed. For example, when you want to use the same transform on another molecule.

GetTverskyCombo¶

float GetTverskyCombo() const

Returns the sum of the “color” and “shape” Tversky scores. If “Tversky” scoring was not set using OEShapeDatabaseOptions::SetSimFunc prior to the search this function will return with an error.

Transform¶

bool Transform(OEChem::OEMolBase &mol) const

Overlays the conformer represented by mol with the query conformation passed as the query to OEShapeDatabase. This overlay will be the orientation that was used to calculate the scores returned by the rest of this class.