Expose R Scripts as Webservices with WPS4R

---

Authors: Matthias Hinz, Benjamin Proß, DanielNuest

This quick tutorial will show you how to deploy an R script in the 52°North WPS. Therefore we start with a one-line mini script and evolve it step-by-step till it is a whole integrated process.

For general configuration instructions please see WPS4RDocumentation.

Base Script

In R, we call the runif()-function to produce a single random number between to numbers, e. g. 0 and 1. This is basically what we want our process to do:

> runif(1, min=0, max=1)

[1] 0.6292043

1. Input/Output

The first thing to do is to write an R script and consider input / output data of the process. Hence we specify the variables "min" and "max" for input and "output" for output.

Meta-information about input and output is required. Add an annotation for each one, which consists at least of a variable name (id-attribute) and its data type (type-attribute, see section supported input / output types). We also add default values (value-attribute) to the input annotations. Note that the declarations "min = 0" "max = 1" were replaced by annotations and therefore disappeared from the script so that it won't run in R as-is. You can use "wps.on" and "wps.off" annotations to declare them again.

2. Metadata

Now we add even more metadata. A WPS process requires at least an id and can be described within the fields "title" and "abstract". Similar descriptions can be added for each input and output variable so that purpose and usage of the process is clear.

3. Complex input: Text

In case you want to handle complex input or output, you need too read/write the data from within R and receive/pass the filename as input/output reference. To demonstrate this we generate a list of 100 random variables and pass it as a text file, using the write.table function in R.

4. Upload the script

4. A) Admin Backend

THIS FEATURE IS CURRENTLY NOT WORKING, PLEASE DEPLOY MANUALLY

Save the script file, e.g. as "Random.R", open your web browser; open the Web Admin Console of your WPS instance. You need the following access data:

• URL: http://\:\/wps/webAdmin/index.jsp (default on local machine: http://localhost:8080/wps/webAdmin/index.jsp)
• User name (default: wps)
• Password (default: wps) Click the button "Upload R script" and fill out the upload form. You only got to specify the file location, but you also have the opportunity to give the process a (different) name, e.g. "RandomNumbers". Submit the data.

In the "algorithm repositories" tab, among the properties of the "LocalRAlgorithmRepository" should now occur one with value org.n52.wps.server.r.R_andom. This is the full process identifier, where the suffix org.n52.wps.server.r. denotes a namespace to distinguish R processes from others.

Figure 1: Upload the script

Figure 2: Repository view - process ready to use

4. B) Manual Script Upload

You can also publish the script manually by copying it into the script directory. Then restart the WPS and execute a GetCapabilities request to check that the process was added. If the script is not published as a process then open the WPS log file and check for parsing errors.

The default script directory is <webapp directory/R/scripts. You can also configure a different script directory in the file wps_config.xml or via the WPS Admin.

5. Send request

Send WPS requests to test the process (change host/port if required):

• GetCapabilities-request via GET: http://localhost:8080/wps/WebProcessingService?Request=GetCapabilities&Service=WPS
• DescribeProcess-request via GET: http://localhost:8080/wps/WebProcessingService?Request=describeProcess&Service=WPS&Identifier=org.n52.wps.server.r.RandomNumbers
• Execute-request: Go through WPS TestClient to send a POST requrest
  • http://localhost:8080/wps/test.html
  • Submit the following request:

    <?xml version="1.0" encoding="UTF-8"?>
    <wps:Execute service="WPS" version="1.0.0" xmlns:wps="http://www.opengis.net/wps/1.0.0" 
    xmlns:ows="http://www.opengis.net/ows/1.1" 
    xmlns:xlink="http://www.w3.org/1999/xlink" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 http://schemas.opengis.net/wps/1.0.0/wpsExecute_request.xsd">
            <ows:Identifier>org.n52.wps.server.r.RandomNumbers</ows:Identifier>
            <wps:ResponseForm>
                    <wps:RawDataOutput mimeType="text/plain">
                            <ows:Identifier>output</ows:Identifier>
                    </wps:RawDataOutput>
            </wps:ResponseForm>
    </wps:Execute>

    
    A list of 100 random values should now appear. If so, your process has been successfully deployed!

Script file

You can download the full script file here: wps4r-tutorial.R