OpenTox API 1.2 Dataset

From ToxBank API Wiki
Jump to: navigation, search

Contents

REST operations

Description Method
URI
Parameters Result Status codes
Get a list of available datasets GET
/dataset

[subjectid]
Query parameters (optional, to be defined by service providers)
List of URIs
or RDF for the metadata only
200,404,503
Get a dataset GET
/dataset/{id}
[subjectid] Representation of the dataset in a supported MIME type 200,404,503
Query a dataset GET
/dataset/{id}
[subjectid]
compound_uris[] and/or feature_uris[] to select compounds and features; further query parameters may be defined by service providers
Representation of the query result in a supported MIME type 200,404,503
Get metadata for a dataset GET
/dataset/{id}/metadata
[subjectid] Representation of the dataset metadata in a supported MIME type 200,404,503
Update metadata for a dataset
PUT


/dataset/{id}/metadata


[subjectid]


RDF or application/www-form-urlencoded

Get a list of all compounds in a dataset GET
/dataset/{id}/compounds
[subjectid] List of compound URIs 200,404,503
Get a list of all features in a dataset GET
/dataset/{id}/features
[subjectid] RDF or List of feature URIs (pointing to feature definitions/ontologies) 200,404,503
Create a new dataset POST
/dataset
Dataset representation in a supported MIME type. MIME type to be specified via Content-type header.

  • Content-type:application/www-form-urlencoded dataset_uri , feature_uris[] and compound_uris[] parameters are used to specify subset of a dataset, as in GET operation;
  • File upload via Content-type:multipart/form-data: file parameter
  • File upload metadata: parameters as in opentox.owl
  • [subjectid]

[subjectid]
<a title="Task" class="internal-link" href="AsyncTask#creating-a-task-post">New URI /dataset/{id} or redirect to task URI (for large uploads)</a>
200,202,400,503

Create a new dataset using a reference featureURI list
</tbody>

POST


/dataset

File upload via Content-type:multipart/form-data: file parameter
Reference featureURI list (http://server/path/dataset/{dataset_id}/feature)
Matcher (e.g. name of feature)
<a title="Task" class="internal-link" href="AsyncTask#creating-a-task-post">New URI /dataset/{id} or redirect to task URI (for large uploads)</a>
200,202,400,503
Update a dataset PUT
  • /dataset/{id}

  • Data representation in a supported MIME type;
  • entries for existing compound/feature pairs will be overwritten, entries for new compound/features will be added
  • File upload metadata: Dublin core annotation parameters, as in opentox,owl#Dataset

  • Content-type:application/www-form-urlencoded dataset_uri , feature_uris[] and compound_uris[] parameters are used to specify subset of a dataset, as in GET operation;
  • File upload via Content-type:multipart/form-data: file parameter
  • File upload metadata: Dublin core annotation parameters, as in opentox,owl#Dataset
  • [subjectid]
<a title="Task" class="internal-link" href="AsyncTask#creating-a-task-post">Dataset URI or task URI</a>
200,202,400,404,503
Remove a dataset DELETE
/dataset/{id}
[subjectid] - 200,404,503
Remove a part of the dataset DELETE
/dataset/{id}
compound_uris[] and/or feature_uris[]; further query parameters may be defined to select the data to be deleted

[subjectid]
- 200,404,503</tbody>
  • subjectid (optional) parameter that contains the OpenSSO A&A token needed to access protected services.

Queries

Subsets of a dataset (e.g. all data for a certain feature, all data for a set of compounds)) are accessed through query parameters. This allows us to pass full URIs as parameters and circumvents the problem of no-unique IDs (e.g. for /dataset/{id}/compound/{compound_id} URIs). The query parameters compound_uris[] and feature_uris[] are mandatory, more advanced queries (e.g. similarity searches) may be implemented by individual services.

Examples

Get all features of two compounds</dt>
curl -X GET http://my_dataset_service/dataset_id?compound_uris[]=compound1_uri&compound_uris[]=compound2_uri</dd>
Get a single feature of a single compound</dt>
curl -X GET http://my_dataset_service/dataset_id?compound_uris[]=compound_uri&feature_uris[]=feature_uri</dd>
Remove a compound from a dataset</dt>
curl -X DELETE http://my_dataset_service/{dataset_id}?compound_uris[]=<compound_uris></dd>
Upload an sdf to ambit server </dt>
curl -X POST -H 'Content-Type:chemical/x-mdl-sdfile' --data-binary @filename.sdf http://ambit.uni-plovdiv.bg:8080/ambit2/dataset</dd>
Get compound URIs of a dataset </dt>
curl -X GET -H 'Accept:text/uri-list' http://ambit.uni-plovdiv.bg:8080/ambit2/dataset/{dataset_id}</dd>
Upload an sdf that contains features of an already existing dataset (if a feature name in filename.sdf matches a feature name from associated_features the corresponding URI is assigned)</dt>
curl -X POST -H 'Content-Type:chemical/x-mdl-sdfile' --data-binary @filename.sdf -d 'associated_features=http://ambit.uni-plovdiv.bg:8080/ambit2/dataset/{datsaet_id}/feature' -d 'matcher=Name' http://ambit.uni-plovdiv.bg:8080/ambit2/dataset</dd>

Together with a little bit of RDF processing you can use queries also for set operations (e.g. subsets, split, merge, intersection).

PS Take care to URI encode parameters that are sent via GET.

Dataset representation

RDF specification

Metadata

Features

RDF dataset representation

The feature URI points to a Feature object, which allows retrieval of the Feature object as RDF and provides information about the name, units, source and the type of the feature. The feature type is denoted by a mandatory link to an ontology via owl:sameAs or directly subclassing a class from an ontology.

This allows Feature URI to point directly to an existing (fixed) ontology, or to a web service, providing access to dynamically created Feature objects.

Conformers

Conformer URIs (see Compound API) can be used instead of compound URIs. The Resolving the parent structure should be done via the compound webservice.

Examples

Multi Cell Call prediction from J48 (N3 notation):

example:DatasetPredicted
a       ot:Dataset ;
dc:identifier "http://myservice/dataset/{datasetid}"^^xsd:string ;
dc:title "Multi Cell Call prediction from J48"^^xsd:string ;
ot:dataEntry
[ a       ot:DataEntry ;
ot:compound example:benzene ;
ot:values
[ a       ot:FeatureValue ;
ot:feature example:MultiCellCallPredicted ;
ot:value "true"^^xsd:boolean
];
ot:values
[ a       ot:FeatureValue ;
ot:feature example:MultiCellCall ;
ot:value "true"^^xsd:boolean
] ;
] .
example:benzene
a       ot:Compound ;
dc:identifier "http://myservice/compound/{compoundid1}"^^xsd:string .
example:MultiCellCallPredicted
a       ot:Feature ;
dc:identifier "http://myservice/feature/{featureid3}"^^xsd:string ;
dc:title "MultiCellCall"^^xsd:string ;
ot:hasSource example:WekaJ48 .

Single compound with a single substructure:

<https://ambit.uni-plovdiv.bg:8443/ambit2/dataset/2407>
a       ot:Dataset ;
ot:dataEntry
[ a       ot:DataEntry ;
ot:compound <https://ambit.uni-plovdiv.bg:8443/ambit2/compound/17285> ;
ot:values
[ a       ot:FeatureValue ;
ot:feature <https://ambit.uni-plovdiv.bg:8443/ambit2/feature/171898> ;
ot:value "true"^^xsd:boolean
]
] .
<https://ambit.uni-plovdiv.bg:8443/ambit2/compound/17285>
a       ot:Compound .
<https://ambit.uni-plovdiv.bg:8443/ambit2/feature/171898>
a       ot:Substructure ;
dc:title "FCF" ;
ot:smarts "FCF" ;
ot:hasSource <https://ambit.uni-plovdiv.bg:8443/ambit2/model/26469> ;
ot:Substructure
a       owl:Class ;
rdfs:subClassOf ot:Feature .

Retrieving metadata:

curl -H "Accept:text/n3" <a href="http://apps.ideaconsult.net:8080/ambit2/dataset/1/metadata" target="_blank">http://apps.ideaconsult.net:8080/ambit2/dataset/112/metadata</a>

<<a href="http://apps.ideaconsult.net:8080/ambit2/dataset/112" target="_blank">http://apps.ideaconsult.net:8080/ambit2/dataset/112</a>>       a       ot:Dataset ;       dc:title "ToxCast_ToxRefDB_20091214.txt" ;

      dcterms:license <<a href="http://www.opendatacommons.org/licenses/pddl" target="_blank">http://www.opendatacommons.org/licenses/pddl></a> .
 

Adding metadata to an existing dataset (using RDF)

curl -X PUT -H "Content-type:application/rdf+xml" -d @mymetadata.rdf http://host/dataset/{id}/metadata 

Adding metadata to an existing dataset (using web form)

curl -X PUT -d "license=<a href="http://www.opendatacommons.org/licenses/pddl" target="_blank">http://www.opendatacommons.org/licenses/pddl</a>" -d "title=blabla" <a href="http://host/dataset/%7Bid%7D/metadata" target="_blank">http://host/dataset/{id}/metadata</a>

Specifying the metadata on upload (mimics sending a multipart web form)

curl -X POST -F "file=@alkanes.csv" 

-F "license=<a href="http://www.opendatacommons.org/licenses/pddl/" target="_blank">http://www.opendatacommons.org/licenses/pddl/</a>"

-F "title=Alkanes" <a href="http://host/dataset/" target="_blank">http://host/dataset/</a>

Supported MIME types

Mandatory

  • application/rdf+xml (default)
  • application/www-form-urlencoded
  • multipart/form-data
  • <a name="idx-multipartform-data-1"></a>

Optional

  • other RDF serialization formats
  • application/xml
  • text/xml
  • text/x-yaml
  • text/x-json
  • application/json
  • text/csv
  • text/arff
  • text/html
  • chemical/x-mdl-sdfile
  • ...
  • multipart/form-data for file uploads

HTTP status codes

Interpretation Nr Name
Success 200 OK
Asynchronous task started
202 Accepted
Dataset not found 404 Not Found
Incorrect MIME type 400 Bad request
Service not available 503 Service unavailable</tbody>
Personal tools