MaaS Client Session API

Authentication and session management for connecting to the MaaS API is via the MaaSSession object.

class MaaSSession(requests_session=NOTHING, is_authenticated=False, config=NOTHING)
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 MaaSSession, but will use the following method to generate one from a stored profile.

get_session(profile)

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

session = get_session("testing")

Inside a cube in Orion:

maas_user = APISession.get_user_profile().username
token = APISession.config.token
config = MaaSSessionConfig(
         protocol="https",
         domain="maas.eyesopen.com",
         user=maas_user,
         orion_credentials=token
      )
session = MaaSSession(config=config)

MaaS Types API

ExactQuery

class ExactQuery(session=None, id: int = None, user: int = None, database_id: str = None, database_title: str = None, name: str = None, status: str = None, date: str = None, reason: str = None, saved: bool = False, queue: dict = None, search_time: float = 0.0, task_id: str = None, max_hits: int = 100, search_type: str = None, smiles: str = None, num_matches: int = 0, total_matches: int = 0, matches: dict = None)
classmethod add(session, query, database_id, *, name=None, max_hits=250, search_type='ISM')

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

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

Parameters

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

  • query (oechem.OEMolBase|str) – Molecule, SMILES or Local file containing query molecule

  • database_id (str) – ID of MaaS database to search

  • name (str) – Query name, if None will try to use the query molecule title

  • max_hits (int) – Number of hits to return

  • search_type (str) – Graph search type: ISM, ABS, or UNCOLOR

Returns

instance of new query on MaaS server

Return type

ExactQuery

Raises

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

  • ValidationError – If the database_id is not a valid MaaS database.

  • ValidationError – If max_hits < 1

  • ValidationError – If search_type not in [‘ISM’, ‘ABS’, ‘UNCOLOR’]

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

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

classmethod run(session, query, dataset_id, output_file, *, max_hits=250, search_type='ISM', get3d=False, num_confs=1, show_progress=False)

Run query against a database.

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

The basic process is:

  1. query = ExactQuery.add(…)

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

  3. If FINISHED, download results to output_file

Parameters

  • session (MaaSSession) – Session connected to chosen MaaS server

  • query (str) – SMILES or local file containing query molecule

  • dataset_id (int) – ID of MaaS database to search

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

  • max_hits (int) – Number of hits to return

  • search_type (str) – Graph search type: ISM, ABS, or UNCOLOR

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

Returns

ExactQuery

Raises

  • ValidationError – If the query is not a valid SMILES or molecule file.

  • ValidationError – If the dataset_id is not a valid MaaS database.

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

  • ValidationError – If max_hits < 1

  • ValidationError – If search_type not in [‘ISM’, ‘ABS’, ‘UNCOLOR’]

  • 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

GraphsimQuery

class GraphsimQuery(session=None, id: int = None, user: int = None, database_id: str = None, database_title: str = None, name: str = None, status: str = None, date: str = None, reason: str = None, saved: bool = False, queue: dict = None, search_time: float = 0.0, task_id: str = None, num_hits: int = 100, cutoff: float = 0.0, sim_measure: str = 'TANIMOTO', sort_order: str = 'DESCENDING', fpname: str = None, smiles: str = None, progress: float = 0.0, results: dict = None, histogram: dict = None)
classmethod add(session, query, database_id, fpname, *, name=None, num_hits=250, sim_measure='tanimoto')

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

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

Parameters

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

  • query (str|mol) – SMILES, molecule, or local file containing query molecule

  • database_id (str) – ID of MaaS database to search

  • fpname (str) – Name of fp to search, like ‘circular’, ‘tree’, or ‘path’

  • name (str) – Query name, if None will try to use the query molecule title

  • num_hits (int) – Number of hits to return

  • sim_measure (str) – Similarity metric, Tanimoto, Tversky, Dice or Cosine

Returns

instance of new query on MaaS server

Return type

GraphsimQuery

Raises

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

  • ValidationError – If the database_id is not a valid MaaS database.

  • ValidationError – If num_hits < 1

  • ValidationError – If sim_measure not in [‘Tanimoto’, ‘Tversky’, ‘Dice’, ‘Cosine’]

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

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

classmethod run(session, query, dataset_id, fpname, output_file, *, num_hits=250, sim_measure='tanimoto', get3d=False, num_confs=1, show_progress=False)

Run query against a database.

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

The basic process is:

  1. query = GraphsimQuery.add(…)

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

  3. If FINISHED, download results to output_file

Parameters

  • session (MaaSSession) – Session connected to chosen MaaS server

  • query (str|mol) – SMILES, molecule or local file containing query molecule

  • dataset_id (str) – ID of MaaS database to search

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

  • num_hits (int) – Number of hits to return

  • sim_measure (str) – Similarity metric, Tanimoto, Tversky, Dice or Cosine

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

Returns

GraphsimQuery

Raises

  • ValidationError – If the query is not a valid SMILES or molecule file.

  • ValidationError – If the dataset_id is not a valid MaaS database.

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

  • ValidationError – If num_hits < 1

  • ValidationError – If sim_measure not in [‘Tanimoto’, ‘Tversky’, ‘Dice’, ‘Cosine’]

  • 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

MaasDatabase

class MaasDatabase(id: str = None, title: str = None, version: str = None, num_mols: int = 0, has_confs: bool = False, filename: str = None, search: dict = None, urls: list = [], status: str = 'Unknown', progress: int = 0, reason: str = '')
classmethod add(session, json_data)

Add a new MaaS database to search.

Parameters

  • session (MaaSSession) – Session connected to chosen MaaS server

  • json_data (str|dict) – JSON containing the database ID and URLs for the database parts. Can be dictionary or filename.

Returns

Instance of MaasDatabase

Raises

  • ValidationError – If the json_data is not valid JSON.

  • ValidationError – If the server doesn’t have enough memory/disk to load this database.

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

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

SubsearchQuery

class SubsearchQuery(session=None, id: int = None, user: int = None, database_id: str = None, database_title: str = None, name: str = None, status: str = None, date: str = None, reason: str = None, saved: bool = False, queue: dict = None, search_time: float = 0.0, task_id: str = None, num_hits: int = 100, query_type: str = None, smarts: str = None, smiles: str = None, mdlquery: str = None, aliphatic_constraint: bool = True, topology_constraint: bool = False, stereo_constraint: bool = False, isotope_constraint: bool = False, atom_expr: int = 0, bond_expr: int = 0, matches: dict = None, num_matches: int = 0, total_matches: int = 0, efficiency: float = 0.0, progress: float = 0.0, screened: float = 0.0)
classmethod add_mdl(session, query, database_id, *, name=None, num_hits=250, aliphatic_constraint=True, topology_constraint=False, stereo_constraint=False, isotope_constraint=False)

Add a new MDL Subsearch query to the MaaS server queue. This method returns.

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

Parameters

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

  • query (mdl query file | molecule file | OEMolBase | SMILES) – Query

  • database_id (str) – ID of MaaS database to search

  • name (str) – Query name, if None will try to use the query molecule title

  • num_hits (int) – Number of hits to return

  • aliphatic_constraint (bool) –

  • topology_constraint (bool) –

  • stereo_constraint (bool) –

  • isotope_constraint (bool) –

Returns

instance of new query on MaaS server

Return type

SubsearchQuery

Raises

  • ValidationError – If the query is not a valid MDL query file

  • ValidationError – If the database_id is not a valid MaaS database.

  • ValidationError – If num_hits < 1

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

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

classmethod add_smarts(session, query, database_id, *, name=None, num_hits=250)

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

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

Parameters

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

  • query (str|oechem.OEMolBase) – SMARTS, SMILES, molecule file or OEMolBase (will be converted to SMILES)

  • database_id (str) – ID of MaaS database to search

  • name (str) – Query name, if None will try to use the query molecule title

  • num_hits (int) – Number of hits to return

Returns

instance of new query on MaaS server

Return type

SubsearchQuery

Raises

  • ValidationError – If the query is not a valid SMARTS, SMILES or molecule.

  • ValidationError – If the database_id is not a valid MaaS database.

  • ValidationError – If num_hits < 1

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

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

classmethod run_mdl(session, query, dataset_id, output_file, *, name=None, num_hits=250, aliphatic_constraint=True, topology_constraint=False, stereo_constraint=False, isotope_constraint=False, get3d=False, num_confs=1, show_progress=False)

Run query against a database.

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

The basic process is:

  1. query = SubsearchQuery.add_mdl(…)

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

  3. If FINISHED, download results to output_file

Parameters

  • session (MaaSSession) – Session connected to chosen MaaS server

  • query (str) – SMILES or local file containing query molecule

  • dataset_id (str) – ID of MaaS database to search

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

  • num_hits (int) – Number of hits to return

  • aliphatic_constraint (bool) –

  • topology_constraint (bool) –

  • stereo_constraint (bool) –

  • isotope_constraint (bool) –

  • num_confs (int) – Number of conformers to retrieve, for 3D formats.

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

Returns

SubsearchQuery

Raises

  • ValidationError – If the query is not a valid MDL query file or SMARTS

  • ValidationError – If the database_id is not a valid MaaS database.

  • ValidationError – If num_hits < 1

  • 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

classmethod run_smarts(session, query, dataset_id, output_file, *, name=None, num_hits=250, get3d=False, num_confs=1, show_progress=False)

Run query against a database.

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

The basic process is:

  1. query = SubsearchQuery.add_smarts(…)

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

  3. If FINISHED, download results to output_file

Parameters

  • session (MaaSSession) – Session connected to chosen MaaS server

  • query (str) – SMARTS for the query

  • dataset_id (str) – ID of MaaS database to search

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

  • num_hits (int) – Number of hits to return

  • num_confs (int) – Number of conformers to retrieve, for 3D formats.

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

Returns

SubsearchQuery

Raises

  • ValidationError – If the query is not a valid MDL query file or SMARTS

  • ValidationError – If the database_id is not a valid MaaS database.

  • ValidationError – If num_hits < 1

  • 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