rsruby 0.4.0 → 0.4.2

data/Manifest.txt

@@ -0,0 +1,37 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+examples/arrayfields.rb
+examples/bioc.rb
+examples/dataframe.rb
+examples/erobj.rb
+ext/Converters.c
+ext/Converters.h
+ext/R_eval.c
+ext/R_eval.h
+ext/extconf.rb
+ext/robj.c
+ext/rsruby.c
+ext/rsruby.h
+lib/rsruby.rb
+lib/rsruby/dataframe.rb
+lib/rsruby/erobj.rb
+lib/rsruby/robj.rb
+test/table.txt
+test/tc_array.rb
+test/tc_boolean.rb
+test/tc_cleanup.rb
+test/tc_eval.rb
+test/tc_extensions.rb
+test/tc_init.rb
+test/tc_io.rb
+test/tc_library.rb
+test/tc_modes.rb
+test/tc_robj.rb
+test/tc_sigint.rb
+test/tc_to_r.rb
+test/tc_to_ruby.rb
+test/tc_util.rb
+test/tc_vars.rb
+test/test_all.rb

data/README.txt

@@ -0,0 +1,96 @@
+== Introduction
+
+RSRuby is a bridge library for Ruby giving Ruby developers access to the full R statistical programming environment. RSRuby embeds a full R interpreter inside the running Ruby script, allowing R methods to be called and data passed between the Ruby script and the R interpreter. Most data conversion is handled automatically, but user-definable conversion routines can also be written to handle any R or Ruby class.
+
+RSRuby is a partial conversion of RPy[http://rpy.sourceforge.net/], and shares the same goals of robustness, ease of use and speed. The current version is stable and passes 90% of the RPy test suite. Some conversion and method calling semantics differ between RPy and RSRuby (largely due to the differences between Python and Ruby), but they are now largely similar in functonality.
+
+Major things to be done in the future include proper handling of OS signals, user definable I/O functions, improved DataFrame support and inevitable bug fixes.
+
+== Installation
+
+A working R installation is required. R must have been built with the '--enable-R-shlib' option enabled to provide the R shared library used by RSRuby.
+
+Ensure the R_HOME environment variable is set appropriately. E.g.:
+
+  R_HOME=/usr/lib/R (on Ubuntu Linux)
+  R_HOME=/Library/Frameworks/R.framework/Resources (on OS X)
+
+An RSRuby gem is available as well as a package using setup.rb. In each case the installation requires the location of your R library to compile the extension. This is usually the same as R_HOME. If you download the setup.rb package use these incantations:
+
+  ruby setup.rb config -- --with-R-dir=$R_HOME
+  ruby setup.rb setup
+  ruby setup.rb install
+
+Using gems it is almost the same:
+
+  gem install rsruby -- --with-R-dir=$R_HOME
+
+If RSRuby does not compile correctly you may need to configure the path to the R library, any one of the following should be sufficient:
+
+o Put the following line in your .bashrc (or equivalent):
+
+  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:RHOME/bin
+
+o or, make a link to RHOME/bin/libR.so in /usr/local/lib or /usr/lib, then run 'ldconfig'.
+
+o or, edit the file /etc/ld.so.conf, add the following line and then run 'ldconfig':
+
+  RHOME/bin
+
+== Documentation
+
+There are a few sources of documentation for RSRuby, though the manual should be considered the authoritative text.
+
+Manual:: The manual[http://web.kuicr.kyoto-u.ac.jp/~alexg/rsruby/manual.pdf] has most of the comprehensive information on calling R functions and the conversion system.
+Examples:: A few example scripts are included in the distribution:
+* Using Arrayfields[link:files/examples/arrayfields_rb.html] instead of Hash for named lists/vectors.
+* Using the Bioconductor[link:files/examples/bioc_rb.html] library.
+* An example[link:files/examples/dataframe_rb.html] using the DataFrame class.
+* An example[link:files/examples/erobj_rb.html] using the ERObj class.
+Tests:: The test scripts also show several usage examples.
+
+Finally, here is a very quick and simple example:
+
+ #Initialize R
+ require 'rsruby'
+
+ #RSRuby uses Singleton design pattern so call instance rather
+ #than new
+ r = RSRuby.instance
+ #Call R functions on the r object
+ data = r.rnorm(100)
+ r.plot(data)
+ sleep(2)
+ #Call with named args
+ r.plot({'x' => data,
+         'y' => data,
+         'xlab' => 'test',
+         'ylab' => 'test'})
+ sleep(2)
+
+== License
+
+Copyright (C) 2006 Alex Gutteridge
+
+The Original Code is the RPy python module.
+
+The Initial Developer of the Original Code is Walter Moreira.
+Portions created by the Initial Developer are Copyright (C) 2002
+the Initial Developer. All Rights Reserved.
+
+Contributor(s):
+Gregory R. Warnes <greg@warnes.net> (RPy Maintainer)
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

data/examples/arrayfields.rb

@@ -1,36 +1,52 @@
-require 'rubygems'
-require_gem 'arrayfields'
-require 'rsruby'
+#==Synopsis
+#
+#This example shows the use of custom converters to change the default
+#RSRuby behaviour. Normally RSRuby converts an R list or vector with the
+#name attribute to a Ruby Hash. Ruby Hashes do not conserve order however
+#unlike the R datatypes.
+#
+#To better replicate the R behaviour, this code uses the arrayfields library
+#(available as a gem) and the RSRuby Proc conversion mode to create named 
+#Arrays which preserve order.
+#
+#NB: You can run this file like a normal Ruby script. I use some post-
+#processing to allow me to add the source to RDoc.
+#
+#  require 'arrayfields'
+#  require 'rsruby'
+#
+#First we generate a Proc that will return true if we have an R object
+#that has the 'names' attribute set:
+#
+#  test_proc = lambda{|x| !(RSRuby.instance.attr(x,'names').nil?) }
+#
+#The next Proc takes the R object and generates a new Array with fields
+#set appropriately:
+#  
+#  conv_proc = lambda{|x|
+#    hash  = x.to_ruby
+#    array = []
+#    array.fields = RSRuby.instance.attr(x,'names')
+#    RSRuby.instance.attr(x,'names').each{|f| array[f] = hash[f]}
+#    return array
+#  }
+#
+#Next we start R, set the t.test function to use Proc conversion and
+#add our Procs to the proc_table Hash.
+#
+#  r = RSRuby.instance
+#  r.t_test.autoconvert(RSRuby::PROC_CONVERSION)
+#  r.proc_table[test_proc] = conv_proc
+#  
+#The return values from t.test are now Arrays rather than Hashes:
+#
+#  ttest = r.t_test([1,2,3])
+#  puts ttest.class
+#  ttest.each_pair do |field,val|
+#    puts "#{field} - #{val}"
+#  end
+#  puts ttest[1..3]
 
-test_proc = lambda{|x|
-  r = RSRuby.instance
-  names = r.attr(x,'names')
-  if names.nil?
-    return false
-  else
-    return true
-  end
-}
-
-conv_proc = lambda{|x|
-  r = RSRuby.instance
-  names = r.attr(x,'names')
-  hash  = x.to_ruby
-  array = []
-  array.fields = names
-  names.each do |field|
-    array[field] = hash[field]
-  end
-  return array
-}
-
-r = RSRuby.instance
-r.t_test.autoconvert(RSRuby::PROC_CONVERSION)
-r.proc_table[test_proc] = conv_proc
-
-ttest = r.t_test([1,2,3])
-puts ttest.class
-ttest.each_pair do |field,val|
-  puts "#{field} - #{val}"
+if __FILE__ == $0
+  eval(IO.read($0).gsub(/^\#\s\s/,''))
 end
-puts ttest[1..3]

data/examples/bioc.rb

@@ -1,99 +1,35 @@
-require 'rsruby'
-
-class ERObj
-
-  @@x = 1
-
-  def initialize(robj)
-    @robj = robj
-    @r    = RSRuby.instance
-  end
-
-  def as_r
-    @robj.as_r
-  end
-
-  def lcall(args)
-    @robj.lcall(args)
-  end
-
-  def to_s
-
-    @@x += 1
-
-    mode = RSRuby.get_default_mode
-    RSRuby.set_default_mode(RSRuby::NO_CONVERSION)
-    a = @r.textConnection("tmpobj#{@@x}",'w')
-
-    RSRuby.set_default_mode(RSRuby::BASIC_CONVERSION)
-    @r.sink(:file => a, :type => 'output')
-    @r.print_(@robj)
-    @r.sink.call()
-    @r.close_connection(a)
-
-    str = @r["tmpobj#{@@x}"].join("\n")
-
-    RSRuby.set_default_mode(mode)
-
-    return str
-
-  end
-
-  def method_missing(attr)
-    mode = RSRuby.get_default_mode
-    RSRuby.set_default_mode(RSRuby::BASIC_CONVERSION)
-    e = @r['$'].call(@robj,attr.to_s)
-    RSRuby.set_default_mode(mode)
-    return e
-  end
-
+#==Synopsis
+#
+#This example shows the use of the DataFrame class and eval_R to execute some
+#Bioconductor code
+#
+#  require 'rsruby'
+#  require 'dataframe'
+#
+#  r = RSRuby.instance
+#
+#First we setup the class_table Hash to convert dataframes to Ruby DataFrames
+#
+#  r.class_table['data.frame'] = lambda{|x| DataFrame.new(x)}
+#  RSRuby.set_default_mode(RSRuby::CLASS_CONVERSION)
+#
+#Then we load the Bioconductor affy library and use eval_R to run some affy
+#code
+#
+#  r.library('affy')
+#
+#  r.eval_R("mydata <- ReadAffy()") 
+#  r.eval_R("eset.rma <- rma(mydata)")
+#  r.eval_R("eset.pma <- mas5calls(mydata)")
+#
+#frame = r.eval_R("data.frame(exprs(eset.rma), exprs(eset.pma), se.exprs(eset.pma))")
+#
+#  puts frame.class
+#  puts frame.rows.join(" ")
+#  puts frame.columns.join(" ")
+#
+#  puts frame.send('COLD_12H_SHOOT_REP1.cel'.to_sym)
+
+if __FILE__ == $0
+  eval(IO.read($0).gsub(/^\#\s\s/,''))
 end
-
-class DataFrame < ERObj
-
-  def rows
-    return @r.attr(@robj, 'row.names')
-  end
-
-  def columns
-    cols = @r.colnames(@robj)
-    cols = [cols] unless cols.class == 'Array'
-    return cols
-  end
-
-  def method_missing(attr)
-    attr = attr.to_s
-    mode = RSRuby.get_default_mode
-    RSRuby.set_default_mode(RSRuby::BASIC_CONVERSION)
-    column_names = @r.colnames(@robj)
-    if attr == column_names or column_names.include?(attr)
-      RSRuby.set_default_mode(mode)
-      return @r['$'].call(@robj,attr.to_s)
-    end
-
-    #? Not sure what here...
-    RSRuby.set_default_mode(mode)
-    return super(attr)
-
-  end
-
-end
-
-r = RSRuby.instance
-
-r.class_table['data.frame'] = lambda{|x| DataFrame.new(x)}
-
-r.library('affy')
-
-r.eval_R("mydata <- ReadAffy()") 
-r.eval_R("eset.rma <- rma(mydata)")
-r.eval_R("eset.pma <- mas5calls(mydata)")
-
-RSRuby.set_default_mode(RSRuby::CLASS_CONVERSION)
-frame = r.eval_R("data.frame(exprs(eset.rma), exprs(eset.pma), se.exprs(eset.pma))")
-
-puts frame.class
-puts frame.rows.join(" ")
-puts frame.columns.join(" ")
-
-puts frame.send('COLD_12H_SHOOT_REP1.cel'.to_sym)

data/examples/dataframe.rb

@@ -1,15 +1,35 @@
-require 'rsruby'
-require 'rsruby/dataframe'
+#==Synopsis
+#
+#This example shows the use of the Class conversion system to convert
+#dataframes into the Ruby DataFrame class
+#
+#  require 'rsruby'
+#  require 'rsruby/dataframe'
+#
+#  r = RSRuby.instance
+#
+#Here we just set up a simple class table that returns a new DataFrame
+#object when a dataframe is returned by R
+#
+#  r.class_table['data.frame'] = lambda{|x| DataFrame.new(x)}
+#  RSRuby.set_default_mode(RSRuby::CLASS_CONVERSION)
+#
+#We then create a dataframe object to test the conversion
+#  e = r.as_data_frame(:x => {'foo' => [4,5,6], 'bar' => ['X','Y','Z']})
+#
+#Using some of the ERObj and DataFrame class capabilities we can access the
+#dataframe data in various ways
+#
+#  puts e
+#  puts e.foo.join(" ")
+#  puts e.bar.join(" ")
+#  puts e.rows.join(" ")
+#  puts e.columns.join(" ")
+#
+#  puts e.baz.join(" ")
+#
+#  puts e['foo'].join(" ")
 
-r.class_table['data.frame'] = lambda{|x| DataFrame.new(x)}
-RSRuby.set_default_mode(RSRuby::CLASS_CONVERSION)
-
-#slight kludge here need to use this form because of the
-#calling with keywords semantics are different to RPy
-e = r.as_data_frame(:x => {'foo' => [4,5,6], 'bar' => ['X','Y','Z']})
-
-puts e
-puts e.foo.join(" ")
-puts e.bar.join(" ")
-puts e.rows.join(" ")
-puts e.columns.join(" ")
+if __FILE__ == $0
+  eval(IO.read($0).gsub(/^\#\s\s/,''))
+end

data/examples/erobj.rb

@@ -1,16 +1,30 @@
-require 'rsruby'
-require 'rsruby/erobj'
+#==Synopsis
+#
+#In this example we intercept the conversion system using the proc conversion
+#mode. Instead of converting, every object returned by R is converted to an
+#ERObj
+#
+#  require 'rsruby'
+#  require 'rsruby/erobj'
+#
+#  r = RSRuby.instance
+#
+#Setting the proc table up with a Proc which always returns true serves to
+#intercept the RSRuby conversion system. The conversion system is bypassed
+#into the second Proc
+#
+#  r.proc_table[lambda{|x| true}] = lambda{|x| ERObj.new(x)}
+#  RSRuby.set_default_mode(RSRuby::PROC_CONVERSION)
+#
+#  e = r.t_test([1,2,3,4,5,6])
+#
+#One feature of ERObj is that they output the same string representation
+#as R. We can also access attributes of the R object
+#
+#  puts e
+#  puts "t value: #{e.statistic['t']}"
+#
 
-r = RSRuby.instance
-r.proc_table[lambda{|x| true}] = lambda{|x| ERObj.new(x)}
-RSRuby.set_default_mode(RSRuby::PROC_CONVERSION)
-
-e = r.t_test([1,2,3,4,5,6])
-
-puts e
-puts "t value: #{e.statistic['t']}"
-
-f = r.t_test([1,2,3])
-
-puts f
-puts "t value: #{f.statistic['t']}"
+if __FILE__ == $0
+  eval(IO.read($0).gsub(/^\#\s\s/,''))
+end