OpenTox API 1.2 Model
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 |
|
[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:
- http://www.opentox.org/api/1.1#NominalFeature: classification model
- http://www.opentox.org/api/1.1#NumericFeature: regression model
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 |