Rpad is an interactive, web-based analysis program. Rpad pages are interactive workbook-type sheets based on R, an open-source implementation of the S language. Rpad is an analysis package, a page designer, and a gui designer all wrapped in one. Rpad makes it easy to develop powerful data analysis applications that can be shared with others (most likely on an intranet). The user doesn't have to install anything--everything's done through a browser.
From the user's point of view, Rpad shouldn't really need any documentation. It just looks like a web page. The user can run a pre-canned analysis and poke around with the inputs and scripts and outputs. For designers of Rpad pages, some more background is helpful.
Rpad is available in two versions: a local version and an intranet/internet version. The local version works through the user's local installation of R through the user's web browser. The intranet/internet version works in client-server fashion with the user accessing a remote server through a standard web browser.
The simplest way to set up a page is to use one or more Rpad script regions. Scripts can be inside of div, span, or textareas. Scripts can be R, shell, or javascript. Server-side shell scripts are useful for using other scripting or command-lines (python, octave, imagemagick, and so on). Javascript is useful for local processing, interactivity, or for debugging Rpad problems.
To "run" or "calculate" a page, press the F9 key or use the mouse to press the "Calculate" menu option. While a web page is up, Rpad is communicating with the same R process. That means all the variables are still there (even if you change the script). This can have some desirable or undesirable effects, so it's good to be aware of it. Refreshing the page will restart the R process.
In the default configuration, Rpad pages no longer have default in-page editing. As such, Rpad pages are normally created with an external text or HTML editor. In-browser editing is still too immature. There are two page-editing gui's that can be enabled. Consider both of these as experimental:
These builtin page editors are somewhat limited. They may not generate very good HTML, and saving pages has some bugs in it (it doesn't save anything in the HEAD, and on some browsers, changes to INPUT blocks don't get saved right). For more advanced and reliable editing, use an external text or HTML editor. The builtin page editors are best used for online changes and exploration.
The Rpad package provides several R utility routines to help the user do graphs and generate HTML output and HTML GUI elements.
You can turn any HTML file into an editable Rpad page. Simply insert the following code into the page header:
<script type="text/javascript" src="gui/Rpad.js"></script>
Within the body of an HTML file, any tag can be made into an Rpad script tag with 'dojoType="Rpad"'. Normally, this is a pre or textarea. Here's a simple example:
<pre dojoType="Rpad"> ls() </pre>Rpad input blocks have several optional attributes to control behavior. Here's a more detailed example with options specifying that the block runs only initially and the source is hidden:
<pre dojoType="Rpad" rpadRun="init" rpadHideSource="true"> ls() </pre>
There are several kinds of Rpad input variations. The attribute 'rpadType' specifies the options, which include:
rpadRun controls when an Rpad section is calculated. Options are:
rpadOutput controls how the output from Rpad section is interpreted. Options are:
Within an R block with rpadOutput of "text" or "html", the formatting can be switched between "text" and "html" by HTMLon() or HTMLoff(). Rpad output sections are normally rendered as plain text with a fixed-width font, so text script outputs are formatted properly. The output blocks can also contain HTML codes for displaying images or for formatted blocks. To change to HTML formatting, send '<htmlon/>' to the output. This is HTMLon() or cat('<htmlon/>') in R scripts. To turn HTML mode off, send '<htmloff/>' or HTMLoff() in R scripts.
"true" if the script source is hidden (outputs are shown). The default is "false".
<script type="text/javascript">
rpadConfig = {
gui: "alternate",
rpadHideSource: true,
onBeforeUnload: false
};
</script>
<script type="text/javascript" src="gui/Rpad.js"></script>
The defaults for rpadConfig are:
gui: "none"
rpadType: "R"
rpadHideSource: false
rpadOutput: "normal"
rpadRun: "normal"
onBeforeUnload: false
In addition to the Rpad section defaults, the option "gui" can be used to specify the page editing gui. If set to true, the option "onBeforeUnload" means to ask the user if it's okay to browse away from the current page.
HTML form elements (input, select, radio, and checkbox) with a name attribute are automatically sent to R when calculate is run. The 'name' is translated into an R variable name. To make the GUI elements selectable, they must be surrounded by <span contenteditable="false"></span> (also for url links and buttons).
Input elements have two options for the rpadType attribute; one of them must be specified for the calculation to take place. With rpadType="Rvariable", the input is read as an R expression (e.g 1.33 or 2*pi or 3*x + sum(3,6,7)). With rpadType="Rstring", the input is treated as a character string. On Mozilla, the Rstring is colored blue to differentiate it (with a little CSS that IE doesn't support).
Radio buttons have two name attributes: commonName is the the name of the radio button set, and variableName is the specific name of this radio button.
If you have several input tags together, it is best to wrap them in a <form> element. Then, all elements are passed to R together rather than one at a time, so the page is more responsive.
You can use javascript to add interactivity to your Rpad pages. The easiest way is to add javascript commands to buttons. Some common functions that can be used in an Rpad HTML file are:
Debugging hint: the dojo.js that is packaged with Rpad is an optimized (compressed) version. To debug errors in the Javascript code using e.g. Firebug, it is easier to use a non-compressed dojo.js. This can be built by setting layerOptimize: false in app.profile.js and then building Dojo as outlined in the README (you will need the complete Dojo source distribution). Then, place the un-optimized dojo.js in your working directory and start Rpad; this new dojo.js will take precedence over the one installed with the package.
Here is an example of a complete Rpad HTML file:
<html>
<head>
<title>GUI Examples</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<script type="text/javascript">
rpadConfig = {
gui: "alternate",
rpadHideSource: true
};
</script>
<script type="text/javascript" src="gui/Rpad.js"></script>
</head>
<body>
<span contenteditable="false">
<form>
<input type="checkbox" name="isPepperoni">Pepperoni <br/>
<input name="favoriteNumber" rpadType=" Rvariable" value="44">Favorite number<br/>
</form>
</span>
<br/>
<pre dojoType="Rpad rpadRun="init">
HTMLon()
data(state)
select("favoriteAmericanState", state.name) # generate a select box
</pre>
<pre dojoType="Rpad">
cat("isPepperoni=",isPepperoni,"\n")
cat("favoriteAmericanState=",favoriteAmericanState,"\n")
</pre>
</body>
</html>
In Rpad_input
sections, everything must be valid HTML,
so "<-" must be "<-". Also,
<br/> tags are needed for line breaks in div tags (they are
not needed for textarea or pre tags).
Multiple lines of input must be contained within a set of pre tages;
a single line of input can be written without the pre tags.
The Dojo port (>1.1.x) has introduced some incompatibilities at the *.Rpad level relative to version 0.9.6. Basically, here's what is different:
The files in Rpad are layed out as follows on the server:
In Rpad scripts, although you can access files in the main directory (the
directory of the page) with "../../whatever", you are better off
using RpadBaseFile("whatever") to maintain
compatibility with the local version of Rpad. You can access
files in the R process's current directory as you would
normally, but if you want to specify it as a URL for output in
the browser (for a link or an embedded file), use RpadBaseURL("whatever").
In the client/server version, each Rpad page gets its own R process on the server, so it is rather resource intensive. Threading and Duncan Temple Lang's idea of "multiple interpreters" would greatly help reduce the resource usage on the server.
Rpad uses Xmlhttp to communicate between the browser and the server, so browser refreshes are not needed to update data. This is available for both Mozilla and IE. Rpad uses standard HTTP GET or PUT requests, and all data is transmitted as ascii. Xmlhttp allows both synchronous and asynchronous communications. The best implementation (I've tried both) appears to be asynchronous. Synchronous communications can lock up the browser for long periods if the server becomes unavailable, or there's a communications glitch. Asynchronous communication avoids this, but the logic is more contorted internally.
There is no built in security in Rpad. The user has complete access to any command in R and also in the system shell. I consider this a feature, not a bug. For protection, the system needs to be locked down on the server. Write protect any files and databases that are a concern, and lock out access to the server user to other parts of the system.
With the base setup, Rpad users can stomp on each others files. If a user saves a file in the Rpad directory, another user can write over it. To make it more permanent, the user would have to request that the system administrator write protect the file and any data that went with the file.
Because of the relatively lax security, Rpad is best suited for intranets or other relatively controlled situations.
Rpad could be integrated into a more advanced content management system that would better handle multiple users, passwords, and so on.
For notes on server installations, click here.
In the client/server version, each Rpad page gets its own R process on the server. So, multiple users won't interfere with each other. In the local version of Rpad, the browser connects with one R process, so there is more chance of interaction between multiple Rpad pages. Each time the user starts a new page in the client-server version, the local environment is clean. But in the local version of Rpad, this is not true: the local environment may have objects from previous Rpad pages or from interaction at the command line.
There are several differences in directory layouts between the local and client-server versions of Rpad. In the local version, the current working directory of the R process is the directory of the Rpad page. In the client-server version, the current directory of the R process is two levels below the Rpad page (something like /var/www/Rpad/server/ddjieyfewx/ for files with a root of /var/www/Rpad/). In both versions, graphics are created in R's current working directory. But pages may read or write data differently depending on whether in the local or client-server version. See the Rpad functions RpadURL, RpadBaseURL, and RpadBaseFile for convenience utilities to make pages portable between the local version and the client-server version.
In the local version of Rpad, the default graphics device is R's builtin png device. On the client-server version, the default graphics device is the ghostscript-based pngalpha device. Therefore, graphic files may look different between versions. The pngalpha device has the advantage that it is antialiased, you can link to an eps file, and you have more fonts. The disadvantages of the pngalpha device are that you have to have ghostscript installed, and it's slower. On the server side, if you want to use R's png device on unix, you must have X running.