rserve-simpler¶ ↑

rserve-simpler is a simple interface on top of rserve-client, a fantastic gem that lets a user communicate with R in a straighforward, efficient way.

rserve-client is doing all the heavy lifting and should be consulted for background.

Synposis¶ ↑

require 'rserve/simpler'
r = Rserve::Simpler.new

# or can initialize a connection held in the 'R' constant:
require 'rserve/simpler/R'
R.do_something_fantastic ...  # ** not a real method

converse, convert, command¶ ↑

These commands specify ways of talking to your Rserve connection. They differ chiefly in the type of output you’ll receive back from R.

# converse: casts the result with 'to_ruby'
r.converse "mean(c(1,2,3))"  # -> 2.0

# convert: returns the raw Rserve::REXP result (like eval)
rexp = r.convert "mean(c(1,2,3))"  # -> #<Rserve::REXP::Double:0x00000002296498 @payload=[2.0], @attr=nil>
rexp.as_doubles   # -> [2.0]
rexp.to_ruby      # -> 2.0

# command: tell R what to do and only expect boolean reply
r.command "z <- mean(c(1,2,3))"  # -> true
# all variables are persistent in the session and can be retrieved later
r.converse "z"  # -> 2.0

converse/convert/command let you name variables in a hash as a shortcut to ‘assign’. [These examples use Ruby 1.9 hash syntax, but they should work on 1.8 if the hashes are keyed old-style {:key => val}]

r.converse(a: [1,2,3], b: [4,5,6]) { "cor(a,b)" } # -> 1.0
# another form doing the same thing
r.converse("cor(a,b)", a: [1,2,3], b: [4,5,6])

prompt-like syntax ‘>>’¶ ↑

‘>>’ is an alias for converse, so you can write code like this:

r >> "mean(c(1,2,3))"  # -> 2.0
# note: use '.>>' (and parentheses at times) to get proper behavior with multiple args or blocks
r.>> "cor(a,b)", a: [1,2,3], b: [1,2,3]

simple DataFrame¶ ↑

Data frames are a prominent object in R. Simpler provides a simple ruby DataFrame object.

Hash based¶ ↑

Column names are derived from the data hash’s keys. Ruby 1.9 hashes keep track of insertion order. Use an OrderedHash (gem install orderedhash) for ruby 1.8, or set colnames.

hash = {
  var1: [1,2,3,4], 
  fac1: [3,4,5,6], 
  res1: [4,5,6,7]
}
# convert with hash.to_dataframe or Rserve::DataFrame.new(hash)
r.command( df: hash.to_dataframe ) do 
  %Q{ 
    pdf("out.pdf")
    plot(df)
    dev.off()
  }
end

with an array of Structs¶ ↑

The equivalent data frame as above can be generated with an array of Struct objects.

DataRow = Struct.new(:var1, :fac1, :res1)
structs = [
  DataRow.new(1,3,4),
  DataRow.new(2,4,5),
  DataRow.new(3,5,6),
  DataRow.new(4,6,7)
]
datafr = Rserve::DataFrame.from_structs(structs)
reply = r.converse("summary(df)", df: datafr).each_cons(6).to_a
datafr.colnames.zip(reply) {|name,data| puts [name].+(data).join("\n ") }

## outputs -> :
var1
 Min.   :1.00  
 1st Qu.:1.75  
 Median :2.50  
 Mean   :2.50  
 3rd Qu.:3.25  
 Max.   :4.00  
fac1
 Min.   :3.00  
 1st Qu.:3.75  
 ...

Notes on plotting¶ ↑

Rserve is great for graphical output. Here are some pointers when getting started with plotting:

plot to screen¶ ↑

Plots to x11() are persistent until the script or session ends.

Inside an irb session:

irb>>  r >> "plot(c(1,2,3), c(3,4,5))"
# if you resize a window (at least on Ubuntu) you may need to re-issue the call
irb>>  r >> "plot(c(1,2,3), c(3,4,5))"
# return a list of currently used devices (device 2 is the only one being used)
# to_ruby returns an array of 1 value as a number
irb>>  r >> "dev.list()"
=> 2
# shut off graphics device 2
# [??] sometimes this generates windows 3 & 4, not sure what is happening
irb>> r >> "dev.off(2)"
# shut off all graphics
irb>> r >> "graphics.off()"

In a script, your plot will appear until the script exits. This usually means you’ll miss the display of your plot. Two ways to deal with this:

sleep¶ ↑

r >> "plot(c(1,2,3), c(4,5,6))"
sleep(7)  # pause for 7 seconds

r.pause¶ ↑

r >> "plot(c(1,2,3), c(4,5,6))"
r.pause  # pauses things until a key is pressed in terminal

plot to file¶ ↑

Files are written below the workdir specified when the Rserve connection was made (see Rserve configuration for background) and this is “/tmp/Rserve” on my system.

r.>> "pdf('output.pdf')", "plot(c(1,2,3),c(4,5,6))", "dev.off()"
# outputs file /tmp/Rserv/conn156/output.pdf
# note the connection number dir!
# (I haven't figured out how to predict this number)

support for NArray¶ ↑

NArray vectors work as input to converse, convert, and command.

TODO¶ ↑

simple option to use pwd as default directory
quiet the startup of Rserve by default
wrap graphic output commands

Copyright¶ ↑

see LICENSE.txt

jtprince/rserve-simpler