RserveClient.pl - Methods for evaluating R code on an Rserve server
The basic way to call the R server is as follows:
loadMacros('RserveClient.pl');
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');The methods in this macro provide access to facilities of the R statistical computing environment, optionally located on another server, by using the Rserve protocol.
IMPORTANT: Before this macro can be used, the server administrator will need to configure the location of the Rserve host by setting $pg_envir->{specialPGEnvironmentVars}{Rserve}{host}. For webwork2 this is accomplished by adding the following line to webwork2/conf/localOverrides.conf:
$pg{specialPGEnvironmentVars}{Rserve} = { host => "localhost" };If using PG directly, then uncomment the Rserve: and following host: lines in pg/conf/pg_config.yml.
Without this configuration, the methods in this macro will display a warning about the missing configuration and return.
The methods in this file set up a connection to the R server and pass a string parameter to R for evaluation. The result is returned as a Perl object.
Start up and close the current connection to the Rserve server. In normal use, these functions are not needed because a call to any of the other methods will handle starting the session if one is not already open, and the session will be closed when processing of the current problem is complete.
Other than for backward compatibility, the only reason for using these functions is to start a new clean session within a single problem. This shouldn't be a common occurrence.
$result = 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.
$result = rserve_query($rexpr);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.
$remoteFile = rserve_start_plot($imgType, $width, $height);Opens a new R graphics device to capture subsequent graphics output in a temporary file on the R server. The $imgType, $width, and $height arguments are optional. The argument $imgType can be one of 'png', 'jpg', or 'pdf', and is set to 'png' if this argument is omitted. If $width and $height are unspecified, then the R graphics device's default size will be used. The name of the remote file is returned.
$localFile = rserve_finish_plot($remoteName);Closes the R graphics capture to file $remoteName, transfers the file to the directory specified by tempDirectory in the PG environment, and returns the name of the local file that can then be used by the image method.
$localFile = rserve_get_file($remoteName);Transfer the file $remoteName from the R server to the directory specified by tempDirectory in the PG environment, and returns the name of the local file that can then be used by the htmlLink method.
This method used to take an optional second argument that specified the local file name to save to. That parameter is deprecated, and is ignored if given.
An example of using this method follows. It is recommended that the rserve_data_url method be used instead of using this method since it takes care of the gory details needed to use this method as seen in the example below.
($intercept, $slope) = rserve_eval('coef(lm(log(dist) ~ log(speed), data = cars))');
($remoteFile) =
rserve_eval('filename <- tempfile(fileext = ".csv"); '
. 'write.csv(cars, filename); '
. 'filename');
$url = alias(rserve_get_file($remoteFile));
BEGIN_PGML
What is the slope of the linear regression of log-transformed stopping
distance vs. car speed in the dataset linked below: [_]{$slope}{5}
Download the [@ htmlLink($url, 'dataset', download => 'dataset.csv') @]*
file.
END_PGML$image = rserve_plot($rCode, $width, $height, $imgType);This method essentially combines rserve_start_plot, rserve_eval, and rserve_finish_plot into a single method. For example, calling
$image = rserve_plot("curve(dnorm(x, mean = $mean), xlim = c(-4, 4)); 0");is equivalent to calling
$remoteImage = rserve_start_plot('png');
rserve_eval("curve(dnorm(x, mean = $mean), xlim = c(-4, 4)); 0");
$image = rserve_finish_plot($remoteImage);The arguments $width, $height, and $imgType are optional. If $width and $height are unspecified, then the R graphics device's default size will be used. The argument $imgType can be one of 'png', 'jpg', or 'pdf', and is set to 'png' if this argument is omitted or is not one of the allowed values.
As with rserve_finish_plot, the file path that is returned that can be used via the [!alt text!]{$image} PGML construct or by the image method. For example,
BEGIN_PGML
What is the mean of the normal distribution shown in the figure below: [_]{$mean}{5}
[!normal distribution!]{$image}{300}
END_PGML$url = rserve_data_url($rDataName);Creates a temporary CSV file on the R server with the data named by $rDataName, transfers it to the directory specified by tempDirectory in the PG environment, and returns a URL that can by used with the htmlLink method. For example,
($intercept, $slope) = rserve_eval('coef(lm(log(dist) ~ log(speed), data = cars))');
$local_url = rserve_data_url('cars');
BEGIN_PGML
What is the slope of the linear regression of log-transformed stopping
distance vs. car speed in the dataset linked below: [_]{$slope}{5}
Download the [@ htmlLink($url, 'dataset', download => 'dataset.csv') @]*
file.
END_PGMLNote that it is recommended that the download attribute be added so that the download file name will be the value of that attribute rather than the lengthy alias name in the $url.