OpenTox API 1.2 Model

From ToxBank API Wiki
Jump to: navigation, search

Contents

Model

Component description

Provides different representations for QSAR/toxicology models. Models are the output/result of learning algorithms and cannot be modified. To make use of a model for prediction, it is necessary to have a dataset with compatible descriptors/features. If the dataset_service parameter is stated, a new dataset will be created if on the other hand the result_dataset parameter is stated, the stated dataset will be updated with the predicted feature values. In other words, a new "column" for the predictions is added to the input dataset. If none of the two parameters is given, a default dataset service is used and a new dataset is created.

REST operations

Description
Method
URI
Parameters
Result
Status codes
Get a list of all available models GET /model [subjectid]
[?query=URI-of-the-owl:sameAs-entry]
List of model URIs or RDF representation
If query specified, returns all models, for which
owl:sameAs is given by the query
200,404,503
Get the representation of a model GET /model/{id} [subjectid] Representation of the model in a supported MIME type
200,404,503
Delete a model DELETE /model/{id} [subjectid] - 200,404,503
Apply a model to predict a dataset
POST /model/{id} dataset_uri=dataseturi
result_dataset
=result_dataseturi
dataset_service
=datasetserviceuri
[subjectid]

URI of created prediction dataset (predictions are features), [../AsyncTask#creating-a-task-post task URI for time consuming computations]

200,202,400,404,500,503
Apply a model to predict a compound
POST /model/{id} compound_uri=compounduri
[subjectid]

Prediction in a supported MIME type, [../AsyncTask#creating-a-task-post task URI for time consuming computations]

200,202,400,404,500,503

Notes

  • dataset_uri=datasetURI is mandatory parameter
  • result_dataset=result_datasetURI, pointing to a resulting dataset. This dataset will be updated with the predicted feature values.
  • dataset_service=datasetserviceURI, pointing to a dataset service. A new dataset with predicted feature values will be created.
  • either' 'result_dataset or dataset_service parameter might be present.
  • If neither of result_dataset or dataset_service parameter is specified, the model service uses a pre-configured dataset service.
  • subjectid (optional) parameter that contains the OpenSSO A&A token needed to access protected services. [If no token is given, anonymous user is assumed?]

Model variables

REST operations

Description Method URI Parameters Result Status codes
List of independent variables GET /model/{id}/independent [subjectid] URI-list/RDF of features used as independent variables 200,404,503
List of dependent variables GET /model/{id}/dependent [s'ubjectid]' URI-list/RDF of features used as dependent variables 200,404,503
List of predicted features GET
/model/{id}/predicted
[subjectid]
URI-list/RDF of features, where predictions are stored 200,404,503

This facilitates extracting specified feature values per compound , e.g. /compound/{cid}?feature=/model/{id}/independent&?feature=/model/{id}/predicted will return representation of the compound with values for independent variables as well as predicted feature values

Classification vs Regression Models

The feature type of the predicted feature(s) is used to distinguish between regression and classification models:

Supermodels

A superservice for creating predictions from chemical structures alone, that may use other algorithms and models (e.g. descriptor calculation, applying multiple models for consensus predictions). In contrast to simple models it is not necessary to provide a dataset with precalculated features, as feature calculations are launched by the superservice. Supermodels are created by superalgorithms, and use the same REST API as OpenTox models

Examples

Get a list of all available model URIs at TUM (-X GET is default and could be ignored here):

curl -X GET -H 'Accept:text/uri-list' http://opentox.informatik.tu-muenchen.de:8080/OpenTox-dev/model

Get the RDF XML representation of model TUMOpenToxModel_kNN_9 (RDF XML is the default representation):

curl -X GET http://opentox.informatik.tu-muenchen.de:8080/OpenTox-dev/model/TUMOpenToxModel_kNN_9

Make a prediction for ambit dataset 1038 with model TUMOpenToxModel_kNN_95:

curl -X POST -d 'dataset_uri=http://apps.ideaconsult.net:8080/ambit2/dataset/1038' \
-d 'dataset_service=http://apps.ideaconsult.net:8080/ambit2/dataset/' \
http://opentox.informatik.tu-muenchen.de:8080/OpenTox-dev/model/TUMOpenToxModel_kNN_95

Model representation

RDF representation defined in opentox.owlexamples

The RDF representation contains metadata (e.g. algorithm, training dataset, parameters, dependent/independent variables) about the model. You should use PMML (if supported) to retrieve a portable version of the model.

Metadata

  • training algorithm
  • training dataset
  • training parameters
  • independent variables
  • dependent variables

Supported MIME types

Mandatory

  • application/rdf xml (default)

Optional

  • application/xml (PMML)
  • text/xml (PMML)
  • text/x-yaml
  • text/x-json
  • application/json
  • ...

HTTP status codes

Interpretation Nr Name
Success 200 OK
Asynchronous task accepted
202 Accepted
Dataset_id is wrong 400 Bad Request
Model for specific id not found 404 Not Found
Prediction error 500 Internal server error
Service not available 503 Service unavailable
Personal tools