smc77 / rincanter

Use embedded R from Clojure and Incanter

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.

Install

Install Leiningen

Rincanter uses Leiningen 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
lein deps # This installs Incanter and its deps into the lib subdir
lein native-deps #This installs the native libs in the native subdir 

Test and Run

Now you are ready to test and run Rincanter:

To run the unit tests:

lein test

To start a repl:

lein repl

To start a swank session and connect with Emacs/SLIME:

lein swank

… then, in Emacs:

M-x slime-connect

Example Usage

The main entry points are the functions:

• r-eval
• with-r-eval
• r-set!
• r-get

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