Clojisr tutorial

Basic examples

Let us start by some basic usage examples of Clojisr.

First, let us make sure that we use the Rserve backend (in case we were using Renjin instead earlier), and that there are no R sessions currently running.

Now let us run some R code, and keep a Clojure handle to the return value.

Convert the R to Clojure: This part requires more thorough documentation.

Run some code on a separate session (specified Rserve port, rather than the default one).

Convert Clojure data to R data. Note that nil is turned to NA.

Functions

An R function is also a Clojure function.

Let us apply it to Clojure data (implicitly converting that data to R).

We can also apply it to R data.

Functions can get named arguments. Here we pass the na.rm argument, that tells R whether to remove missing values whenn computing the mean.

An alternative call syntax:

Anoter example:

Some functions are already created in Clojisr and given special names for convenience. For example:

R dataframes and tech.ml.dataset datasets

Create a tech.ml.dataset dataset object, pass it to an R function to compute the row means, and convert the return value to Clojure.

Load the R package 'dplyr' (assuming it is installed).

Use dplyr to process some Clojure dataset, and convert back to the resulting dataset.

Tibbles are also supported, as a special case of data frames.

R objects

Clojisr holds handles to R objects, that are stored in memory at the R session, where they are assigned random names.

We can figure out the place in R memory corresponding to an object's name.

Generating code

Let us see the code-generation mechanism of Clojisr, and the rules defining it.

We will need a reference to the R session:

For the following examples, we will use some dummy handles to R objects:

.. and some real handles to R objects:

For an r-object, we generate the code with that object's location in the R session memory.

For a clojure value, we implicitly convert to an R object, generating the corresponding code.

For a symbol, we generate the code with the corresponding R symbol.

A sequential structure (list, vector, etc.) can be interpreted as a compound expression, for which code generation is defined accorting to the first list element.

For a list beginning with the symbol 'function, we generate an R function definition.

For a vector instead of list, we heve the same behaviour.

For a list beginning with the symbol 'tilde, we generate an R ~-furmula.

For a list beginning with a symbol known to be a binary operator, we generate the code with that operator between all arguments.

For a list beginning with another symbol, we generate a function call with that symbol as the function name.

For a list beginning with an R object that is a function, we generate a function call with that object as the function.

All other sequential things (that is, those not beginning with a symbol or R function) are intepreted as data, converted implicitly to R data.

Some more examples, showing how these rules compose:

Running generated code

Clojure forms can be run as R code. For example:

Let us repeat the basic examples from the beginning of this tutorial, this time generating code rather than writing it as Strings.

The strange column name is due to dplyr's mutate behaviour when extra parens are added to the expression.

Requiring R packages

Sometimes, we want to bring to the Clojure world functions and data from R packages. Here, we try to follow the require-python syntax of libpython-clj (though currently in a less sophisticated way.)

Data visualization

Functions creating R plots or any plotting objects generated by various R libraries can be wrapped in a way that returns an SVG, BufferedImage or can be saved to a file. All of them accept additional parameters specified in grDevices R package.

Currently there is a bug that sometimes causes axes and labels to disappear when rendered inside a larger HTML.

First example, simple plotting function as SVG string.

ggplot2 plots (or any other plot objects like lattice) can be also turned into SVG.

Any plot (function or object) can be saved to file or converted to BufferedImage object.

Intermediary representation as Java objects.

Clojisr relies on the fact of an intemediary representation of java, as Java objects. This is usually hidden from the user, but may be useful sometimes. In the current implementation, this is based on REngine.

We can convert data between R and Java.

We can further convert data from the java representation to Clojure.

On the opposite direction, we can also convert Clojure data into the Java represenattion.

There is an alternative way of conversion from Java to Clojure, naively converting the internal Java representation to a Clojure data structure. It can be handy when one wants to have plain access to all the metadata (R attributes), etc.

We can evaluate R code and immediately return the result as a java object, without ever creating a handle to an R object holding the result:

More data conversion examples

Convertion between R and Clojure always passes through Java. To stress this, we write it explicitly in the following examples.

Basic types convertion clj->r->clj

Various R objects

Named list

Array of doubles

Timeseries

Pairlist

NULL

TRUE/FALSE

Inspecting R functions

The mean function is defined to expect arguments x and .... These arguments have no default values (thus, its formals have empty symbols as values):

It is an S3 generic function function, which we can realize by printing it:

So, we can expect possibly more details when inspecting its default implementation. Now, we see some arguments that do have default values.

R-function-arglists

As we saw earlier, R functions are Clojure functions. The arglists of functions brought up by require-r match the expected arguments. Here are some examples:

Using Renjin

In the followint example, we use a differnt R backend (the pure JVM Renjin) for reading a csv, without changing the default backend (which is the usual R using Rserve).