Quick tour in Rwui


Contents

A PDF version of this help can be found here: quick_tour.pdf.

1 The problem

Suppose you have an R script that reads in a simple table, for example

 X1    X2    X3
1.745 1.18  4.428
0.512 0.46  4.666
0.864 0.167 4.202
...
and produces a boxplot and provides some summary statistics, such as the mean and standard deviation for each column of the table. You want to make this analysis tool available on the web to other users by providing a simple web interface for uploading data, analysing them with the R script, and displaying the results. The next few sections will show you how simple this is using the web application Rwui.

No programming skills, not even for HTML, are required (beyond R programming obviously). The only potential hurdle is the need to install a webserver like Tomcat, which isn't too difficult either.

2 The R script

Here is a short R program that produces boxplots and summaries of a table stored in an input file whose name is stored in an R variable called fileName.

dt <- matrix(scan(fileName,skip=1), ncol=3)
cat("mean ",apply(dt,2,mean),"\n",file="summary.txt")
cat("sd ",apply(dt,2,sd),"\n",file="summary.txt",append=TRUE)

png(filename = "box.png")
boxplot(dt)
dev.off()

## png() may sometimes not work depending on the system. 
## bitmap() is more reliable in this instance (requires Ghostscript)
# bitmap(file="box.png") 
# boxplot(dt) 
# dev2bitmap(file="box.png") 
# dev.off()

It writes the results to a textfile summary.txt and plots a boxplot in file box.png. We would like to generate a web application that allows us to upload the input file and displays the results files and makes them available for download.

3 Creating the web application with Rwui

NB. This Quick Tour covers the main pages of Rwui. You will encounter a number of extra pages not referred to in the text, but these can be clicked through and ignored during this introductory tour.

3.1 Step one: Choose a project name and project description

First choose a short description that will appear at the top of the web browser, for example, Summary of table

Image welcome


Later we discuss how to use a previous application description file, for now we move on to the next page by clicking Enter.

On this next page a short project description can be provided, for example,

This is a simple program to display summary statistics and boxplots 
for a user provided ASCII file containing a spreadsheet

Image intro

3.2 Step two: Add a file upload button

Note how the bottom part of the web page shows the current layout of your future website.

Choose the File Upload Box from the selection.


Image filebutton

3.3 Step three: Define a variable

The new application needs to link the name of the file a user will upload using the File Upload Box, with the R script. Here is the line in the R script reading the input file:

dt <- matrix(scan(fileName,skip=1), ncol=3)
...

So the R script wants the name of the file a user uploads to be stored in the variable fileName. Hence we declare the variable fileName as the variable for the uploaded file and add some explanation of the purpose of the file. For example,

 
The file should contain numerical data in ASCII format, numbers in a
row separated by spaces and rows separated by newlines

Image filevariable


The current website looks quite respectable already, judging from the display in the lower part of the current page.

Image variableresult


We finish the variable definitions by clicking Finished composing page. We want to keep validation so we just press Enter on the next page, which brings us to the next page, where we enter a short name for the application (without spaces or other fancy characters!), for example, just summary.

Image applicationname

3.4 Step four: Define output files

We need to get the result to the future user somehow. Inspection of our R program

...
cat("mean ",apply(dt,2,mean),"\n",file="summary.txt")
...
png(filename = "box.png")
...
shows that we are writing to a summary file summary.txt and a plot file box.png. We want these two files visible to the user after the analysis and specify them on the next two Rwui pages:

Image summaryfile

Image boxfile


Pressing Finished entering filenames brings us to the next page. We don't need to display any progress information because this simple script won't take long to run, so don't tick the box and just press Enter.

3.5 Step five: Uploading the R script

We are almost done now. We just need to upload the R script file. For this purpose save the following R script to a file summary.R.

dt <- matrix(scan(fileName,skip=1), ncol=3)
cat("mean ",apply(dt,2,mean),"\n",file="summary.txt")
cat("sd ",apply(dt,2,sd),"\n",file="summary.txt",append=TRUE)

png(filename = "box.png")
boxplot(dt)
dev.off()

## png() may sometimes not work depending on the system. 
## bitmap() is more reliable in this instance (requires Ghostscript)
# bitmap(file="box.png") 
# boxplot(dt) 
# dev2bitmap(file="box.png") 
# dev.off()

and upload it.

We don't want to include an initial password protected Login page for this application, so leave the default option of `No Login page' selected and press Enter.

3.6 Step six: Creating and downloading the web application

On the next page click Create web application and keep fingers crossed that everything works out fine while Rwui is generating and preparing all the necessary files for download.

Image completed


This is a good opportunity to check whether everything looks fine: for example, whether all the results files which should be displayed are listed in the right hand part of the page.

If changes need to be made to the current application this is always easy: just press the Rwui back button until reaching the page where the change needs to be made. This is true at any stage of the process, the Rwui back button (not the browser back button!) can be pressed any time to get back to an earlier stage.

Once Rwui has created the application, save the generated summary.tgz or summary.zip file somewhere on your computer and untar or unzip it. For example under Unix use

gunzip -c summary.tgz | tar xv

(under Windows you might want to use the summary.zip file and use an extraction tool). This generates a new directory summary containing the complete application including Java source code and, the important bit, a web application file, called in our case summary.war.

3.7 Step seven: Deploy the application

We are almost done now. For the last step you need a Tomcat installation up and running. Test Tomcat by typing:

http://localhost:8080

in your webbrowser. If you have Tomcat freshly installed you will see something like:

Image tomcat


The last step is to deploy your application to your Tomcat directory. This is as simple as copying the file summary/deploy/summary.war to the Tomcat webapps directory, where Tomcat will automatically unpack and incorporate it. In my case I have to write

cp ~/tmp/summary/deploy/summary.war ~/software/tomcat/webapps/

Have a look into the webapps directory whether Tomcat has expanded the summary.war file into a summary directory.

If you now enter the address

http://localhost:8080/summary

in your webbrowser, you should, with a bit of luck, see the start page of the new application.

Image summary

4 Using the application for analysing data

To create some test data, save the following data in a file test.dat

  X1     X2    X3
 1.745  1.18  4.428
 0.512  0.46  4.666
 0.864  0.167 4.202
-0.498  0.781 4.496
-0.153  0.588 3.194
 0.591  1.794 4.682
 1.653  0.563 5.392
-0.847  1.624 5.628
 0.054  1.149 6.951
-0.257  1.521 5.871

and upload them in your new application. Analyse the data by pressing Analyse. You can analyse as many data files as you want, one at a time, and the results will all be available in a list.

Image results


Clicking on a result gets you to a page displaying the contents of the results files we specified when creating the application (summary.txt and box.png), for the respective data file.

Image result


Well done! It's now time to consider making some of your wonderful R analysis scripts available to a wider community by providing them with an easy to use web interface, created using Rwui.


5 Modifying a previous application

In the distribution directory summary created from summary.tgz you will find the file summary.xml which should be kept in a safe place. If everything else is lost it will always allow you to go back to Rwui and recreate the application from scratch. An application can also be easily modified or expanded using this XML description of the application.

Suppose we wanted to change the application so that a density plot is shown as well. First we modify our R script slightly, summary2.R.

dt <- matrix(scan(fileName,skip=1), ncol=3)
cat("mean ",apply(dt,2,mean),"\n",file="summary.txt")
cat("sd ",apply(dt,2,sd),"\n",file="summary.txt",append=TRUE)

png(filename = "box.png")
boxplot(dt)
dev.off()

png(filename = "density.png")
plot(density(as.matrix(dt)))
dev.off()

Using the summary.xml file, it is trivial to upgrade your application without too much pain. Call Rwui again http://sysbio.mrc-bsu.cam.ac.uk/Rwui and upload the summary.xml description file of your application.

Work your way through Rwui; as long as you only press the Enter or the Finished ... buttons no changes will be made to your application. We stop at the page for results files and enter the name of the new file density.png.

Image updatedensity


On the right hand side of the page you'll see the new file added to the current list of results files to be displayed. Click Finished entering filenames and press Enter until reaching the R script upload page, where you enter the new file summary2.R. Create and download the application, untar/unzip it, copy the new summary.war into the webapps directory just as before. When analysing the data and looking at the result you should now see the new plot added

Image densityplot



richard newton 2007-08-13