Using R Integration with WeBWorK

The upcoming release of WeBWorK will include the ability to use questions which call on the R statistical software package to do calculations and generate images. This guide provides instructions for adding support for R to your current WeBWorK installation. It assumes that you already have the most recent version of WeBWorK (2.12) running on your server.

Installation

After you have a working WeBWorK server, there are four distinct steps that need to happen:

1. set up the R server
2. install the Perl module for the Perl-R bridge
3. upgrade to a version of WeBWorK that supports the R server
4. enable the R server in your WeBWorK configuration

Set up the R server

Your R server (which can be on the same server as WeBWorK, but in a real-world scenario will more likely run on its own hardware/VM), is quite easy to set up:

1. install R following OS-specific instructions on the project homepage.
2. install the Rserve server, which allows remote clients to execute R code on the Rserve's server and returns the execution's result in response. The easiest way is to run (as an administrative user) Rscript -e 'install.packages("Rserve", repo="http://cran.rstudio.com")'. Note that this package includes C source that needs to be compiled, so you have to have the basic developer tools present on the server.
3. run the Rserve service as appropriate to your system. The command you need to run is "R CMD Rserve". This will start the Rserve daemon which will listen on port 6311. The daemon only accepts connections from the localhost; if you run WebWork and Rserve on separate servers, read the final section of this page for additional configuration steps for your system. For systems using systemd (RHEL CentOS > 7, Ubuntu >15), you may use the following instructions to have Rserve start on boot:
   • Download this file, and place it in /usr/lib/systemd/system. Now you can start Rserve with the command (as a superuser) systemctl start rserve. You can also set Rserve to start at startup with the command systemctl enable rserve.

Install the Perl-R bridge

Perl module Statistics::R::IO implements Rserve's communication protocol in Perl and provides translation from R data structures to Perl's. It is available on CPAN and can be installed in the standard manner for Perl modules, e.g., by running (as an admin user) cpan Statistics::R::IO.

Switch to a Version of WeBWorK that supports Rserve

There are currently two different versions of WeBWorK that include support for Rserve:

• develop - the development version of WeBWorK. This is the latest WeBWorK code that includes untested features. While efforts are made to keep this stable, it is pre-release, and thus may have undiscovered issues.
• 2.12-r - a copy of the 2.12 release of WeBWorK with only the Rserve support added on. If you are running 2.12, switching to this branch should not require any significant changes to your WeBWorK installation.

To switch to one of these versions, you will need to run the following commands as root (or add sudo in front of the commands):

   cd /opt/webwork/webwork2
   git fetch origin
   git branch -t [version] origin/[version]
   git checkout [version]
   cd /opt/webwork/pg
   git fetch origin
   git branch -t [version] origin/[version]
   git checkout [version]

(where [version] is either develop or 2.12-r).

If you switch to the develop version, you may need to log into the admin course and upgrade your courses.

Enabling R in WeBWorK

Edit localOverrides.conf (usually found at /opt/webwork/webwork2/conf/localOverrides.conf) and add the following line before the final line:

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

You should now be able to load questions which call R. There are a number of such questions already in the OPL, for example Library/UBC/STAT/STAT300/hw07/stat300_hw07_q02.pg (which can be found under Statistics -> Simple linear regression -> Hypothesis tests). If your R server is working properly, you should see a scatterplot in this question.