Experiments Service Description The Lifemapper Experiments Service is a RESTful service that allows you to list experiments, get an experiment, or post a new experiment.
A Lifemapper experiment is a grouping of a model and all projections built from it. The Lifemapper pipeline generates experiments based on unmodeled taxa as well as movels that are out of date. In addition, users can submit their own experiments with the algorithm parameters tuned to their liking. Getting a List of Experiments You can view a list of experiments by clicking this link. This will bring up a list of all experiments associated with the "lm2" user.
This list of experiments can be browsed and filtered via url query parameters. For example, if you wanted to return only completed experiments generated using the Bioclim algorithm you could use the following url:
http://lifemapper.org/services/lm2/experiments/?status=35&algorithmCode=BIOCLIM .
A complete list of available url parameters for the experiments listing service can be found here.
The list of experiments is available in a variety of formats. These formats do not contain the actual experiment data, just metadata about them.
Formats available:
Getting an Individual Experiment You will need the experiment id number to return an individual experiment. If you submitted an experiment, you should have this number. You can also browse the list to find the experiment you want and just click the link.
Get an Individual Experiment Method explains in more detail how this service works.
Formats available: Posting an experiment The experiment submission page can lead you through the process of submitting a new experiment. It will begin by helping you pick an existing occurrence set or upload a new one. Then you will be able to select an algorithm and set its parameters and finally select your model and projection scenarios.
You also have the option to submit an experiment directly.
To submit a new experiment, you will first need to make sure you have all of the necessary pieces. The required elements for a Lifemapper experiment are an occurrence set id, an algorithm parameter set id, a model scenario id, and a group of projection scenario ids.
-
Pick an Occurrence Set
-
Pick an Algorithm Parameters Set
- Pick a model scenario
-
Pick a group of projection scenarios
Once you have all of the parts, you can submit a new experiment either through URL parameters, or via the message body of an HTTP POST request.
Post an Experiment from URL parameters
To post an experiment via URL parameters, you just need to determine what the url should be and send an HTTP POST request to it. For this example, we will use occurrence set 3345122, algorithm parameters set 13, scenario 32 for the model, and scenarios 32, 33, and 35 for projections. We will also use the public anonymous user for the owner of this experiment.
The resulting url is:
http://lifemapper.org/services/anon/experiments/xml?algorithmParametersId=13&occurrenceSetId=3345122&modelScenario=32&projectionScenario=32&projectionScenario=33&projectionScenario=35
If you send an HTTP POST to that url, the response will be something like:
<?xml version="1.0" encoding="utf-8"?> <?xml-stylesheet type="text/xsl" href="/css/services.xsl"?> <lm:response xmlns:lm="http://lifemapper.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://lifemapper.org /schemas/serviceResponse.xsd"> <lm:title>Accepted experiment(s)</lm:title> <lm:user>lm2</lm:user> <lm:urls> <lm:url> http://lifemapper.org/services/anon/experiments/215 </lm:url> </lm:urls> </lm:response>
The HTTP response code should be 202. If it is 400 check your request. If it is anything else, contact us at: lifemapper [at] ku [dot] edu for help.
When you read the response, note that the element in: lm:response/lm:urls/lm:url will contain a url pointing to your new experiment. Keep note of the experiment id which is the number listed at the end of the url. In this case, the experiment id is 215.
Post an Experiment from the Message Body of a Request
To past an experiment via the request message body, you will need to send an HTTP POST request to the base experiments service url (with the desired user specified). For example, if we use the Lifemapper public anonymous user as the owner of this new experiment, the resulting url is:
http://lifemapper.org/services/anon/experiments/xml
Next, we will build the request message body. This is the content that should be posted to the service. We will use the same id numbers that we did when we posted a new experiment via url parameters to show the differences in the two approaches.
Those values again were:
- 13 for the algorithm parameter set id
- 3345122 for the occurrence set id
- 32 for the model scenario
- 32, 33, and 35 for the projection scenarios
You can see an example request at:
http://lifemapper.org/samples/sampleExperimentRequest.xml
Our example results in a request looking like this:
<?xml version="1.0" encoding="utf-8"?> <lm:request xmlns:lm="http://lifemapper.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://lifemapper.org /schemas/serviceRequest.xsd"> <lm:experiment> <lm:modelScenario>32</lm:modelScenario> <lm:projectionScenarios> <lm:projectionScenario>32</lm:projectionScenario> <lm:projectionScenario>33</lm:projectionScenario> <lm:projectionScenario>35</lm:projectionScenario> </lm:projectionScenarios> <lm:algorithmParametersId>13</lm:algorithmParametersId> <lm:occurrenceSetId>3345122</lm:occurrenceSetId> </lm:experiment> </lm:request>
If you send an HTTP POST to our url with this as the request body, the response will be something like:
<?xml version="1.0" encoding="utf-8"?> <?xml-stylesheet type="text/xsl" href="/css/services.xsl"?> <lm:response xmlns:lm="http://lifemapper.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://lifemapper.org /schemas/serviceResponse.xsd"> <lm:title>Accepted experiment(s)</lm:title> <lm:user>lm2</lm:user> <lm:urls> <lm:url> http://lifemapper.org/services/anon/experiments/282 </lm:url> </lm:urls> </lm:response>
The HTTP response code should be 202. If it is 400 check your request. If it is anything else, contact us at: lifemapper [at] ku [dot] edu for help.
When you read the response, note that the element in: lm:response/lm:urls/lm:url will contain a url pointing to your new experiment. Keep note of the experiment id which is the number listed at the end of the url. In this case, the experiment id is 282.