Using ToxOtis one can parse remote OpenTox entities providing their URI or even OpenTox resources that are stored in some local file. Behind the scenes, ToxOtis downloads and parses an RDF representation of the resource and parses it into some instance of OTOnlineResource. For this purpose, the user is endowed with two tools: The abstract method loadFromRemote defined in OTOnlineResource (doc) and a set of spiders (doc) which are more powerful tools but also require a higher level of acquaintance with RDF and Jena (a library for parsing and editing RDF documents in Java). The ToxOtis API for downloading and parsing OpenTox resources is intertwined with the OpenTox A&A API, so in many cases users will need to provide their authentication token.
All subclasses of OTOnlineResource in ToxOtis, like Compounds, Features, Algorithms and Models can be downloaded from a remote location into some local resource such as a file or a variable (e.g. a String), or in general be directed to some output stream or written to some generic destination using a Write. The prototype methods are:
void download(String destination, Media media, AuthenticationToken token) throws ToxOtisException; void download(OutputStream destination, Media media, AuthenticationToken token) throws ToxOtisException; void download(File destination, Media media, AuthenticationToken token) throws ToxOtisException; void download(Writer destination, Media media, AuthenticationToken token) throws ToxOtisException
This way, one can download the MOL representation of a compound and write it into a file. Here is an example of use:
Compound comp = new Compound(new VRI(Services.IDEACONSULT).augment("compound","10"));
File destination = new File("/path/to/file.mol");
comp.download(destination, Media.CHEMICAL_MDLMOL, (AuthenticationToken)null);
Before proceeding to the next sections, users are adviced to take a look at the documentation about the implementation of OpenTox components in ToxOtis.
A predefined collection of OpenTox algorithms is available within the class OpenToxAlgorithms (doc). You can load the algorithm data from the remote location using the method loadFromRemote defined in Algorithm (doc). Here is an example:
Algorithm myAlg = new Algorithm(OpenToxAlgorithms.TUM_KNN_CLASSIFICATION.getServiceVri()); // This will load into your object all information found at the remote location: myAlg.loadFromRemote(); System.out.println(myAlg.getMeta());
The above source code will print the following to the System standard output:
identifier : http://opentox.informatik.tu-muenchen.de:8080/OpenTox-dev/algorithm/kNNclassification^^string
title : kNNclassification^^string
description : OpenTox REST interface to the WEKA k-Nearest Neighbor learning algorithm.
Can select appropriate value of K based on cross-validation. Can also do distance weighting.^^string
date : Mon Sep 13 20:19:24 EEST 2010^^dateTime
creator : tobias.girschick@in.tum.de^^string
If the algorithm is a protected resource you will have to authenticate yourself against that algorithm service providing an authentication token (doc). Here is an example:
Algorithm myAlg = new Algorithm(OpenToxAlgorithms.NTUA_MLR.getServiceVri());
AuthenticationToken at = PasswordFileManager.CRYPTO.authFromFile("./.secret/.my_secret.key");
// This will load into your object all information found at the remote location:
myAlg.loadFromRemote(at);
The following example illustates how to use a Dataset Spider (doc) to download and parse a dataset from a remote server:
VRI vri = new VRI(Services.IDEACONSULT.augment("dataset","5"));
// Require that the dataset will contain no more than 10 compounds
final int size = 10;
vri.addUrlParameter("max", size);
DatasetSpider spider = new DatasetSpider(vri);
Dataset ds = spider.parse();
Now we can use this Dataset object to inspect its dataentries and values:
DataEntry de = ds.getDataEntries().get(2); FeatureValue fv = de.getFeatureValue(0); System.out.println(de.getConformer().getUri()); System.out.println(fv.getFeature().getUri() + " = " + fv.getValue());
The above code will print the following message to the System’s standard output:
http://apps.ideaconsult.net:8080/ambit2/compound/2554/conformer/327497 http://apps.ideaconsult.net:8080/ambit2/feature/20083 = 100-01-6^^string
Alternatively you can of course use the implementation of the method loadFromRemote() in Dataset (doc). Here is an example:
VRI vri = new VRI(Services.AMBIT_UNI_PLOVDIV.augment("dataset","9"));
Dataset ds = new Dataset(vri);
ds.loadFromRemote();
This will parse into the object ds the data downloaded from the URI: ambit.uni-plovdiv.bg:8080/ambit2/dataset/9.
Error Reports (code) (doc) 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 online at opentox.org/dev/apis/api-1.1/Error Reports. The parsing of Error Reports is carried out quite the same way as the entities mentioned above. The only difference with Error Reports is the the URL that hosts the error report differs from the IRI that describes the report in the RDF graph returned. So, if you choose to use a spider for parsing an Error Report you have to be careful with the initialization: The standard constructor for a spider ErrorReportSpider(Resource resource, Model model) will probably throw an error if you provide the wrong resource. This is why, you should prefer the constructor ErrorReportSpider(URI actorUri, Model ontModel) (doc) where you provide the URI of the actor of the exception and not the RDF node straightforward! Here is an example to obfuscate any misunderstanding:
VRI uri = new VRI(Services.NTUA.augment("algorithm", "mlr"));
GetClient client = new GetClient();
client.setUri(uri);
OntModel model = client.getResponseOntModel();
ErrorReportSpider spider = new ErrorReportSpider(uri, model);
ErrorReport er = spider.parse();
Error reports also appear in ToxOtisException (doc). When a ToxOtis Exception is thrown due to some exception thrown by a remote service, the Error Report from that service is incorporated into the exception. Here is an example:
VRI uri = new VRI(Services.NTUA.augment("algorithm", "mlr"));
try {
new AlgorithmSpider(uri);
} catch (ToxOtisException tox) {
System.out.println(tox.getRemoteErrorReport());
}
This will print to the System’s output the following text:
URI : http://opentox.ntua.gr:3000/errorReport/#2390078396 Actor : http://opentox.ntua.gr:3000/algorithm/mlr Code : AuthenticationFailed Status : 403
This is an example of how a user can download and parse an OpenTox Model (code) (doc) from a remote location:
VRI vri = new VRI(Services.NTUA.augment("model","f9a97443-6baf-4361-a55c-b08cf12c3e39"));
ModelSpider mSpider = new ModelSpider(vri);
Model m = mSpider.parse();
The above code downloads the model from opentox.ntua.gr and creates the object m: Model. The same can be accomplished using a Model object exclusivle. Here is an alternative way:
VRI vri = new VRI(Services.tumDev().augment("model","TUMOpenToxModel_j48_7"));
Model m = new Model(vri);
m.loadFromRemote();
A Task (code) (doc) is parsed as simply as any other OpenTox component. You simply have to provide its URI and invoke the method loadFromRemote() or, in case authentication is needed, loadFromRemote(AuthenticationToken). Here is an example of use:
VRI vri = new VRI("http://opentox.ntua.gr:3000/task/0fc060a0-f69b-4a81-bb2e-b9b32c8a04b3");
Task t = new Task(vri).loadFromRemote();
Compounds (code) (doc), as these are represented in OpenTox, do not provide much information that could be parsed from their RDF representation, so the API for Compounds is formulated in a way that meaningful information would be returned to the user. First of all, users can obtain the Set of conformers (if any) that it groups and delegates. In cases where 3D characteristics of the compound are not taken into account, conformers do not play a particular role, otherwise the exact conformer has to be determined. The set of these conformers is available using the method Set<Conformer> listConformers(AuthenticationToken token) throws ToxOtisException. What is more, one can download the compound and store it in some supported chemical media type like sdf or mol as it was explained in the previous section. Here is an example of downloading the SD file of a given compound:
Compound c =new Compound(Services.IDEACONSULT.augment("compound","100"));
c.download(new File("/path/to/file.sdf"), Media.CHEMICAL_MDLSDF, null);
The compound and conformer APIs in ToxOtis are taking just their first steps so there is not much functionality in there yet.