api package

Submodules

api.config module

Configuration file. All settings are stored in Config class which gets instantiated in __init__.py.

class api.config.Config

Bases: object

Class to configure important filepaths and settings.

KEGG_DB_NAME = 'kegg'

Name of KEGG database with models collection

MONGO_URI = 'mongodb://localhost/'

URI to MINE MongoDB

NEG_ADDUCT_PATH = '/home/docs/checkouts/readthedocs.org/user_builds/mine-api/envs/latest/lib/python3.7/site-packages/minedatabase/data/adducts/Negative Adducts full.txt'

Path to “Negative Adducts full.txt”

POS_ADDUCT_PATH = '/home/docs/checkouts/readthedocs.org/user_builds/mine-api/envs/latest/lib/python3.7/site-packages/minedatabase/data/adducts/Positive Adducts full.txt'

Path to “Positive Adducts full.txt”

TEST_DATA_DIR = '/home/docs/checkouts/readthedocs.org/user_builds/mine-api/checkouts/latest/api/../tests/data'

Path to directory with test data

api.database module

Used just to create the mongo connection. See Stack Overflow question 33166612 for details on why this needs to be its own file.

api.exceptions module

Module for all Exception subclassses.

exception api.exceptions.InvalidUsage(message, status_code=400, payload=None)

Bases: Exception

Custom Exception handler for the API. See source at http://flask.pocoo.org/docs/1.0/patterns/apierrors/ for more info.

message

Human readable string describing the exception.

Type

str

status_code

HTTP status code - defaults to 400 (Bad Request).

Type

int, optional

payload

Extra information on the error.

Type

dict, optional

to_dict()

Convert payload to dict with message.

api.routes module

Here, routes are defined for all possible API requests. Note that nearly all actual logic is imported from the minedatabase package.

api.routes.database_query_api(db_name, mongo_query)

Perform a direct query built with Mongo syntax.

Parameters

  • db_name (str) – Name of Mongo database to query against.

  • mongo_query (str) – A valid Mongo query (e.g. …/q={“ID”: “cpd00001”}).

Returns

JSON Documents matching provided Mongo query.

Return type

flask.Response

api.routes.get_adduct_names_api(adduct_type='all')

Get names of all adducts for the specified adduct type.

Parameters

adduct_type (str,optional) – Options are ‘positive’, ‘negative’, or ‘all’. Defaults to ‘all’.

Returns

JSON array of adduct names. If adduct_type == ‘all’, then this is an array of two arrays, with the first element being positive adducts and the second adduct being negative adducts.

Return type

flask.Response

api.routes.get_comps_api(db_name)

Get compounds for specified ids in database.

Parameters

  • db_name (str) – Name of Mongo database to query against.

  • id_list (list) – List of compound ids. Attach as “dict” to POST request. For example, requests.post(<this_uri>, data=”{‘id_list’: [‘id1’, ‘id2’, ‘id3’]}”). IDs can be either MINE IDs or Mongo IDs (_id).

Returns

List of compound JSON documents.

Return type

flask.Response

api.routes.get_ids_api(db_name, collection_name, query=None)

Get Mongo IDs for a subset of a given database collection.

Parameters

  • db_name (str) – Name of Mongo database to query against.

  • collection_name (str) – Name of Mongo collection within database to query against.

  • query (str,optional) – Specifies subset of collection to retrieve ids for. Formatted as a python dict as you would have in argument to db.collection.find(). Defaults to None.

Returns

List of ids matching query in JSON format.

Return type

flask.Response

api.routes.get_op_w_rxns_api(db_name, op_id)

Get operator with all its associated reactions in selected database.

Parameters

  • db_name (str) – Name of Mongo database to query against.

  • op_id (str) – Either operator id (e.g. 1.1.-1.h) or Mongo ID (_id) for operator.

Returns

Operator JSON document (including associated reactions).

Return type

flask.Response

api.routes.get_ops_api(db_name)

Get operators for specified ids in database.

Parameters

  • db_name (str) – Name of Mongo database to query against.

  • id_list (list,optional) – List of operator ids. Attach as “dict” to POST request. For example, requests.post(<this_uri>, data=”{‘id_list’: [‘id1’, ‘id2’, ‘id3’]}”). IDs can be either operator ids (e.g. 1.1.-1.h) or Mongo IDs (_id). If not provided, all operators are returned (id_list=None).

Returns

List of operator JSON documents.

Return type

flask.Response

api.routes.get_rxns_api(db_name)

Get reactions for specified ids in database.

Parameters

  • db_name (str) – Name of Mongo database to query against.

  • id_list (list) – List of reaction ids. Attach as “dict” to POST request. For example, requests.post(<this_uri>, data=”{‘id_list’: [‘id1’, ‘id2’, ‘id3’]}”). IDs can be either MINE IDs or Mongo IDs (_id).

Returns

List of reaction JSON documents.

Return type

flask.Response

api.routes.handle_invalid_usage(error)

Makes it so user can receive an informative error message rather than a default internal server error.

api.routes.model_search_api(query)

Perform a model search and return results.

Parameters

query (str) – KEGG Org Code or Org Name of model(s) to search for (e.g. ‘hsa’ or ‘yeast’). Can provide multiple search terms by separating each term with a space. TODO: change from space delimiter to something else

Returns

JSON Document with KEGG org codes matching query.

Return type

flask.Response

api.routes.ms2_search_api(db_name)

Search for commpound-adducts matching precursor mass(es).

Attach all arguments besides db_name as form data in POST request.

Parameters

  • db_name (str) – Name of Mongo database to query against.

  • tolerance (float) – Specifies tolerance for m/z, in mDa by default. Can specify in ppm if ppm is set to True.

  • charge (bool) – Positive or negative mode. (True for positive, False for negative).

  • energy_level (int) – Fragmentation energy level to use. May be 10, 20, or 40.

  • scoring_function (str) – Scoring function to use. Can be either ‘jaccard’ or ‘dot product’.

  • text (str) – Text as in metabolomics datafile for specific peak.

  • text_type (str,optional) – Type of metabolomics datafile (mgf, mzXML, and msp are supported). If None, assumes m/z values are separated by newlines. Default is None.

  • adducts (list,optional) – List of adducts to use. If not specified, uses all adducts. (adducts=None)

  • models (list,optional) – List of model _ids. If supplied, score compounds higher if present in metabolic model. Defaults to None.

  • ppm (bool,optional) – Specifies whether tolerance is in ppm. Defaults to False.

  • logp (tuple,optional) – Length 2 tuple specifying min and max logp to filter compounds (e.g. (-1, 2)). Defaults to None.

  • halogens (bool,optional) – Specifies whether to filter out compounds containing F, Cl, or Br. Filtered out if set to True. Defaults to False.

Returns

JSON array of compounds that match m/z within defined tolerance and after passing other defined filters (such as logP).

Return type

flask.Response

api.routes.ms_adduct_search_api(db_name)

Search for commpound-adducts matching precursor mass(es).

Attach all arguments besides db_name as JSON data in POST request.

Parameters

  • db_name (str) – Name of Mongo database to query against.

  • tolerance (float) – Specifies tolerance for m/z, in mDa by default. Can specify in ppm if ppm is set to True.

  • charge (bool) – Positive or negative mode. (True for positive, False for negative).

  • text (str) – Text as in metabolomics datafile for specific peak.

  • text_type (str,optional) – Type of metabolomics datafile (mgf, mzXML, and msp are supported). If None, assumes m/z values are separated by newlines. Default is None.

  • adducts (list,optional) – List of adducts to use. If not specified, uses all adducts (adducts=None).

  • models (list,optional) – List of model _ids. If supplied, score compounds higher if present in metabolic model. Defaults to None.

  • ppm (bool,optional) – Specifies whether tolerance is in ppm. Defaults to False.

  • logp (tuple,optional) – Length 2 tuple specifying min and max logp to filter compounds (e.g. (-1, 2)). Defaults to None.

  • halogen (bool,optional) – Specifies whether to filter out compounds containing F, Cl, or Br. Filtered out if set to True. Defaults to False.

  • verbose (bool,optional) – If True, verbose output. Defaults to False.

Returns

JSON array of compounds that match m/z within defined tolerance and after passing other defined filters (such as logP).

Return type

flask.Response

api.routes.quick_search_api(db_name, query)

Perform a quick search and return results.

Parameters

  • db_name (str) – Name of Mongo database to query against.

  • query (str) – A MINE id, KEGG code, ModelSEED id, Inchikey, or Name.

Returns

JSON Documents matching query.

Return type

flask.Response

api.routes.similarity_search_api(db_name, smiles=None, min_tc=0.7, limit=-1)

Perform a similarity search for a SMILES string and return results.

Either a SMILES string or mol object string is required. SMILES is the recommended format. If GET request, uses smiles. If POST, uses mol.

Parameters

  • db_name (str) – Name of Mongo database to query against.

  • smiles (str) – SMILES string describing molecular structure of query molecule. Either smiles or mol arg is required (smiles arg recommended over mol arg).

  • mol (str,optional) – mol object in str format (should contain a lot of strange chars like “%20” and end with “END”). Used only for the MINE website backend because MarvinJS on the front end only generates mol objects from input structures, and cannot convert it to SMILES. Captured from form data. Defaults to None.

  • min_tc (float,optional) – Minimum Tanimoto Coefficient required for similarity match. Defaults to 0.7.

  • limit (int,optional) – Maximum number of results (compounds) to return. By default, returns all results (limit=-1).

  • model (str,optional) – KEGG organism code (e.g. ‘hsa’). Adds annotations to each compound based on whether it is in or could be derived from the KEGG compounds in this organism (provided in the ‘Likelihood_score’ field of each compound document). Defaults to None.

Returns

JSON Document of similar compounds.

Return type

flask.Response

api.routes.spectra_download_api(db_name, mongo_query=None)

Download one or more spectra for compounds matching a given query.

Parameters

  • db_name (str) – Name of DB containing compound documents to search.

  • mongo_query (str,optional) – A valid Mongo query as a literal string. If None, all compound spectra are returned. Defaults to None.

  • parent_filter (str,optional) – If set to a metabolic model’s Mongo _id, only get spectra for compounds in or derived from that metabolic model. Defaults to None.

  • putative (bool,optional) – If False, only find known compounds (i.e. in Generation 0). Otherwise, finds both known and predicted compounds. Defaults to True.

Returns

Text of all matching spectra, including headers and peak lists.

Return type

flask.Response

api.routes.structure_search_api(db_name, smiles=None, stereo=True)

Perform an exact structure search and return results.

If GET request, uses smiles. If POST, uses mol.

Parameters

  • db_name (str) – Name of Mongo database to query against.

  • smiles (str) – SMILES string describing molecular structure of query molecule.

  • mol (str,optional) – mol object in str format (should contain a lot of strange chars like “%20” and end with “END”). Used only for the MINE website backend because MarvinJS on the front end only generates mol objects from input structures, and cannot convert it to SMILES. Captured from form data. Defaults to None.

  • stereo (bool,optional) – If true, uses sterochemistry in finding exact match. Defaults to True.

  • model (str,optional) – KEGG organism code (e.g. ‘hsa’). Adds annotations to each compound based on whether it is in or could be derived from the KEGG compounds in this organism (provided in the ‘Likelihood_score’ field of each compound document). Defaults to None.

Returns

JSON Document of match (empty if no match).

Return type

flask.Response

api.routes.substructure_search_api(db_name, smiles=None, limit=-1)

Perform a substructure search and return results.

If GET request, uses smiles. If POST, uses mol.

Parameters

  • db_name (str) – Name of Mongo database to query against.

  • smiles (str) – SMILES string describing molecular substructure to search for.

  • mol (str,optional) – mol object in str format (may contain a lot of whitespace hex-chars like “%20” and end with “END”). Used only for the MINE website backend because MarvinJS on the front end only generates mol objects from input structures, and cannot convert it to SMILES. Captured from form data. Defaults to None.

  • limit (int) – Maximum number of results (compounds) to return. By default, returns all results (limit=-1).

Returns

JSON Documents of compounds containing given substructure.

Return type

flask.Response

api.run module

This is the main file that runs the app. FLASK_APP env variable should be set to a path to this file (e.g. on Windows “set FLASK_APP=api/run.py”).

api.run.create_app(instance_config=<class 'api.config.Config'>)

Create a Flask instance of MINE-Server with a specified configuration.

Parameters

instance_config (Config (default: app.config.Config)) – Specifies configuration for this instance. Useful to change when running unit tests (see app.config_unittest.ConfigUnitTest).

Notes

This method is automatically called by Flask upon startup.

Module contents