Welcome to Rincanter!

About

Rincanter is a Clojure and Incanter wrapper around the Rosuda JRIEngine Java/R bridge. The hope is to allow easy access to an embedded R engine from Incanter. It also offers translation between Clojure and Incanter datatypes and R datatypes such as R dataframe to Incanter dataset.

Installation

Install Leiningen

Rincanter uses Leiningen (currently using version 2) to manage its dependencies on Clojure, Incanter, and Rosuda JRI components. You will need to install Leiningen following the instructions on its project page.

Install R for your platform

The directions for installing R are outside the scope of this document, but R is well supported on most platforms, and has great documentation: R Project Page

make sure r_HOME is set.

On some platforms or installations, you may also need to set the environment variable R_HOME. The value you use for R_HOME will depend on your particular installation, but following are typical values for setting R_HOME in the shell and in emacs for Mac OS X:

shell:

R_HOME=/Library/Frameworks/R.framework/Resources; export R_HOME

You can also set this in one of your .profile files to ensure that it is always set in your shell.

For emacs, in your scratch buffer, enter the elisp form:

(setenv "R_HOME" "/Library/Frameworks/R.framework/Resources")

Then, go to the end of that line and execute the key-command:

C-x C-e

..to execute the elisp form in your running emacs. You can also put that form in one of your emacs startup files if you want R_HOME to always be set.

Install Rincanter from git

git clone git://github.com/jolby/rincanter.git
cd rincanter

Download and Install the rosuda JRI and REngine components

This is a bit archaic. Rosuda seems to compile against the version of R installed on your system so we can’t distribute the JARs. You need to build two JARs, and one native lib and make them available to RIncanter.

The Native Library

Staring in the rincater base directory

mkdir external
cd external 
svn co svn://svn.rforge.net/org/trunk/rosuda/REngine
svn co svn://svn.rforge.net/org/trunk/rosuda/JRI
cd JRI
./configure
make

You will now have a jri native library file in this directory. Depending on your platform it will have a name like:

libjri.so (linux)
libjri.jnilib (Mac OS X)
jri.dll (Windows)

You need to make this native lib available to RIncanter which is done by putting in the appropriate directory. For instance on a 32 bit linux:

mkdir ../../target/
mkdir ../../target/native/
mkdir ../../target/native/linux/
mkdir ../../target/native/linux/x86/
cp libjri.so  ../../target/native/linux/x86/

The appropriate directory pattern is ../../target/native/<os>/<arch>/ where <os> is probably one of win,macosx,linux and <arch> is x86 or x86_64 if you are on 64bit.

Install the JARs

cd ../REngine
make

You will now have an REngine.jar file in this directory.

cd JRI # this is a child dir of REngine, different from the JRI dir above
make

You will now have an JRIEngine.jar file in this directory.

Now you need to make these JARs available to leiningen, either by installing them into the local repository or nexus. If you have maven handy you can install them to your local repo with these commands

mvn install:install-file -Dfile=./JRIEngine.jar -DartifactId=JRIEngine -Dversion=0.5-5 -DgroupId=JRIEngine -Dpackaging=jar
cd ..
mvn install:install-file -Dfile=./REngine.jar -DartifactId=REngine -Dversion=0.5-5 -DgroupId=REngine -Dpackaging=jar

Or follow https://github.com/technomancy/leiningen/blob/preview/doc/DEPLOY.md for more general instructions.

Test and Run

Now you are ready to test and run Rincanter. Test

lein test

To get an interactive session going by starting up emacs (making sure that R_HOME is visible) and then using nrepl

emacs project.clj

and then M-x nrepl-jack-in.

Example Usage

The main entry points are the functions:

r-eval

You can play around with Clojure/Incanter and R in the same REPL session:

(use '(com.evocomputing rincanter))

(r-eval "data(iris)")

;;eval's the iris dataframe object, converts into
;;incanter dataset
(r-eval "iris")
 
;;create vector on R side
(r-eval "vec_in_r = c(1,2,3)")

;;now retrieve it, converting to Clojure vector
(r-get "vec_in_r")

plotting:

(use '(com.evocomputing rincanter))

(r-eval "data(iris)")

;;initialize the R graphics device for your system:
;;For Mac OS X
(r-eval "quartz()")
;;windows: 
(r-eval "windows()")
;;unix/linux
(r-eval "x11()")

;;create the plot using values from the iris dataset
(r-eval "plot(Sepal.Length ~ Sepal.Width, data = iris)")
;;alter this existing plot
(r-eval "title(main = \"Iris Sepal Measurements\")")

with-r-eval

Using with-r-eval, it is even easier. Within this form, all forms enclosed in parenthesis are evaluated as normal Clojure forms, strings are evaluated in R using r-eval:

(use '(com.evocomputing rincanter))

(with-r-eval 
  "data(iris)"

  ;;eval's the iris dataframe object, converts into
  ;;incanter dataset
  "iris"
 
  ;;create vector on R side
  "vec_in_r = c(1,2,3)"

  ;;now retrieve it, converting to Clojure vector
  (r-get "vec_in_r"))

Documentation

API Documentation

API Documentation for rincanter is located at: Rincanter API