- Software review
- Open Access
Creating web applications for spatial epidemiological analysis and mapping in R using Rwui
Source Code for Biology and Medicine volume 6, Article number: 6 (2011)
Creating a user friendly web based application which executes an R script allows physicians, epidemiologists, and others unfamiliar with the statistical language to perform powerful statistical analyses easily. The geographic mapping of data is an important tool in spatial epidemiological analysis, and the R project includes many tools for such analyses, but few for visualization. Hence, web applications that run R for epidemiological analysis need to be able to present the results in a geographic format.
Rwui is a web application for creating web based applications for running R scripts. We describe updates to Rwui that enable it to create web applications for R scripts which return the results of the analysis to the web page as geographic maps.
Rwui enables statisticians to create web applications for R scripts without the need to learn web programming. Creating a web application provides users access to an R based analysis without the need to learn R. Recent updates to Rwui have increased its applicability in the field of spatial epidemiological analysis.
Spatial epidemiology combines the geographic mapping of disease distributions with pattern analysis, spatial statistics and disease modelling [1–3]. The statistical language R  is a high-level mathematical scripting language which includes a vast range of pre-programmed functions, and facilitates rapid development of data analysis programs. It contains many functions useful for epidemiological analysis, including three dedicated epidemiological packages Epi  and Epitools  and SpatialEpi .
Statisticians creating epidemiological analyses in R may need to make an analysis available to users who are unfamiliar with the language. A solution is to provide a user-friendly web application for the R script. Values for variables and data files for processing are submitted by the user on a web form. The web application then runs the R script on a server, out of sight of the user, and returns the results of the analysis to the user's web page.
Rwui (R Web User Interface)  is a web application that creates web applications for running R scripts. Code for the web application is generated automatically so that a fully functional web application for an R script can be implemented in a matter of minutes. So statisticians who are unfamiliar with web programming can easily create web applications for running R scripts.
There have been several updates to Rwui since it was first published , permitting the applications created by Rwui to include a number of new features, the most important being:
Applications can be 'daisy-chained', the output of one web application forming the input to another web application.
The results of an analysis can be e-mailed to the user rather than displayed on the web page.
Image maps can be added to graphical output. Adding an image map makes the image 'clickable', so that supplementary information can be displayed according to the spatial coordinates where the image is clicked.
The results of the R analysis can be displayed on a geographic map.
This article describes the last of these new features, namely displaying results on geographic maps. The geographic mapping of data has long been a vital tool in epidemiological analysis. So web applications that run R for epidemiological analyses should be able to present the results in a geographic format. Integrating the Google maps project  into Rwui has made this possible in the web applications that Rwui creates.
Creating web applications with Rwui
The information that Rwui needs in order to create a web application for running an R script is entered on a series of web forms. Using these forms the statistician designs the web application they wish to construct. After entering a title and introductory text for the application, the input items that will appear on the application's web page are selected. Input items may be, for example, Numeric or Text entry boxes, Checkboxes, Drop-down lists, Radio Buttons and File Upload boxes. Figure 1 shows a screenshot of this page of Rwui during the design of an epidemiological example application. Each of the input variables of the R script (i.e those variables that require a value supplied by the user) must have a corresponding input item on the application's web page. Various other options relating to the function and layout of the application being created can then be selected on a further sixteen web forms. Rwui displays a facsimile of the web page that has been created as items are added to the page. After the R script has been uploaded, Rwui generates the web application for the script, which can be downloaded as a zip or tgz file.
Installing web applications created by Rwui
The completed applications will run on a Tomcat server . Tomcat is free and widely used server software, easy to install on both Unix and Windows machines. All that needs to be done to use the downloaded web application is to place the completed application's .war file in the Tomcat server's webapps directory. As well as enabling remote access to applications on a server, Tomcat can be installed on stand-alone machines, in which case the web applications are accessed in a browser on the machine via the 'localhost' URL.
Using web applications created by Rwui
Users of web applications created by Rwui simply enter the information they wish to analyse on the web page via the input items on the page, such as Numeric entry boxes or File Upload boxes, and then press the Analyse button. The information they have entered is sent to the server where the application has been installed and the R script is run on the uploaded information automatically. Once finished, the results are returned to the user's web page. As well as displaying the results on the data entry web page a unique results page is created for each data submission from which the results of the analysis can be downloaded. If the script takes some time to run, the web application can be designed to display progress information for the user and may also include a cancel button if required.
The structure of web applications created by Rwui
The web applications created by Rwui are Java based web applications that use the open source Apache Struts framework . The R script is run using R batch mode. The batch command is placed in a shell script, which is run as a Process using the application's instance of the Runtime class. A Java application has one instance of the Runtime class, which allows the application to interface with the environment in which it is running. The Process class has a method that causes the current thread to wait until the Process has completed. Before the R script is run, the values of the variables that the user entered on the web pages are passed to the R script. The application writes this information, as R assignments, into a text file which is concatenated with the main R script prior to execution.
The application waits for the script to finish and then displays the results on the web page. A uniquely named working directory is created each time the R script is run. To pass results back to the web page, the R script writes results to this directory. The web application, on completion of the R script, displays the files in this directory on the Results page.
Displaying geographic maps in web applications created by Rwui
A web application created by Rwui can display the results of the R analysis as a geographic map, by displaying a static Google map (or maps). A typical application would have the user of the web application uploading a data file. The data is then analysed by the R script on the server. The R script produces a text file of results (eg. called geomap.txt). These results are then displayed for the user on the web page as a geographic map. The format of the text file of results produced by the R script is important. Each line of the results file must contain the name of one valid static Google maps parameter followed by the value for that parameter. Valid parameter names are documented in the Google static maps guide . The parameter name and the parameter value must be separated by an equals (=) sign. An example results file would be:
The above text file of results generated the geographic map seen in Figure 2B.
To include a geographic map when designing a web application with Rwui, it is simply a matter of ticking a checkbox on the appropriate web form asking whether the file to display on the results page is a geographic map, and entering the name of the text file of results that the R script will generate (eg. geomap.txt). The R script which the web application is designed to run must of course include code for generating a file called geomap.txt containing the appropriate parameter name/value pairs to produce the desired geographic map.
An example web application created by Rwui which displays epidemiological information on a geographic map is available at http://sysbio.mrc-bsu.cam.ac.uk/epi_example. The R script is available at http://sysbio.mrc-bsu.cam.ac.uk/epi_example/epi_example.R. Figure 2 shows screenshots of geographic maps from this example application. The application displays data on cholera outbreaks in India between the years 1997 and 2006. This data was taken from a paper by Kanungo et al. . In this simple demonstration application the data to be analysed is held on the server, but in more general use an epidemiological application created by Rwui could upload user data by means of a File upload or Zip-file upload box on the web page. The R script in this example parses the data and performs a very simple data analysis, but in general, besides parsing the data, any of the many statistical analysis methods available in R could be applied to the data prior to display as a geographic map.
Availability and requirements
Project name: Rwui
Project home page: http://sysbio.mrc-bsu.cam.ac.uk/Rwui
Any restrictions to use by non-academics: None
The web applications created by Rwui require:
Operating system(s): Linux or Windows
Java 1.5.0 or higher
Tomcat 5.5 or higher
An R version compatible with the R script
License: GNU GPL for R, and if the Google maps facility is used, its license .
Any restrictions to use by non-academics: If the Google maps facility is used, its terms .
Ostfeld R, Class G, Keesing F: Spatial epidemiology: an emerging (or re-emerging) discipline. Trends in Ecology and Evolution. 2005, 20: 328-336. 10.1016/j.tree.2005.03.009.
Berke O: Exploratory disease mapping: kriging the spatial risk function from regional count data. International Journal of Health Geographics. 2004, 3: 1-11. 10.1186/1476-072X-3-18.
Eisen L, Lozano-Fuentes S: Use of Mapping and Spatial and Space-Time Modeling Approaches in Operational Control of Aedes aegypti and Dengue. PLoS Neglected Tropical Diseases. 2009, 3: 10.1371/journal.pntd.0000411.
R Development Core Team: R: A language and environment for statistical computing. 2004, R Foundation for Statistical Computing, Vienna, Austria, [3-900051-07-0], [http://www.R-project.org]
Carstensen B, Plummer M, Laara E, Hills M: Epi: A package for statistical analysis in epidemiology. [http://cran.r-project.org/web/packages/Epi/index.html]
Aragon T: Epitools: R Package for Epidemiologic Data and Graphics. [http://cran.r-project.org/web/packages/epitools/index.html]
Kim A: SpatialEpi: Performs various spatial epidemiological analyses. [http://cran.r-project.org/web/packages/SpatialEpi/index.html]
Newton R, Wernisch L: Rwui: A web application to create user friendly web interfaces for R scripts. R News. 2007, 7 (2): 32-35.
Google Static Maps API. [http://code.google.com/apis/maps/documentation/staticmaps/]
Apache Tomcat. [http://tomcat.apache.org/]
Apache Struts. [http://struts.apache.org/]
Kanungo S, Sah B, Lopez A, Sung J, Paisley A, Sur D, Clemens J, Balakrish Nair G: Cholera in India: an analysis of reports, 1997-2006. Bull World Health Organ. 2010, 88: 185-191. 10.2471/BLT.09.073460.
Google Maps/Google Earth APIs Terms of Service. [http://code.google.com/apis/maps/terms.html]
AD was funded by the Community Medicine Program at the University of British Columbia, Canada.
The authors declare that they have no competing interests.
RN and LW designed and programmed Rwui. AD contributed the concept of the geographic mapping facility and to its design. All authors read and approved the final manuscript.
About this article
Cite this article
Newton, R., Deonarine, A. & Wernisch, L. Creating web applications for spatial epidemiological analysis and mapping in R using Rwui. Source Code Biol Med 6, 6 (2011). https://doi.org/10.1186/1751-0473-6-6
- Text File
- Epidemiological Analysis
- Result Page
- Input Item
- Geographic Format