Logo of 52°North

WPS4R - the R Backend of the 52°North WPS

In the following the main principles of exposing R scripts as WPS processes are explained.
To set up your system for WPS4R follow this tutorial. A short step-by-step tutorial is available here.

Create and manage processes

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

  1. How to upload processes
    1. Open Web Admin Console in your browser (URL: http://<service host>:<service port>/wps/webAdmin/index.jsp)
    2. Click "Upload R Script"
    3. Choose an annotated R script (Process id will be org.n52.wps.server.r.[filename])
    4. Optionally choose a process name (Process id will be org.n52.wps.server.r.[process name])
    5. Click "submit", process will be submitted and added to the LocalRAlgorithmRepository
  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 clicking "x", activate / deactivate them with the checkbox
    5. Click "Save and Activate configuration" to make changes take effect

     

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:

In order to expose a R script as a WPS process, you will have to annotate the script. These annotations are described in the following.

  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 occur 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 occur once for each input variable. They provide information for the process description as well as for parsing the input. Before the script is executed, the WPS will initialize a variable of the declared name ("id"), which 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 denotes 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";

    AttributeTypeAnnotationMandatoryDescription
    abstractStringwps.des, 
    wps.in, 
    wps.out
    NoEquals Abstract-arguments of process description
    identifierStringwps.des, wps.in, wps.outYesEquals Identifier-arguments of process description  
    Id in wps.des currently does not affect anything, cause retrieved from filename or upload form
    minOccursInteger(0 or 1)wps.inNoEquals minOccurs-arguments of process description; Set to 0 if a default value was given, otherwise 1
    maxOccursIntegerwps.inNoEquals maxOccurs-arguments of process description 
    Multiple inputs for one id are currently not supported
    titleStringwps.des, wps.in, wps.outNoEquals Title-arguments of process description
    typeStringwps.in, wps.outYesType argument for input or output according to the list in section "Supported input/output types"
    valueAny value(to be read from R)wps.inNoSet a default literal value to a process input; this means minOccurs=0, maxOccurs=1

     

  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

     

Supported input/output types

The following data types and mime types are currently supported by WPS4R. 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 typeAnnotation keyInputOutput
doubledoubleYesYes
integerintegerYesYes
stringstringYesYes
booleanbooleanYesYes

Complex data / raster

Data typeAnnotation keyInputOutput
application/dbasedbfYesYes
application/geotiffgeotiffYesYes
application/x-geotiffgeotiff_xYesYes
application/imgimgYesYes
application/x-erdas-hfaimg_xYesYes
application/netcdfnetcdfYesYes
application/x-netcdfnetcdf_xYesYes
application/remapremapYesYes

Complex data / image

Data typeAnnotation keyInputOutput
image/geotiffgeotiff_imageYesYes
image/gifgifYesYes
image/jpegjpegYesYes
image/pngpngYesYes
imgage/tifftiffYesYes

Complex data / vector

Data typeAnnotation keyInputOutput
application/dgndgnYesYes
application/shpshpYesYes
application/vnd.google-earth.kmlkmlYesYes
application/x-zipped-shpshp_xYesYes

Complex data / text

Data typeAnnotation keyInputOutput
text/plaintextYesYes
text/xmlxmlYesYes