WPS4R – the R Backend of the 52n WPS

WPS4R is a solution for creating WPS processes via R-scripts during runtime. Those scripts are stored by the WPS and executed by Rserve. Rserve is an independent TCP / IP Server for R, which has either a local or a remote connection to the WPS and therefore could run on a different server. (See http://www.rforge.net/Rserve/)

Content:

1. Create and manage processes

Processes creation is done by uploading R-scripts. These scripts are supplemented by annotations. The annotation provide a framework for on-the-fly generation of process description documents and declaration of input / output variables of the R process.

1.1. How to upload processes

  1. Open Web Admin Console in your browser (URL: http://<service host>:<service port>/wps/webAdmin/index.jsp)
  2. Press "Upload R Script"
  3. Enter the location of an annotated R script, eventually choose a process name
    (Process id will be either org.n52.wps.server.r.[filename] or org.n52.wps.server.r [process name])
  4. Press "submit" (resp. “Daten absenden”), process will be active from now

Image: How to upload scripts
Figure 1: Upload form for R processes

1.2. How to manage processes

  1. Open Web Admin Console in Browser
  2. Go to “Algorithm Repositories”, scroll down name “LocalRAlgorithmRepository”
  3. Among the properties are the registered processes. They got the name “Algorithm” and a value which is the process identifier
  4. Delete processes by pressing “x”, activate / deactivate them with the checkbox
  5. Press "Save and Activate configuration” to make changes take effect

Image: Manage WPS4R repository
Figure 2: Manage WPS4R repository

2. R scripts and WPS-annotations

For working with R scripts, any text editor can be used. But it is easier to use GUIs with syntax highlighting, such as:

2.1. Syntax and semantics

There are three types of annotations, which might occur anywhere in the script: wps.in, wps.out and wps.des. Arguments are passed either sequential, as unordered key-value pairs or as composite of sequence and key-value pairs. The wps.des-annotation occurs only once in a script. Every input / output variable refers to one annotation and vice versa. Mandatory arguments for each wps.in- and wps.out-annotation are "identifier" and "type". For R, annotations simply appear as comments, so each line has to start with '#'.

Usage:

wps.des: id, title, abstract;

Wps.des - annotations might occure just once in a script, they provide general information for the process description


wps.in: id, type, title, abstract, value = null, minOccurs = 1, maxOccurs = 1;

Wps.in - annotations occure once for each input variable. They provide information for the process description as well es for parsing the input. Before the script is executed, WPS4R will initialize a variable of the declared name ("id"), wich either holds a literal value or a file URI (path as string), which points to a data file.


wps.out: id, type, title, abstract;

A Wps.out - annotation usually occurs once in a script and dentotes the output variable. Similar to the wps.in annotation it provides information for the process description and data handling. The corresponding output variable has to be initialized from within the script.

Examples:

wps.in: variable1, integer, this is variable1, further description;

wps.in: variable2, string, abstract = further description, value = "abc";

Attribute Type Annotation Mandatory Description
abstract String wps.des,

wps.in,

wps.out

No Equals Abstract-arguments of process description
identifier String wps.des,

wps.in,

wps.out

Yes Equals Identifier-arguments of process description
Id in wps.des currently does not affect anything, cause retrieved from filename or upload form
minOccurs Integer
(0 or 1)
wps.in No Equals minOccurs-arguments of process description; Set to 0 if a default value was given, otherwise 1
maxOccurs Integer, usually 1 wps.in No Equals maxOccurs-arguments of process description; Usually set to 1
Multiple inputs for one id are currently not supported
title String wps.des,

wps.in,

wps.out

No Equals Title-arguments of process description
type String wps.in,

wps.out

Yes Type argument for input or output according to the list in section “Supported input/output types”
value Any value

(to be read from R)

wps.in No Set a default literal value to a process input; this means minOccurs=0, maxOccurs=1

2.2. Script example

# wps.des: simpleExample, title = A Simple WPS Process, 
# abstract = Example Calculation with R;

# wps.in: input, integer;

# wps.out: output, double;

# calculate something... variable "input" don't has to be initialized
output = runif(1)*input

3. Supported input/output types

The following data types and mime types are currently supported by WPS4E. Default encoding is „UTF-8“. Note that every complex input has to be imported from within R, therefore you got to rely on packages like “rgdal”, for example, if you want to import a shape file, use:

<inputID>= readOGR(<inputID>, sub(“.shp”, ””, <inputID>))

Literal data

Data type Annotation key Input Output
double double Yes Yes
integer integer Yes Yes
string string Yes Yes
boolean boolean Yes Yes

Complex data / raster

Mime type Annotation key Input Output
application/dbase dbf Yes Yes
application/geotiff geotiff Yes Yes
application/x-geotiff geotiff_x Yes Yes
application/img img Yes Yes
application/x-erdas-hfa img_x Yes Yes
application/netcdf netcdf Yes Yes
application/x-netcdf netcdf_x Yes Yes
application/remap remap Yes Yes

Complex data / image

Mime type Annotation key Input Output
image/geotiff geotiff_image Yes Yes
image/gif gif Yes Yes
image/jpeg jpeg Yes Yes
image/png png Yes Yes
imgage/tiff tiff Yes Yes

Complex data / vector

Mime type Annotation key Input Output
application/dgn dgn Yes Yes
application/shp shp Yes Yes
application/vnd.google-earth.kml kml Yes Yes
application/x-zipped-shp shp_x Yes Yes*

Complex data / text

Mime type Annotation key Input Output
text/plain text Yes Yes
text/xml xml Yes Yes
* Output files are not zipped automatically, to return zip archives, you must zip it from within R using the zip()-function