Quick Start

Syntax for using RinRuby

RinRuby is invoked within a Ruby script (or the interactive "irb" prompt denoted >>) using:

   >> require "rinruby"

This reads the deﬁnition of the RinRuby class into the current Ruby interpreter and creates an instance of the RinRuby class named R. The eval instance method passes the R commands contained in the supplied string and displays any resulting plots and prints any output. For example:

   >> sample_size = 10
   >> R.eval "x <- rnorm(#{sample_size})"
   >> R.eval "summary(x)"
   >> R.eval "sd(x)"

produces the following :

       Min.   1st Qu. Median   Mean     3rd Qu.   Max.
   -1.88900 -0.84930 -0.45220 -0.49290 -0.06069 0.78160
   [1] 0.7327981

This example used a string substitution to make the argument to ﬁrst eval method equivalent to x <- rnorm(10). This example used three invocations of the eval method, but a single invoke is possible using a here document:

   >> R.eval <<EOF
        x <- rnorm(#{sample_size})
        summary(x)
        sd(x)
      EOF

Data is copied from R to Ruby using the pull method or a short-hand equivalent. The pull method only supports R vectors which are numeric (i.e., integers or doubles) or character (i.e.,
strings). The R value of NA is pulled as nil into Ruby. Data in other formats must be coerced when copying to Ruby. The R object x deﬁned previously can be copied to Ruby object copy_of_x as follows:

   >> copy_of_x = R.pull "x"
   >> puts copy_of_x

which produces the following :

   -0.376404489256671
   -1.0759798269397
   -0.494240140140996
   0.131171385795721
   -0.878328334369391
   -0.762290423047929
   -0.410227216105828
   0.0445512804225151
   -1.88887454545995
   0.781602719849499

RinRuby also supports a convenient short-hand notation when the argument to pull is simply a previously-deﬁned R object (whose name conforms to Ruby’s requirements for method names):

   >> copy_of_x = R.x

The explicit assign method, however, can take an arbitrary R statement. For example:

   >> summary_of_x = R.pull "as.numeric(summary(x))"
   >> puts summary_of_x

produces the following:

   -1.889
   -0.8493
   -0.4522
   -0.4929
   -0.06069
   0.7816

Notice the use above of the as.numeric function in R. This is necessary since the pull method only supports R vectors which are numeric (i.e., integers or doubles) and character (i.e., strings). Data in other formats must be coerced when copying to Ruby.

Data is copied from Ruby to R using the assign method or a short-hand equivalent. For example:

   >> names = ["Lisa","Teasha","Aaron","Thomas"]
   >> R.assign "people", names
   >> R.eval "sort(people)"

produces the following:

[1] "Aaron" "Lisa" "Teasha" "Thomas"

The short-hand equivalent to the assign method is simply:

>> R.people = names

As with the short-hand notation for pull, some care is needed when using the short-hand of the assign method since the label (i.e., people in this case) must be a valid method name in Ruby. For example, R.copy.of.names = names will not work, but R.copy_of_names = names is permissible.

The assign method supports Ruby variables of type Fixnum (i.e., integer), Bignum (i.e. integer), Float (i.e., double), String, and arrays of one of those four fundamental types. Data in other formats must be coerced when copying to R. Note that Fixnum or Bignum values that exceed the capacity of R’s integers are silently converted to doubles. Data in other formats must be coerced when copying to R.

When assigning an array containing differing types of variables, RinRuby will follow R’s conversion conventions. An array that contains any Strings will result in a character vector in R. If the array does not contain any Strings, but it does contain a Float or a large integer (in absolute value), then the result will be a numeric vector of Doubles in R. If there are only integers that are suffciently small (in absolute value), then the result will be a numeric vector of integers in R.

Implementation Details

RinRuby is a program which allows the user to run R commands from Ruby. An instance of R is created as a new object within Ruby, which allows R to remain open and running until the user closes the connection. There is no software that needs to be installed in R. Ruby sends data to R over TCP/IP network sockets, while commands and text are passed through the pipe. The pipe avoids compatibility issues on differing operating systems, platforms, and versions of Ruby and R, while the socket can handle large amounts of data quickly while avoiding rounding issues for doubles.

Installation is simple and RinRuby works on Linux, Windows, and Mac OS X using a variety of Ruby implementation, including C Ruby and jRuby. Being 100% pure Ruby, RinRuby does not need to be adapted with each incremental release of R and Ruby.