CallingR

Calling R from GAMA models

Introduction

The R language is a powerful tool for statistical computing and graphics, and its community is very large in the world (See the website). Adding a support for the R language is one of our strong endeavors to accelerate many statistical and data mining tools integration into the GAMA platform.

Table of contents

• Introduction
• Configuration in GAMA
• Calling R from GAML
  • Before computation
  • Computation
    • Evaluate an R expression
    • Evaluate an R script
    • Convert GAMA object to R object
    • Convert a species to a dataframe

Configuration in GAMA

1. Install R on your computer: please refer to the R official website, or to RStudio if you want in addition a nice IDE.

2. Before running this model, you should install the rJava library in R. In the R (RStudio) console, write: install.packages("rJava") to install the library. To check that the install is correct, you load the library using library(rJava) (in the R console). If no error message appears, it means the installation is correct.

3. In case of trouble:

   • On MacOSX, in recent versions you should first write in a terminal:

   R CMD javareconf
   sudo ln -f -s $(/usr/libexec/java_home)/jre/lib/server/libjvm.dylib /usr/local/lib
   

   • For linux, make sure you have the default-jdk and default-jre packages installed and then execute the command sudo R CMD javareconf

4. You need to Configure the Environment Variable R_HOME (the procedure depends on your OS).

   • On Windows,
   • On Linux, by default it should be /usr/lib/R, you can thus just append the line R_HOME=/usr/lib/R to your /etc/environment file and reboot your computer
   • On macOS, you need to create (or update) the file environment.plist in the folder: ~/Library/LaunchAgents/ (for the current user, note that this folder is a hidden folder) or in /Library/LaunchAgents/ (for all users) It should look like:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>my.startup</string>
    <key>ProgramArguments</key>
    <array>
      <string>sh</string>
      <string>-c</string>
      <string> launchctl setenv R_HOME /Library/Frameworks/R.framework/Resources/ </string>
    </array>
    <key>RunAtLoad</key>
    <true/>
  </dict>
</plist>

5. From GAMA 1.8.2, you need to specify the path to the R connector library in the GAMA launching arguments. To this purpose, you need to add to either (1) the GAMA.ini file if you use the release version of GAMA, or (2) the launching configuration (if you use the source code version) the following line: (replace PATH_TO_R by the path to R, i.e. the value in $R_HOME):
   • on macOS: -Djava.library.path=PATH_TO_R/library/rJava/jri/rlibjri.jnilib
   • on Windows: -Djava.library.path=PATH_TO_R/library/rJava/jri/jri.dll
   • on Linux: -Djava.library.path=PATH_TO_R/library/rJava/jri/

As an example, under macOS, you need to add:

-Djava.library.path=/Library/Frameworks/R.framework/Resources/library/rJava/jri/

Calling R from GAML

Before computation

Any agent aiming at using R for some computation needs to be provided with the RSkill.

Before calling any computation, this agent needs to start a connection with the R software.

As an example, if we want that the global agent can use R, we need to have the following minimal model:

global skills: [RSkill] {
   init {
      do startR;
   }
}

Computation

Evaluate an R expression

The R_eval operator can be used to evaluate any R expression. It can also be used to initialize a variable or call any function. It can return any data type (depending on the R output). As in an R session, the various evaluations are dependent on the previous ones.

Example:

global skills: [RSkill] {
	
	init{
		do startR;
		
		write R_eval("x<-1");
		write R_eval("rnorm(50,0,5)");
	}

}

Evaluate an R script

To evaluate an R script, stored in a (text) file, open the file and execute each of its lines.

global skills:[RSkill]{
	file Rcode <- text_file("../includes/rScript.txt");
		init{
		do startR;
		// Loop that takes each line of the R script and execute it.
	 	loop s over: Rcode.contents{
			unknown a <- R_eval(s);
			write "R>"+s;
			write a;
		}
	}
}

Convert GAMA object to R object

To use GAMA complex objects into R functions, we need to transform them using the to_R_data operator: it transforms any GAMA object into a R object.

global skills:[RSkill] {
	init {
		do startR();
		
		string s2 <- "s2";
		list<int> numlist <- [1,2,3,4]; 
  		write R_eval("numlist = " + to_R_data(numlist));
	}
}

Convert a species to a dataframe

Dataframe is a powerful R data type allowing to ease data manipulation... Dataframe wan of course be defined at hand using R commands. But GAML provides the to_R_dataframe operator to directly transform a species of agents into a dataframe for future analysis.

global skills: [RSkill] {
	
	init{
		do startR();
		
		create people number: 10;
		
		do R_eval("df<-" + to_R_dataframe(people));
		write R_eval("df");
		write R_eval("df$flipCoin");	
	}
}
species people {
	bool flipCoin <- flip(0.5);
}