FastROCS Client Session API

Authentication and session management for connecting to the FastROCS API is via the FastROCSSession object.

class FastROCSSession(requests_session=NOTHING, is_authenticated=False, config=NOTHING)

A HTTP Session authenticated for accessing the FastROCS REST API.

Use get_session() to create a new instance with a given set of credentials.

clear_token(username, password)
property config
create_resource(resource_type, params=None, files=None)

A method to create Orion instances of the Types classes, the params and files are the inputs expected by the RESTful API.

Parameters

  • resource_type (class) – A class from types

  • params (dict) – Parameters to create the resource with

  • files (dict) – Files to create resource with

Returns

An instance of the resource type

Return type

resource

Raises

  • InvalidCredentials – If session has invalid credentials

  • AuthorizationRequired – If session wasn’t authorized to make the request

delete_resource(resource)

Deletes the resource from FastROCS

:param BaseType resource_id :return: Whether it succeeded or not :rtype: boolean :raises InvalidCredentials: If session has invalid credentials :raises AuthorizationRequired: If session wasn’t authorized to make the request

get_page(url, resource_type, filters=None)
get_resource(resource_type, resource_id, timeout=None)

When you want to instantiate an Orion resource that already exists you would use get_resource to construct that instance, specifying the type and identifier of the resource.

Parameters

  • resource_type (class) – A class from types

  • resource_id (integer) – Identifier of the resource

  • timeout (integer) – Time to spend getting a resource, best effort timeout

Returns

An instance of the resource type

Return type

resource_type

Raises

  • InvalidCredentials – If session has invalid credentials

  • AuthorizationRequired – If session wasn’t authorized to make the request

is_authenticated()

Notifies the user of whether the Session is authenticated

Return type

boolean

list_resources(resource_type, filters=None)

Takes a resource class and provides you with an iterator of the resource type.

Parameters

  • resource_type (class) – A class from types

  • filters (dict) – Query parameters to filter with

Returns

Iterator of resource_types

Return type

iter<resource_type>

Raises

  • InvalidCredentials – If session has invalid credentials

  • AuthorizationRequired – If session wasn’t authorized to make the request

refresh_resource(resource)

Takes a resource and refreshes its attributes

Parameters

resource (class) – An instance of an oeclient_utils.BaseType

Raises

  • InvalidCredentials – If session has invalid credentials

  • AuthorizationRequired – If session wasn’t authorized to make the request

requests_session
reset_token(username, password)
retrieve_token(username, password)
update_resource(resource, params, files=None)

Takes a resource, updates it, and refreshes its attributes

Parameters

  • resource (class) – An instance of an oeclient_utils.BaseType

  • params (dict) – Parameters to update on the resource

Raises

  • InvalidCredentials – If session has invalid credentials

  • AuthorizationRequired – If session wasn’t authorized to make the request

url(resource_uri, query_params=None, api_prefix='')

Most of the time, you won’t construct a FastROCSSession, but will use the following method to generate one from a stored profile.

get_session(profile='default')

Get a new FastROCSSession, configured with the given profile.

If no credentials are found, this will prompt the user for their password.

Parameters

profile (string) – Name of profile to use.

Return type

OEFastROCSSession

You can setup a FastROCSSession with the config by doing the following

session = get_session("testing")

Inside a cube in Orion:

from oeclient_utils import OESessionConfig
config = OESessionConfig(
         protocol="https",
         domain="orion.eyesopen.com",
         orion_credentials=os.getenv("ORION_TOKEN"),
         api_prefix="api/v1"
      )
session = FastROCSSession(config=config)

FastROCS Types API

Dataset

class Dataset(id: int = None, session=None, name: str = '', user: int = None, color_force_field: str = 'ImplicitMillsDean', shape_only: bool = False, system: bool = False, public: bool = False, status: str = '', num_mols: int = None, num_confs: int = None)

A Dataset represents a collection of 3D multi-conformer molecules for FastROCS to search.

For example, to search a corporate or vendor collection, the input molecules should be processed with Omega to generate 3D conformers and the run through ShapeDatabasePrep.py to prepare them for adding to the FastROCS server.

classmethod add(session, dataset_specifier, *, name=None, system=False, public=False, color_force_field='ImplicitMillsDean', shape_only=False)

Add a new dataset for FastROCS to search.

The file to upload should be an OEB (not .oeb.gz) file created by ShapeDatabasePrep.py (included in the OpenEye Python toolkit distribution.)

Parameters

  • session (FastROCSSession) – Session connected to chosen FastROCS server

  • dataset_specifier (str) – Local filename or URL that contains the data

  • name (str) – Display name for this dataset

  • system (bool) – Mark this dataset as ‘system’

  • public (bool) – Mark this dataset as ‘public’, searchable by everyone.

  • color_force_field (str) – Color force field to use to prep the dataset

  • shape_only (bool) – If set, color atoms won’t be added and only shape scoring will work

Returns

Instance of a new dataset in FastROCS

Return type

Dataset

Raises

  • ValidationError – If the dataset_specifier is not a local file or URL or if an int is used as the dataset name.

  • InvalidCredentials – If the current profile/session has invalid data

  • BadResponse – If an error occurs add the dataset

classmethod serve(session, dataset_specifier, host, *, name=None, system=False, public=False, color_force_field='ImplicitMillsDean', shape_only=False, port=8887, timeout=60)

Add a new dataset for FastROCS to search, using a temporary HTTP server running via this command.

This will not work if the route from the FastROCS server back to this machine is blocked by an incoming firewall.

The file to upload should be an OEB (not .oeb.gz) file created by ShapeDatabasePrep.py (included in the OpenEye Python toolkit distribution.)

Parameters

  • session (FastROCSSession) – Session connected to chosen FastROCS server

  • host (str) – Hostname or IP for local server.

  • dataset_specifier (str) – Local filename or URL that contains the data

  • name (str) – Display name for this dataset

  • system (bool) – Mark this dataset as ‘system’

  • public (bool) – Mark this dataset as ‘public’, searchable by everyone.

  • color_force_field (str) – Color force field to use to prep the dataset

  • shape_only (bool) – If set, color atoms won’t be added and only shape scoring will work

  • port (str) – Network port for server

  • timeout (int) – If FastROCS server does not contact the local server within this timeout, the server will exit.

Returns

Instance of a new dataset in FastROCS

Return type

Dataset

Raises

  • ValidationError – If the dataset_specifier is not a local file or URL or if an int is used as the dataset name.

  • BadResponse – If an error occurs add the dataset

  • InvalidCredentials – If the current profile/session has invalid data

update(*, dataset_specifier=None, name=None, system=None, public=None, color_force_field=None, shape_only=None)

Update an existing FastROCS dataset.

The file to upload should be an OEB (not .oeb.gz) file created by ShapeDatabasePrep.py (included in the OpenEye Python toolkit distribution.)

Parameters

  • dataset_specifier (str) – Local filename or URL that contains the data

  • name (str) – Display name for this dataset

  • system (bool) – Mark this dataset as ‘system’

  • public (bool) – Mark this dataset as ‘public’, searchable by everyone.

  • color_force_field (str) – Color force field to use to prep the dataset

  • shape_only (bool) – If set, color atoms won’t be added and only shape scoring will work

Raises

  • ValidationError – If the dataset_specifier is not a local file or URL or if an int is used as the dataset name.

  • BadResponse – If an error occurs trying to update the dataset

  • InvalidCredentials – If the current profile/session has invalid data

Examples

>>> import fastrocs_client as frcli
>>> session = frcli.get_session(profile='testing')
>>> dataset = session.get_resource(Dataset, 12)
>>> dataset.update(name="new name", public=True, system=True)
>>> session.refresh_resource(dataset)
>>> print(dataset.display(pretty=True))
{
    "color_force_field": "ImplicitMillsDean",
    "id": 12,
    "name": "new name",
    "public": true,
    "shape_only": false,
    "status": "LOADED",
    "system": true,
    "user": "2",
    "num_mols": 128,
    "num_confs": 7951
}

Query

class Query(id: int = None, session=None, name: str = '', user: int = None, status: str = 'UNKNOWN', progress: dict = {}, queue: dict = {}, queue_position: int = 0, dataset_id: int = 0, num_hits: int = 0, num_queries: int = 0, output_format: str = '', results: str = '', shape_only: bool = False, sim_type: str = '', tversky_alpha: float = 0.95)

A Query represents a single 3D molecule query for FastROCS.

0D and 2D molecules can be used as a query. They will be converted to 3D before the search

classmethod add(session, query_file, dataset_id, *, num_hits=250, sim_type='tanimoto', tversky_alpha=0.95, shape_only=False)

Add a new query to the FastROCS server queue. This method returns.

To get subsequent status of the query, use Query.info()

Parameters

  • session (FastROCSSession) – Session connected to chosen FastROCS server

  • query_file (str) – Local file containing query molecule

  • dataset_id (int) – ID of FastROCS dataset to search

  • num_hits (int) – Number of hits to return

  • sim_type (str) – Similarity metric, tanimoto or tversky

  • tversky_alpha (float) – Alpha coefficient for Tversky score

  • shape_only (bool) – Skip color scoring

Returns

instance of new query on FastROCS server

Return type

Query

Raises

  • ValidationError – If the query_file is not a valid molecule file.

  • ValidationError – If the dataset_id is not a valid FastROCS dataset.

  • ValidationError – If the output_format is not a valid molecule file type.

  • ValidationError – If num_hits < 1

  • ValidationError – If sim_type not in [‘tanimoto’, ‘tversky’]

  • InvalidCredentials – If the current profile/session has invalid data

  • BadResponse – If an error occurs trying to add the query

download_results(output_file)

Download the results of this query to a local molecule file

Parameters

output_file (str) – Molecule filename

Raises

  • ValidationError – If query.status is not FINISHED

  • IOError – If unable to open output_file for writing

  • InvalidCredentials – If the current profile/session has invalid data

  • AuthorizationRequired – If authentication with the current session fails.

  • NotFoundResponse – If the current query no longer exists on the server

  • BadResponse – For other server failures

download_to_file(filename)

Download the current query molecule to a local file.

Parameters

filename (str) – Molecule file for output.

Raises

  • IOError – If unable to open filename for writing

  • InvalidCredentials – If the current profile/session has invalid data

  • AuthorizationRequired – If authentication with the current session fails.

  • NotFoundResponse – If the current query no longer exists on the server

  • BadResponse – For other server failures

classmethod run(session, query_file, dataset_id, output_file, *, num_hits=250, sim_type='tanimoto', tversky_alpha=0.95, shape_only=False, show_progress=False)

Run query against a dataset.

Unlike ‘add’, ‘run’ wait for the query to complete and downloads the results.

The basic process is:

  1. query = Query.add(…)

  2. Poll while query.status is not FINISHED or FAILED

  3. If FINISHED, download results to output_file

Parameters

  • session (FastROCSSession) – Session connected to chosen FastROCS server

  • query_file (str) – Local file containing query molecule

  • dataset_id (int) – ID of FastROCS dataset to search

  • output_file (str) – Local file to store the output in

  • num_hits (int) – Number of hits to return

  • sim_type (str) – Similarity metric, tanimoto or tversky

  • tversky_alpha (float) – Alpha coefficient for Tversky score

  • shape_only (bool) – Skip color scoring

  • show_progress (bool) – Don’t show progress (default)

Returns

Query

Raises

  • ValidationError – If the query_file is not a valid molecule file.

  • ValidationError – If the dataset_id is not a valid FastROCS dataset.

  • ValidationError – If the output_file is not a valid molecule file type.

  • ValidationError – If num_hits < 1

  • ValidationError – If sim_type not in [‘tanimoto’, ‘tversky’]

  • IOError – If unable to open output_file for writing

  • InvalidCredentials – If the current profile/session has invalid data

  • BadResponse – If an error occurs trying to run the query