OEFastROCS ShapeDatabaseServer XMLRPC API¶

This chapter documents the XMLRPC API that is exposed by the ShapeDatabaseServer.py server since the 1.0 release of FastROCS. Since that release many users have created internal clients to the server that depend on that XMLRPC API, so OpenEye has strived to keep this API stable for pre-existing client code. This chapter should serve as a guide for anyone looking to create a new FastROCS server around the toolkit API.

Most users can just use the ShapeDatabaseClient.py script directly, without the need to worry about the details of the protocol between the client and server.

Note

The XMLRPC API will be replaced by a RESTful API in a future version of FastROCS TK.

GetBestOverlays¶

GetBestOverlays(querymolstr, nhits, iformat=".oeb", oformat=".oeb") -> Binary

Return the nhits results of the database search performed with the query querymolstr. The file format of the data in the XML RPC Binary querymolstr is specified by the iformat argument. Valid iformat arguments are any OEChem supported molecular file format that OEIs3DFormat will return True for. This is because FastROCS TK requires a 3D conformation to search against.

The returned XML RPC Binary will contain the best nhits of query against the database. The returned XML RPC Binary will contain the molecule sorted by the chosen scoring function for the database. nhits of 0 specifies that all database molecules should be returned in sorted order, not a very advisable operation as that could move many megabytes to gigabytes of data over the network.

The file format of the returned XML RPC Binary is specified by the oformat argument. This can be any OEChem supported file format that OEIsWriteable will return True for. However, scores are only stored as SD data, so only the following file formats will return score information:

Furthermore, the molecules returned will be aligned to the query molecule in 3D. So only formats that can represent 3D information will actually contain the resulting alignment.

GetName¶

GetName() -> str

Return the name of the database being served from the server. By default, this is the filename the server was started with. However, this can be changed by the SetName remote procedure call.

GetVersion¶

GetVersion() -> str

Return the version of FastROCS TK being run on the server.

IsLoaded¶

IsLoaded(blocking=False) -> bool

Returns True if the server has finished loading the database into memory and ready to accept queries. Returns False if the server is still initializing, causing any queries submitted to wait in a queue before they can be processed.

OEThrowSetLevel¶

OEThrowSetLevel(level)

Turns on debugging information for the server, or turning it back off again. The integer level should be drawn from the OEErrorLevel namespace. FastROCS TK uses OEThrow to handle all logging information. FastROCS TK will throw lots of performance debugging information to the OEErrorLevel_Debug level that will not be seen by default. When contacting OpenEye support about FastROCS (support@eyesopen.com), including this information would be very beneficial to helping solve the problem.

QueryHistogram¶

QueryHistogram(queryidx) -> [int, ..., int]

Return the current distribution of scores for the search specified by the queryidx. The distribution is returned as a list of integers. The distribution of scores can be retrieved in ‘real-time’ during a search as well, though it is recommended to still use QueryStatus with the blocking parameter set to True to avoid spurious requests and load on the server.

The distribution is only guaranteed to be a complete distribution of all the scores once the query has fully completed executing. A query is fully complete when the integers returned by QueryStatus are equal and both non-zero.

QueryStatus¶

QueryStatus(queryidx, blocking=False) -> (int, int)

Return the current progress of the search specified by the queryidx. The progress is returned as a pair of integers. The first integer in the pair is how many conformers have already been searched. The second integer in the pair is how many conformers there are total in the database to be searched. When the two integers are equal, the search has finished, and a call to QueryResults will return immediately with the resulting hits.

queryidx must be an integer that was previously returned by the SubmitQuery remote procedure call. This remote procedure call can be called any number of times with the same queryidx between the matching SubmitQuery remote procedure call and the finishing QueryResults remote procedure call.

The blocking parameter specifies whether this remote procedure call should return immediately. If blocking is False, the remote procedure call will return immediately with the current status. However, this returned value could be identical to a previous call and provide no new information to the end user. If blocking is True, this remote procedure call will not return until there is new information to return. This will result in less “busy waiting” network traffic constantly pinging the server for an update.

Note

It is possible for both values returned to be 0 even though the search is not complete. There is a very short period of time that the XML RPC service does not know the total number of conformers yet after the query has been submitted. Users can disregard this state and requery the server for a new status.

QueryResults¶

QueryResults(queryidx) -> Binary

Return a XML RPC Binary of search results for the specified queryidx. The contents of the XML RPC Binary, including file format and size, are controlled by the corresponding call to SubmitQuery.

This remote procedure call will block if the search is not completed yet. Use the QueryStatus remote procedure call to determine if the results are ready to return.

Warning

This function can only be called once for a particular queryidx. Once a query’s results are retrieved with this remote procedure call, all record of the search are removed from the server’s memory. The reverse is true as well though, if this function is not called, the query’s results will stay resident in memory until the server is restarted.

SetName¶

SetName(name)

Specify the name of the database this server is serving. Subsequent calls to the GetName remote procedure call will return this name.

SubmitQuery¶

SubmitQuery(querymolstr, nhits, iformat=".oeb", oformat=".oeb", shapeOnly=False) -> int

Submit a query 3D molecule to the server and begin processing immediately. If there is already a search in progress, the query will be submitted to a queue. An integer index is returned to allow tracking the progress of the search through the QueryStatus function, and then to retrieve the results through the QueryResults function. This function will return immediately, unlike the GetBestOverlays remote procedure call.

The shapeOnly argument specifies that color scoring should not be performed and taken into account when scoring and sorting molecules. This defaults to False to be compatible with versions of FastROCS prior to 1.5.0.

The file format of the query in the XML RPC Binary querymolstr is specified by the iformat argument. Valid iformat arguments are any OEChem supported molecular file format that OEIs3DFormat will return True for. This is because FastROCS TK requires a 3D conformation to search against. In addition to supporting 3D conformations from standard OEChem file formats, shape queries from .sq files are also supported as queries. .sq files are most easily constructed from within the vROCS GUI. They are usable from the Shape TK through the OEShapeQueryPublic APIs.

The nhits argument specifies how many hits should be returned by the corresponding QueryResults remote procedure call. These hits will be returned in the order of the best score first. A value of 0 given to nhits specifies that all database molecules should be returned, not a very advisable operation as that can potentially push many megabytes to gigabytes of data over the network.

The file format of the XML RPC Binary to return from QueryResults is specified by the oformat argument. This can be any OEChem supported file format that OEIsWriteable will return True for. However, scores are only stored as SD data, so only the following file formats will return score information:

Furthermore, the molecules returned will be aligned to the query molecule in 3D. So only formats that can represent 3D information will actually contain the resulting alignment.