The following figure gives an overview of all OpenTox components and their interconnections. At the OpenTox web site one can find more information about these components.
An algorithm (source code) (javadoc) is characterized by a set of Ontological Classes that classify it according to the OpenTox Algorithms Ontology. As algorithms can be used for a wide variety of purposes (e.g. model building, feature calculation, feature selection, similarity calculation, substructure matching), required and optional input parameters and algorithm results (e.g. model or dataset URIs, literal values) have to be specified in the algorithm representation together with a definition of the algorithm. A set of parameters along with their scope (optional/mandatory) and default values are also available for every algorithm. Already JAQPOT3 implements the OPTIONS method providing guidelines to the client (templated machine-readable documentation) on its consumption.
A Conformer is an identifier of a unique chemical substance up to its 3D characteristics. The class Conformer does not play yet an important role in ToxOtis. It is an extension of Compound that will be used in special cases as for example to access 3D-sensitive descriptor calculation services or in general services and resources that take inro account the 3D conformation of the chemical substance they cope with.
A Compound is a wrapper for a set of conformers and also (when used to identify a chemical substance) acts as a proxy for a conformer. Various methods have been implemented to provide access to available properties about a compound.
A Feature is an object,representing any kind of property, assigned to a Compound. The feature types are determined via their links to ontologies (Feature ontologies, Decsriptor ontologies, Endpoints ontologies). OpenTox has established an ontology for biological/toxicological and chemical features that is available online.
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 POSTed via HTTP, 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.
A Model is characterized by its parameters, the training dataset (the dataset used to produce the model), a set of independent variables and its predicted and dependent variables.
Metadata of a Model:
In OpenTox various computational procedures such as model training, data filtering or even data upload operations can be time consuming. While such operations take place, the socket that binds the client to the server has to be released. Such a connection is prone to network errors and additionally it would be quite burdensome for the server to keep lots of connections open until each operation completes. In order to tackle this problem three structures have to be adopted by the services: background jobs, queues and execution pools.
A client request initializes a background job which is put in an execution queue (In the meanwhile other jobs may run in the background). A task is then created and returned to the user in a supported MIME like
application/rdf+xml. A task is a resource that contains information about the progress and the status of a background job. While the background job is running, an estimation of the time left for the completion of its execution (percentage completed) is also included in the task. Clients can access the task URI to inspect the progress of their task and be informed about its (successful or unsuccessful) completion. We could say that a task is the loading bar of RESTful web services.
Tasks are characterized by their percentage of completion, their status (running, completed, cancelled, error), the result URI (appears upon completion) and an error report in case of an exceptional event. In particular a Task holds the following attributes:
dc:date- specifies when the task has been created; of type
dc:creator- specifying the URI of the resource, where the task has been created, of type
dc:title- human readable title of the task, of type
dc:description(optional , eventually might be used for error reporting ?)
ot:hasStatus- one of "Cancelled", "Completed", "Running", "Error", "Queued"
ot:percentageCompleted- of type
ot:resultURI- specifies the URI(s) of the newly created resource, of type
xsd:anyURI; present only if status is "Completed"
Tasks in OpenTox accept four status values: running, queued, completed, error, rejected and canceled. A task is tagged as running when the background job is either in the execution pool. Details about the progress of the execution may be revealed to the user as meta data (comment, description) in the task representation. If a background job was interrupted by some exceptional event, either because of a bad request or some internal server error, the related task must include an error report for this event (see API documentation for Error Reports). Completed tasks bear a link to the generated resource. Moreover, clients can cancel a task by applying the DELETE method on the task URI. It is up to the service provider to automatically cancel tasks that do not complete in a reasonable time period.
Error Reports are part of the OpenTox API since version 1.1. Error Reports define a formal way to handle exceptional situations while invoking a service or during inter-service communication thus facilitating debugging. They are sufficiently documented on-line at http://opentox.org/dev/apis/api-1.1/Error%20Reports. Error Reports are characterized by the actor of the exception (URI of the server or client that initiated the event), a brief explanatory message about the event, a detailed message that can also contain technical details , the HTTP status code that accompanies the report and another error report if the server reporting the exception acts as an error-proxy for an exception that happened while the server was acting as a client or proxy to some other server.
Features of Error Reports:
Users are entities that might optionally be exposed as resources by an OpenTox web service. Web services can use User resources to cater for accounting and implementation-specific access rights (e.g. various administrative tasks on the server can be exposed through an HTTP/REST interface). JAQPOT3 is so far the only OpenTox web service to have Users as resources and introduce User Quota. Models, Tasks, Compounds and other resources that can be created by a user, link back to it using the property ot:createdBy.