NAME

RserveClient.pl - Macros for evaluating R code on an Rserve server

SYNOPSIS

Here's a basic way to call the R server:

loadMacros('RserveClient.pl');

rserve_start();
my @rnorm = rserve_eval("rnorm(15, mean=$m, sd=$sd)");
rserve_eval(data(stackloss));
my @coeff = rserve_eval('lm(stack.loss ~ stack.x, stackloss)$coeff');
rserve_finish();

DESCRIPTION

The macros in this file provide access to facilities of R statistical computing environment, optionally located on another server, by using the Rserve protocol.

IMPORTANT: Before you can use these macros, you will need to configure the location of your Rserve host by adding it to $pg{specialPGEnvironmentVars}{Rserve}{host}, for instance by appending the following line to webwork2/conf/localOverrides.conf:

$pg{specialPGEnvironmentVars}{Rserve} = {host => "localhost"};

Without this configuration in place, Rserve macros will only print out a warning about missing configuration and return undef.

MACROS

The macros in this file set up a connection to the R server and pass a string parameter to R for evaluation. The resulting vector is returned as a perl array object.

rserve_eval REXPR

Evaluates an R expression, given as text string in REXPR, on the Rserve server and returns its result as a Perl representation of the Statistics::R::REXP object. Multiple calls within the same problem share the R session and the object workspace.

rserve_query

Evaluates an R expression, given as text string in REXPR, in a single-use session on the Rserve server and returns its result as a Perl representation of the Statistics::R::REXP object.

This function is different from rserve_eval in that each call is completely self-enclosed and its R session is discarded after it returns.

rserve_start, rserve_finish

Start up and close the current connection to the Rserve server. In normal use, these functions are completely optional because the first call to rserve_eval will call start the session if one is not already open. Similarly, the current session will be closed in its destructor when the current question goes out of scope.

Other than backward compatibility, the only reason for using these functions is to start a new clean session within a single problem, which shouldn't be a common occurrence.

rserve_start_plot [IMG_TYPE, [WIDTH, HEIGHT]]

Opens a new R graphics device to capture subsequent graphics output in a temporary file on the R server. IMG_TYPE can be 'png', 'jpg', or 'pdf', with 'png' as the default. If left unspecified, WIDTH and HEIGHT, will use the R graphics device's default size. Returns the name of the remote file.

rserve_finish_plot REMOTE_NAME

Closes the R graphics capture to file REMOTE_NAME, transfers the file to WebWork's temporary file area, and returns the name of the local file that can then be used by the image macro.

rserve_get_file REMOTE_NAME, [LOCAL_NAME]

Transfer the file REMOTE_NAME from the R server to WebWork's temporary file area, and returns the name of the local file that can then be used by the htmlLink macro. If LOCAL_NAME is not specified, the filename portion of the REMOTE_NAME is used.

DEPENDENCIES

Requires perl 5.010 or newer and CPAN module Statistics::R::IO, which has to be loaded in WebWork's Safe compartment by adding it to ${pg}{modules}.