Welcome to Rincanter!
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.
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:
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:
..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
To get an interactive session going by starting up emacs (making sure that R_HOME is visible) and then using nrepl
and then M-x nrepl-jack-in.
The main entry points are the functions:
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")
(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\")")
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"))
API Documentation for rincanter is located at: Rincanter API