Introduction to the Adapter for Rserve

Rserve is a TCP/IP server that allows users to run R scripts directly from WebFOCUS or the Reporting Server without the need to initialize R or link to an R library.

The adapter is available on UNIX, Linux, and Windows. On UNIX and Linux, Rserve allows parallel sessions and, therefore, the environment supports multiple users. On Windows, Rserve does not support parallel connections. Multiple sessions are shared, so the environment supports a single user at a time.

The installation of R and Rserve, and the creation of the model are done without server or WebFOCUS involvement, and are prerequisites for configuring and using the Adapter for Rserve.

Prerequisites

Install R and Rserve on a host computer that has access to the WebFOCUS Reporting Server. Install them in a location for which you have write access.
Create an R model that you will want to run from WebFOCUS.
Save the R model (known as serialization) in a user script folder accessible to Rserve, using the R save command or the saveRDS function. The name and location of this folder will be determined by the Rserve administrator.
Create a .csv file that has only those columns that will be used as independent variables in the model. Do not include the dependent variable.
Write an R script to read and run the model.

R Script Features

The R script that will read and run the model must conform to the following rules:

The R script must read command line arguments, even though a command line interface is not used. In the following example, the command line arguments are saved to a variable named args.
```
args <- commandArgs(trailingOnly=TRUE)
```
The first argument is the name of the file to be processed by the model. The file name and a temporary HOLD file are automatically generated by the server. The second argument is the name of the output file. For example:
```
input_file <- file.path(args[1])
output_file <- file.path(args[2])
```
The result field name must match the output of the R script. For example, in the following syntax, the result field from the model is named Price:
```
colnames(results) <- c('Price')
write.csv(results, file=output_file, row.names=FALSE)
```

For a complete example, see Sample Session: Creating a Synonym for an R Script and Running the Script.

Server and WebFOCUS Steps

Once you have a model and the R script that runs it, you need a sample .csv file that contains a few rows of data for the independent variables used in the model. This file will be used to determine the data types and lengths of the independent variables when you create a synonym for the model.

Later, when you run the model from WebFOCUS, you will need a data file to run against that will provide values for the input variables to be passed to the RSERVE function. The function will return the result of running the model as output.

Therefore, the following steps must be completed in the server Web Console and WebFOCUS.

Configure the Adapter for Rserve, as described in Configuring the Adapter for Rserve.
Upload the sample input file (.csv) to the server. This file is needed for creating the synonym for the model.
Create a synonym for the model, as described in Creating a Synonym for an R Script.
Make sure an adapter has been configured for access to the data source against which you want to run the model.
Create a synonym for this data using the adapter configured in Step 4.
From WebFOCUS, create a report or chart that uses the RSERVE function in a COMPUTE, passes it the input values (independent variables), and retrieves the result, as described in Sample Session: Creating a Synonym for an R Script and Running the Script.

The following diagram summarizes the process of preparing the model, named my_model, to be called in a WebFOCUS procedure.

The following diagram summarizes the process of calling the model named my_model in a WebFOCUS procedure (against a data source supported by R).