R in Wandora

Revision as of 15:56, 18 July 2011

NOTE: This is an upcoming feature which is not yet included in the release version of Wandora.

Wandora can be used with the R language. R is an environment for statistical computing and graphing. Properties of the topic map and its topics can be accessed from R and statistics and graphs can be generated from them.

Setting up R

To use R in Wandora you need to install R, then install a few R libraries using the package manager inside R and finally possibly adjust some environment parameters in the Wandora startup script. These steps are explained in detail below.

Installing R

Download R from the R website at http://www.r-project.org/ and follow the installation instructions there.

On Linux environments R may also be available using the package repository of your Linux distribution. In Ubuntu the name of the package you need is r-base.

Installing required R libraries

At the very least you must install the rJava library. Do this using the package manager inside R. First run R using the administrator account. On Windows right click the icon and select "Run as Administrator". The installation may have created two icons on your desktop or the start menu, one for 32-bit R and one for 64-bit. You should use the one that matches your Java runtime environment. Note that you might have a 32-bit Java runtime environment even if your Windows is 64-bit.

On Linux run R with root, for example in console using "sudo R".

When installing a package you will be prompted to select a mirror for download. Just select your country or one close to it. To install the package issue the command in R:

 install.packages("rJava")

Most likely you will also want to install the igraph library. It is needed to plot network graphs.

 install.packages("igraph")

Currently Wandora has a problem with the default graphics device in Windows environment. To be able to plot anything in Windows you will need to install the JavaGD graphics device. This is only needed in Windows.

 install.packages("JavaGD")

Setting up enviroment variables

Next make sure that the environment variables are setup correctly in the Wandora startup script. In Windows open the bin/SetR.bat file and in Linux the bin/SetR.sh file. If you did a standard installation of R then the Linux start-up script likely needs no changes at all.

The Windows start-up script however has two things that may need adjusting. Make sure the first line points to you R installation directory. Especially the R version number may need to be changed. Also make sure that the processor architecture matches your Java installation. Note that you may have a 32-bit Java even if your system is 64-bit. If you aren't sure which Java version you have you can simply try both settings and see which one works. The architecture is specified on lines 5 and 6. For 32-bit use

 set R_ARCH=i386
 REM set R_ARCH=x64

And for 64-bit

 REM set R_ARCH=i386
 set R_ARCH=x64

Other parameters should be correct unless you have customized your R installation beyond a standard setup.

You should now be able to use R inside Wandora.

Plotting in Windows

The default graphics device doesn't work correctly in Windows. If you try to plot anything you will get an unresponsive graphics window. If at any time you accidentally open it you can close it cleanly in Wandora R Console with

 dev.off()

To work around this issue you need to use the JavaGD graphics device. You first need to load the JavaGD library with

 library("JavaGD")

Then initialize the graphics device with

 JavaGD()

This will open an empty graphics window. You can then use plot normally to plot in this window.

R console in Wandora

You can open the R console in Wandora by clicking the R console button in the top toolbar. Assuming that you have installed R and setup the environment correctly you will get the standard R greeting with R version and license information.

 R version 2.11.1 (2010-05-31)
 Copyright (C) 2010 The R Foundation for Statistical Computing
 ISBN 3-900051-07-0
 
 R is free software and comes with ABSOLUTELY NO WARRANTY.
 You are welcome to redistribute it under certain conditions.
 Type 'license()' or 'licence()' for distribution details.
 
   Natural language support but running in an English locale
 
 R is a collaborative project with many contributors.
 Type 'contributors()' for more information and
 'citation()' on how to cite R or R packages in publications.
 
 Type 'demo()' for some demos, 'help()' for on-line help, or
 'help.start()' for an HTML browser interface to help.
 Type 'q()' to quit R.
 
 >

Otherwise you'll get an error message and instructions about how to setup your R environment.

You can issue R commands in the text area at the bottom part of the window. This includes almost everything you can do in R, one notable exception is that the help system doesn't work properly so "?plot" and the like don't do anything. Also you shouldn't try to quit the R session with "quit()" or "q()" as this will completely terminate the current process resulting in Wandora being closed as well.

You can browse the topic map in Wandora while having the R console open. This way you can select topics in the main Wandora window and then get references to those topics in the R environment (see next section).

Using R with topic maps in Wandora

There are a couple of ways to access the topic map in R. In each case retrieving information from the topic map relies heavily on the Java topic map API used in Wandora. You will need to call the Java methods of the topic objects. To find out more about the API look at the javadocs of Wandora. Mostly you will only need to look at the Topic and TopicMap classes and a few classes related to them. The Java methods are accessed with the $ indexing operator. For example if the variable t contains a topic you can get the base name of that with

 t$getBaseName()

You can get a reference to the topic map object itself with getTopicMap function in R. Alternatively you can get a list of all the topics in the topic map with getAllTopics or the currently selected topics in Wandora with getContextTopics. For example, to get the base names of the currently selected topics in Wandora use

 lapply(getContextTopics(),function(t) t$getBaseName())

To plot something you first need to gather the data you want to plot. For example, you could plot a histogram that visualizes the amount of associations the topics have in the topic map.

 ts<-getAllTopics() # get a list of all topics
 as<-lapply(ts,function(t) t$getAssociations()$size()) # as has the number of associations in each topic
 fac<-factor(unlist(as)) # make a factor from as
 plot(fac) # plot the factor

In Windows you should open the JavaGD graphics device before the last plot line. Do this with

 library("JavaGD") # loads the JavaGD, only need to do this once per R session
 JavaGD() # opens a JavaGD graphics window

There is also a function to setup a graph object that can be used with the igraph library. use the makeGraphJava function and pass it a list of topic objects. It returns a graph object that can be plot directly. See the igraph R documentation for more information about how to customize the plot. Especially the plot function may be passed parameters relating to the layout of the graph. Before using the makeGraphJava you have to load the igraph library. For example to plot a network of the currently selected topics in a circular layout use the following. And of course you must have selected some topics in Wandora for this to work.

 library("igraph") # loads the library, only need to do this once per R session
 plot(makeGraphJava(getContextTopics()),layout=layout.circle)

Again in Windows you need to remember to use the JavaGD library before plotting.