# Plugin R

This Wiki Plugin provides an interface to run R scripts through web pages.

PluginR allows basic and direct usage, writing the script between the PluginR tags (see below), but it also allows advanced usage, where Pretty Trackers can be used to make web interfaces to modify the parameters that you want to allow the user to modify before producing the text or graphic output from your scripts. Or you can send full data files to your R script to be processed and get the output automatically on-line a few seconds later. This way, Tiki and PluginR become a nice and collaborative web interface for your custom R scripts.

Is this your first time to R or Tiki?

 New to R?
R is a free software environment for statistical computing and graphics. It compiles and runs on a wide variety of UNIX platforms, Windows and MacOS. R needs to be installed separately in your server for PluginR to work, of course.

 New to Tiki?
Tiki is a Tightly Integrated Knowledge Infrastructure, which allows you to create almost any kind of web environment for your project. As far as R is involved, it allows you to run R scripts in web pages and edit them easily at any time (it's based on a wiki engine). And it also allows you to create web interfaces for your R scripts and packages (you'll see some examples linked below).

To run Tiki you need:
1. A XAMP stack (Linux/Mac/Windows + Apache web server + Mysql database server + PHP programing language). As a reference, see how to install it on a Ubuntu? GNU/Linux here
2. Install Tiki on that server. See: Installation
3. Install PluginR in place, as admin, through the tiki-mods.php interface once inside your own Tiki, or by hand getting the PluginR code from http://mods.tiki.org
4. Have R working in the same server where your Tiki is installed.

In addition, you can apply one of two Tiki Configuration Profiles in http://profiles.tiki.org ready for R and PluginR:
1. r_test: a Profile called r_test to check whether all features are working in your server, and which params might be useful to fine tune the output that you will get from the R scripts you write in your server according to your needs.
http://profiles.tiki.org/r_test
2. R_HeatMaps, to see an example of application used in Bioinformatics to produce HeatMaps through a dynamic web page.
Any user can apply this profile in their tiki installation, and edit it to fit it as interface for their own R scripts with relative ease.
http://profiles.tiki.org/R_HeatMaps
• Some screenshots of the profile after being applied to your tiki site:

## Installation

This plugin is not installed by default in Tiki (it's GPL licensed, while Tiki is LGPL licensed), and it can be obtained from Mods.

You can see the details of the last version here:
http://mods.tiki.org/details.php?type=wikiplugins&mod=r

And you can fetch it from a link like (being X.YY the latest version of the plugin; e.g. 0.70):
http://mods.tiki.org/Dist/wikiplugins-r-X.YY.tgz

See the documentation about Mods to see how to manually install a Mod in your Tiki site.

In its current design, it will only work in Unix-like environments, such as GNU/Linux and others. It comes with two plugin files (wikiplugin_r.php and wikiplugin_rr.php), and one .htaccess file to allow writing .png files (for charts and figures) at the ./temp folder in tiki.

Additionally, you might want to install the "geshi" program in your tiki file tree (as explained in PluginCode ), so that you can get color highlighting when documenting bits of R syntax inside PluginCode calls. Since Tiki7 you can alternatively enable the feature "Syntax highlighting" (codemirror) bundled within Tiki in order to get this result and also syntax highlighting while in edit mode. See Syntax Highlighter

### Requirements

The R package and imagemagick installed in the server. On GNU/Linux and similar systems, you can install the base packages with something like:
sudo apt-get install r-base r-base-dev r-recommended imagemagick

or
yum install R R-devel R-lattice imagemagick

depending on the GNU/Linux distribution that you use.

If you see an error message saying something about an error when attempting to convert..., then you need to ensure that you installed the system package imagemagick, that will be needed for image conversion server side in R.

Once all requirements are installed, you can start the R console in a terminal by typing "R".

You might need some extra R packages in your R installation, depending on the type of analysis that you want R to perform for you.

For instance, depending on which R pacjages you want to use, you might need to install these system packages additionally, in order to have the other specific packages working (from debian GNU/Linux system, or similar name under other GNU/Linux distributions)
In Ubuntu 10.04 LTS Server
sudo apt-get install r-cran-rgl r-cran-misc3d libx11-dev libxt-dev libcurl4-gnutls-dev libxml2-dev r-cran-xml libgraphviz4 libcairo2-dev r-cran-cairodevice freeglut3 freeglut3-dev

In Ubuntu 12.04 LTS Server
sudo apt-get install r-cran-rgl r-cran-misc3d libx11-dev libxt-dev libcurl4-gnutls-dev libxml2-dev r-cran-xml libgraphviz-dev libcairo2-dev r-cran-cairodevice freeglut3 freeglut3-dev r-cran-rglpk

Of course you can use some nice GUI programs on top of R, like the nice multiplatform RStudio (http://www.rstudio.net), or others.

For MS Windows-based OS, you need to ensure that you have imagemagick successfully installed in your system. See these urls for help:

## Usage and Parameters

To use this plugin in a wiki page, use the syntax:
Syntax for the R plugin
{R()} your R script here {R}

or

Syntax for the R plugin
{RR()} your R script here which might use some potentially dangerous commands in the server, once that plugin call is validated by an admin{RR}

### Plugin R vs Plugin RR

Since version 0.5.1 from this mod, you can use plugin rr to execute as admin unsafe commands: you will be required admin validation of those plugin calls.

With plugin r, you will not be requested plugin validation, instead, but unsafe commands will be blocked.

### Parameters

You can add some optional parameters to the PluginR call:

Parameter Accepted values Default Effect Required? Since PluginR
echo int 0 Show a code block with the R commands to be run before running them (similarly to the echo command) n 0,78
caption alpha R/RR code Code snippet label. n 0,78
wrap int 1 Enable word wrapping on the code to avoid breaking the layout. n 0,78
colors int r Syntax highlighting with colors. Available: php, html, sql, javascript, css, java, c, doxygen, delphi, rsplus.... n 0,78
ln int R/RR code Show line numbers for each line of code. n 0,78
wikisyntax int 0 Choose whether the output should be parsed as wiki syntax (Optional). Options: 0 (no parsing, default), 1 (parsing) n 0,4
width int none Width of the graph (Optional). Options: an integer number in pixels (default) or in units specified. If ommitted but height is set, width will be proportional to keep aspect ratio n 0,4
height int none Height of the graph (Optional). Options: an integer number in inches (default) or in units specified. If ommitted but width is set, height will be proportional to keep aspect ratio n 0,4
units alpha px Choose units for the width and/or height parameters (Optional). Options: px (default) for pixels, in (inches), cm or mm n 0,4
pointsize int 12 The default pointsize of plotted text, interpreted as big points (1/72 inch) at res dpi (optional). Options: interger number such as 12 or bigger n 0,4
bg any string except for HTML and PHP tags transparent The initial background colour (optional). Options: white, yellow, grey, ... and transparent n 0,4
res int 72 The nominal resolution in dpi which will be recorded in the bitmap file (if any). Also used for units other than the default, and to convert points to pixels (Optional). Options: a positive integer (default: 72 dpi). Values higher than 150 usually seem to be too much n 0,4
svg int 0 Show link for the creation of the SVG version of the plot. Options: 0 (do not create it, default), 1 (create it). Requires R Cairo pakage, which can be checked with the following command in the R console: capabilities() n 0.70
pdf int 0 Show link for the creation of the PDF version of the plot. Options: 0 (do not create it, default), 1 (create it). Requires R Cairo pakage, which can be checked with the following command in the R console: capabilities() n 0.70
onefile FALSE/TRUE TRUE should all plots appear in one file? This would be the default value; but if you answer no, they will attempt to appear in separate files in the server, even if you currently will not be able to fetch them easily through the internet browser. This param can be used with figure types svg and pdf; however, not many svg viewers support several plots in one svg file n 0.70
loadandsave int 0 Choose whether the call to the PluginR should attempt first to load any previous workspace data (.RData) for that wiki page or tracker itemId (if using Pretty Trackers), and save the workspace again at the end before closing the R session. ex: 0. (default), 1 to load the R workspace at the beginning and save it again at the end. n 0,61.
x11 int 1 Choose whether the server can use X11 to produce graphs in R, or alternatively use dev2bitmap instead (Optional). Options: 1 (R has support for X11, default), 0 (no support for X11 thus using dev2bitmap). These capabilities can be checked in the server with the command in the R console: capabilities() n 0,4
attId int none AttId from a tracker Item attachment. ex: 1. (Optional) n 0,1
type any string except for HTML and PHP tags none Choose the source file type in the appropriate mimetype syntax (Optional). Options: text/csv|text/xml. ex: text/csv. (default). For text/xml, you need to have installed library ("R4X") in R at the server. See documentation for more details n 0,1
onefile int 1 Should all plots appear in one file? This is the default value (1); but if you answer no, they will attempt to appear in separate files in the server, even if you currently will not be able to fetch them easily through the internet browser. This param can be used with figure types svg and pdf; however, not many svg viewers support several plots in one svg file n 0.71
removen int 0 Remove the extra \n tags generated by some R packages out of the user control (such as with charts generated through GoogleVis R package). Options: 0 (do not remove \n tags, default), 1 (remove them all) n 0.76
security int 1 Set the security level for the R commands allowed by the plugin. ex: 1. (default), 0 for no security checking. n 0,4. Since 0.5.1, this param is not allowed, and all plugin R calls are checked against unsafe commands, which are blocked by default. To use unsafe commands, user the sister plugin rr.

### Display several graphs in the same Plugin R call

Since PluginR version 0.72, a user can create and display several png's within the same PluginR call, provided that the user writes

# newgraph

before the new graph so that pluginR opens up the required new graphic device.

### Set a CRAN mirror in your R call

You can setup a CRAN mirror in your R call at the wiki page level, by means of using this code:
r <- getOption("repos")
r["CRAN"] <- "http://ftp.heanet.ie/mirrors/cran.r-project.org/"
options(repos=r)

Replace "http://ftp.heanet.ie/mirrors/cran.r-project.org/" with your local CRAN mirror.

## Examples

### 1. Example 1: simple command

Direct output
This code,
{R()}1:25{R}

Would produce:
Quote:
[1] 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

### 2. Example 2: a simple graph

{R()}
x <- 1:10;
y <- (1:10)^2;
plot(x,y);
{R}

### 3. Example 3

Opening a file from a tracker item attachment and let the R script use it, showing the output in the wiki page.

http://www.geography.uoregon.edu/GeogR/topics/examplesession.htm

Get this file sumcr.csv as example:
http://www.geography.uoregon.edu/GeogR/data/csv/sumcr.csv

When opened in a text editor, it should look like (with 89 lines, instead of just those following 4):
Location,Reach,HU,CumLen,Length,DepthWS,WidthWS,WidthBF,HUAreaWS,HUAreaBF,wsgrad
HUA-1,A,R,9.20,9.20,0.12,4.10,9.00,37.72,82.80,0.008696
HUA-2,A,G,29.70,20.50,0.21,3.98,9.63,81.66,197.48,0.002927
HUA-3,A,R,51.20,21.50,0.10,4.46,11.43,95.83,245.75,0.001395
...

Upload this file as an attachment to a Tracker item.

#### 3.1. 3a: attId hardcoded

Create a wiki page with a call to the PluginR, setting the attId in the appropriate param of the plugin.
In this example, let's say that the attId is number 2.

attId=2. csv file with csv extension. data separated with commas

{R(attId=2)}summary(data)
{R}

The data in that csv file has been assigned to the variable data in the pluginR.
Thus, summary(data) will produce the summary of the variables and data included in that csv file.

Output produced:
Location  Reach  HU         CumLen          Length          DepthWS
HUA-1  : 1   A:20   G:27   Min.   :  9.2   Min.   : 1.800   Min.   :0.0900
HUA-10 : 1   B:46   P:22   1st Qu.:234.6   1st Qu.: 5.675   1st Qu.:0.1500
HUA-11 : 1   C:22   R:39   Median :454.8   Median : 8.800   Median :0.2000
HUA-12 : 1                 Mean   :440.0   Mean   : 9.953   Mean   :0.2208
HUA-13 : 1                 3rd Qu.:616.9   3rd Qu.:13.000   3rd Qu.:0.2700
HUA-14 : 1                 Max.   :835.0   Max.   :27.300   Max.   :0.5100
(Other):82
WidthWS         WidthBF          HUAreaWS        HUAreaBF
Min.   :1.160   Min.   : 3.700   Min.   : 4.95   Min.   : 13.32
1st Qu.:2.520   1st Qu.: 7.253   1st Qu.:15.78   1st Qu.: 51.18
Median :3.065   Median : 8.700   Median :28.62   Median : 77.70
Mean   :3.159   Mean   : 8.929   Mean   :31.89   Mean   : 89.43
3rd Qu.:3.862   3rd Qu.:10.312   3rd Qu.:38.66   3rd Qu.:110.95
Max.   :5.300   Max.   :19.300   Max.   :95.83   Max.   :295.00

Min.   :-4.091e-02
1st Qu.:-2.925e-05
Median : 7.549e-03
Mean   : 8.769e-03
3rd Qu.: 1.465e-02
Max.   : 7.100e-02

#### 3.2. 3b: attId dynamically referenced

A page A with a PluginTrackerList lists items from a tracker with the param link=y. The url param has to be like: url="tiki-index.php?page=B&itemId", where B here stands for the wiki page containing the plugin R call.

When the users click on the link of an item, they are sent to wiki page B, with an url containing the Id number of that traker item selected. PluginR gets then the attachment id of that tracker item, in order to use it to populate the variable "data".

The syntax, in this other example, is as follows:

{R(attId)}summary(data)
{R}

The same output should be produced as in the previous example 2a.

However, right now, if there is not itemId passed through the url, the R plugin runs and shows some output error on the wiki page.

To see this example in action, install the Profile http://profiles.tiki.org/r_test

### 4. Example 4: producing graphs

{R(attId=2)}
x <- t(data[4]);
y <- t(data[5]);
plot(x,y);
{R}

### 5. Example 5: adding params to the graphs

To see this example in action, install the Profile http://profiles.tikiwiki.org/r_test

res 72 dpi

#### 5.1. Using default: res 72, pointsize 12,

Width 500px and rest by default: res 72, pointsize 12, bg "transparent"

This code:
^{R(width=500)}data(cars)
plot( cars$dist ~ cars$speed )
title('By default, res 72, pointsize 12,\n bg transparent')
m <- lm( cars$dist ~ cars$speed )
k <- coef(m)
curve( k[1] + k[2]*x , from=min(cars$speed) , to=max(cars$speed) , add=TRUE ){R}^

Produces:

res 120 dpi

#### 5.2. res 120 & pointsize 12 & bg yellow

If not pointsize is set, default value (12) is used.

This code:
^{R(width=500 res=120 units=px bg=yellow)}data(cars)
plot( cars$dist ~ cars$speed )
title('res 120 & pointsize 12 \n bg yellow')
m <- lm( cars$dist ~ cars$speed )
k <- coef(m)
curve( k[1] + k[2]*x , from=min(cars$speed) , to=max(cars$speed) , add=TRUE ){R}^

Produces:

#### 5.3. res 72 & pointsize 16

This code:
^{R(width=500 res=72 pointsize=16 units=px)}data(cars)
plot( cars$dist ~ cars$speed )
title('res 72 \n pointsize 16')
m <- lm( cars$dist ~ cars$speed )
k <- coef(m)
curve( k[1] + k[2]*x , from=min(cars$speed) , to=max(cars$speed) , add=TRUE ){R}^

Produces:

#### 5.4. res 120 & pointsize 16

This code:
^{R(width=500 res=120 pointsize=16 units=px)}data(cars)
plot( cars$dist ~ cars$speed )
title('res 120 \n pointsize 16')
m <- lm( cars$dist ~ cars$speed )
k <- coef(m)
curve( k[1] + k[2]*x , from=min(cars$speed) , to=max(cars$speed) , add=TRUE ){R}^

Produces:

### 6. Example 6: edit R params through Pretty Trackers

What are "Pretty Trackers" in the Tiki context?

And to see this example in action, for the time being, install the Profile http://profiles.tikiwiki.org/r_test

### 7. Example 7: showing results in html

#### 7.1. Using html tags

This code:
{R()}print("<b>hello</b>"){R}

Produces:

[1] "hello"

#### 7.2. Using wikisyntax param: no param set

This code:
{R()}print("__hello__"){R}

Produces:

[1] "__hello__"

#### 7.3. Using wikisyntax param set to 0

This code:
{R(wikisyntax=>0)}print("__hello__"){R}

Produces:

[1] "__hello__"

#### 7.4. Using wikisyntax param set to 1

This code:
{R(wikisyntax=>1)}print("__hello__"){R}

Produces:

1 "hello"

### 8. Example 8: using potentially dangerous commands

As an admin you can execute any R command to the server. Just plugin rr instead, and validate your plugin calls as needed.

Normal users don't have the ability to validate plugin calls, so that they can only execute safe R commands in the server.

By default Plugin R runs in --vanilla mode, so that no workspace is loaded at the beginning nor saved at the end, and no human intervention is expected to run the R commands, nor echo's from the R console are printed.

However, for some use cases, you may need to save the R objects and data from your session (call to PluginR) and re-use it afterwards in a new PluginR call, in the same wiki page or others.

#### 9.1. In the same wiki page

If you have more than one call to PluginR in the same wiki page, you can use the param. loadandsave to force R to load any existing workspace data for that wiki page and save it at the end again.

For instance, for a Wiki page called "My Test", you would have your workspace data stored in your server at:

./temp/cache/My_Test/.RData

Note that spaces in names are replaced by the underscore sign ("_"). Therefore, the equivalent page with name "My_Test" (with the underscore instead of the space) would be using the same workspace data.

Example:

#### 9.2. Across diferent wiki pages

In this case, we assume that all wiki pages involved in your R calls are a set of scripts that can be run for multiple analysis on one or more of your r scripts. This way, we'll use the Trackers feature, which will serve as a database engine to keep track of all our analysis projects, with the addition to keep the same workspace data among all pages related to the same project.

Therefore, as far as the itemId param is used in the urls sent between wiki pages (by means of PluginTrackerList, or other tracker-related plugins), the same workspace will be used even if different wiki pages are involved.

Workspace data is stored under the ./temp/cache/ directory. E.g., for project with itemId 33, the workspace will be saved at:
./temp/cache/_itemid_000033/.RData

## Current limitations

1. When you use PluginR combined with PrettyTrackers for advanced reporting somehow similar to what you can achieve with "Sweave & latex" (e.g. using Smarty templates in Tiki):
• angle brackets (i.e.: { lines of code } ) have to surrounded by smarty "literal" tags. For instance, in order to get this if clause working in a smarty template:
if (a == 0) {
# line 1 of R code
# line 2 of R code...
}

you have to use this code:
if (a == 0) {literal} { {/literal}
# line 1 of R code
# line 2 of R code...
{literal} } {/literal}
2. Installation of R packages in a server behind a proxy needs the user to export the environment variables for the proxy previous to any action attempting to connect to internet (installing r packages, etc).
• You can alternatively install whatever R packages you need through a standard console/ssh (by yourself or after requesting it to the sysadmin in your server), after adding the proxy info to the Renviron file in your operating system.
You can also try adding this type of line at the beginning of your R script:
Sys.setenv(http_proxy="http://your_proxy_url:8080")

Former limitations fixed
There were some former limitations when using R code in smarty syntax through wiki pages as templates for PluginTrackerList:
• double parenthesis parsed as internal or alias links,
• square brackets parsed as external links,
• double pipes for OR.

But these one have been fixed by using a new param created in PluginTrackerList in Tiki 6.4 and Tiki 7.1:
• param "tplwiki"
which prevents parsing of R code by smarty: only {$f_1} type of fields are converted into their equivalent data from the corresponding field 1, etc. ## Tips Some useful tips for advanced usage: 1. When using PluginTrackerList calls, remember to keep param showlinks="0" to rpevent that Main tracker fields (those who will be linked to the tracker item) are rendered as html links, which R would not like in many cases. 2. When using tracker fields of type "textarea" (lets say for tracker field 1 ({$f_1})), and attempting to show them in a command like remember to surround the tracker field reference with double quottation, like:
cat("{$f_1}") because if you have more than one line, if you don't surround that field with double quotation marks, R doesn't know that the next line is still from the previous "cat" command. 3. smarty language function capture can be very handy to add smarty logic based on some values of a tracker item field. Example: {capture name='saveas'}{$f_46}{/capture}
{if $smarty.capture.saveas eq "PDF"} {wikiplugin _name=rr loadandsave=1 pdf=1 svg=0} cat("f_46 is {$f_46}");
# Do your stuff here with pdf button generation...
{/wikiplugin}
{elseif $smarty.capture.saveas eq "SVG"} {wikiplugin _name=rr loadandsave=1 pdf=0 svg=1} cat("f_46 is {$f_46}");
# Do your stuff here with svg button generation...
{/wikiplugin}
{else}
cat("f_46 is {\$f_46}");
# Do your stuff here with no pdf nor svg buttons...
{/wikiplugin}
{/if}
4. To create and display several png's in the same PluginR call, write
# newgraph

before the new graph so that pluginR opens up the required new graphic device.
5. When using data in R from file attachments to tracker items, you can use the following R session variables to display that content, if desired, from R
• file_type for filetype
• data_file for path and file name (usually in tmp folder on disk when used by php),
• data for the contents of that file

## External sources of information

See it also here with the JQuery S5 slideshow engine here:
http://ueb.vhir.org/tools/2011+UseR

### Blogs

See the blogs from developers of PluginR:

### Publications

There are some publications/communications already based on the usage on Tiki & PluginR in different scientific fields:

• 2012. "Deploying a tools website in a Bioinformatics unit with Tiki & PluginR". de Pedro, X.; Briansó, F.; Sánchez. A. XIth Spanish Symposium on Bioinformatics (JBI2012). Spanish Institut of Bioinformatics and the Portuguese Bioinformatics Network and hosted by the Barcelona Biomedical Research Park (PRBB). Barcelona, Catalonia, Spain. January 23-25. PDF:

• 2011. "Web 2.0 for R scripts & workflows: Tiki & PluginR". Xavier de Pedro & Àlex Sánchez. The R User Conference 2011. University of Warwick, Coventry, UK. August 16-18th. http://ueb.vhir.org/2011+UseR

• 2010. "Usando de forma segura R vía web con Tiki". Xavier de Pedro y Àlex Sánchez. I Congreso de usuarios de R (II Jornadas). Mieres (Oviedo, España). 1-2 de Diciembre de 2010. PDF (in Spanish):

• 2010. "Assessing Student Activity Through Log Analysis From Computer Supported Learning Assignments". X. de Pedro, M. Calvo, A. Carnicer, J. Cuadros, A. Miñarro. In International Congress of University Teaching and Innovation - CIDUI 2010, Barcelona July 2010. http://cochise.bib.ub.es http://cochise.seeds4c.org

alias
Plugin R | PluginRR | Plugin RR | R

### Keywords

These keywords serve as "hubs" for navigation within the Tiki documentation. They correspond to development keywords (bug reports and feature requests):