rinruby 0.99.1 → 0.99.3

data/README.txt

@@ -4,11 +4,12 @@ http://rinruby.ddahl.org
 Copyright 2005-2008 David B. Dahl
 
 Developed by David B. Dahl
-Documented by Scott Crawford and David B. Dahl
+Documented by David B. Dahl and Scott Crawford
 Homepage: http://rinruby.ddahl.org
 
 
 
+
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 3 of the License, or

data/lib/rinruby.rb

@@ -1,11 +1,45 @@
-# RinRuby
-# Accessing the R interpreter from pure Ruby
-# Copyright 2005-2008 David B. Dahl
+#=RinRuby: Accessing the R[http://www.r-project.org] interpreter from pure Ruby
 #
-# Coded by David B. Dahl
-# Documented by Scott Crawford and David B. Dahl
-# http://rinruby.ddahl.org
+#RinRuby is a Ruby library that integrates the R interpreter in Ruby, making R's statistical routines and graphics available within Ruby.  The library consists of a single Ruby script that is simple to install and does not require any special compilation or installation of R.  Since the library is 100% pure Ruby, it works on a variety of operating systems, Ruby implementations, and versions of R.  RinRuby's methods are simple, making for readable code.  The {website [rinruby.ddahl.org]}[http://rinruby.ddahl.org] describes RinRuby usage, provides comprehensive documentation, gives several examples, and discusses RinRuby's implementation.
 #
+#Below is a simple example of RinRuby usage for simple linear regression. The simulation parameters are defined in Ruby, computations are performed in R, and Ruby reports the results. In a more elaborate application, the simulation parameter might come from input from a graphical user interface, the statistical analysis might be more involved, and the results might be an HTML page or PDF report. 
+#
+#<b>Code</b>:
+#
+#      require "rinruby"
+#      n = 10
+#      beta_0 = 1
+#      beta_1 = 0.25
+#      alpha = 0.05
+#      seed = 23423
+#      R.x = (1..n).entries
+#      R.eval <<EOF
+#          set.seed(#{seed})
+#          y <- #{beta_0} + #{beta_1}*x + rnorm(#{n})
+#          fit <- lm( y ~ x )
+#          est <- round(coef(fit),3)
+#          pvalue <- summary(fit)$coefficients[2,4]
+#      EOF
+#      puts "E(y|x) ~= #{R.est[0]} + #{R.est[1]} * x"
+#      if R.pvalue < alpha
+#        puts "Reject the null hypothesis and conclude that x and y are related."
+#      else
+#        puts "There is insufficient evidence to conclude that x and y are related."
+#      end
+#
+#<b>Output</b>:
+#
+#      E(y|x) ~= 1.264 + 0.273 * x
+#      Reject the null hypothesis and conclude that x and y are related.
+#
+#Coded by:: David B. Dahl
+#Documented by:: David B. Dahl & Scott Crawford
+#Copyright:: 2005-2008
+#Web page:: http://rinruby.ddahl.org
+#E-mail::   mailto:rinruby@ddahl.org
+#License::  GNU General Public License (GPL), version 3 or later
+#
+#--
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
@@ -18,15 +52,45 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>
+#++
+#
 #
+#The required files java and readline are used when present at functionality.
 
 class RinRuby
 
+  VERSION = '0.99.3'
+
   require 'socket'
 
   attr_reader :interactive
   attr_reader :readline
 
+#RinRuby is invoked within a Ruby script (or the interactive 'irb' prompt denoted >>) using:
+#
+#      >> require "rinruby"
+#
+#This reads the definition of the RinRuby class into the current Ruby interpreter and creates an instance of the RinRuby class named R. There is a second method for starting an instance of R which allows the user to use any name for the instance, in this case myr:
+#
+#      >> require "rinruby"
+#      >> myr = RinRuby.new
+#      >> myr.eval "rnorm(1)"
+#Any number of independent instances of R can be created in this way.
+#
+#<b>Parameters that can be passed to the new method</b>
+#
+#* echo: By setting the echo to false, output from R is suppressed, although warnings are still printed. This option can be changed later by using the echo method. The default is true.
+#* interactive: When interactive is false, R is run in non-interaction mode, resulting in plots without an explicit device being written to Rplots.pdf. Otherwise, when interactive is true, such plots are shown on the screen. The default is true.
+#* executable: The path of the R executable (which is R in Linux and Mac OSX, or Rterm.exe in Windows) can be set with the executable argument. The default is nil, which on Windows uses the registry keys to find the path, or on linux and Mac OS X uses the path defined by $PATH.
+#* port_number: This is the smallest port number on the local host that could be used to pass data between Ruby and R. The actual port number used depends on port_width.
+#* port_width: RinRuby will randomly select a uniform number between port_number and port_number + port_width - 1, (inclusive), to pass data between Ruby and R. If the randomly selected port is not available, RinRuby will continue selecting random ports until it finds one that is available. By setting port_width to 1, RinRuby will wait until port_number is available. The default port_width is 1000.
+#
+#It may be desirable to change the parameters to the instance of R, but still call it by the name of R. In that case the old instance of R which was created with the require rinruby statement should be closed first using the quit method which is explained below. Unless the previous instance is killed, it will continue to use system resources until exiting Ruby. The following shows an example by changing the parameter echo:
+#
+#      >> require "rinruby"
+#      >> R.quit
+#      >> R = RinRuby.new(false)
+
   def initialize(echo=true, interactive=true, executable=nil, port_number=38442, port_width=1000)
     while true
       begin
@@ -45,7 +109,7 @@ class RinRuby
       when /bccwin/: 'windows'
       when /cygwin/: 'windows-cygwin'
       when /java/
-        require 'java'
+        require 'java' #:nodoc:
         if java.lang.System.getProperty("os.name") =~ /[Ww]indows/
           'windows-java'
         else
@@ -85,6 +149,8 @@ class RinRuby
     @socket = @server_socket.accept
   end
 
+#The method quit will gracefully close the bridge between Ruby and R, freeing up system resources. This method is automatically run when a Ruby script ends.
+
   def quit
     @writer.puts "q(save='no')"
     @socket.close rescue true
@@ -95,6 +161,36 @@ class RinRuby
     true
   end
 
+
+#The eval instance method passes the R commands contained in the supplied string and displays any resulting plots or prints the 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 first 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
+#
+#<b>Parameters that can be passed to the eval method</b>
+#
+#* string: The string parameter is the code which is to be passed to R, for example, string = "hist(gamma(1000,5,3))". The string can also span a large chunk of code by use of a here document, as shown:
+#      R.eval <<EOF
+#         x<-rgamma(1000,5,3)
+#         hist(x)
+#      EOF
+#
+#* echo_override: This argument allows one to set the echo behavior for this call only. The default for echo_override is nil, which does not override the current echo behavior.
+
   def eval(string, echo_override=nil)
     echo_enabled = ( echo_override != nil ) ? echo_override : @echo_enabled
     begin
@@ -134,6 +230,14 @@ class RinRuby
     true
   end
 
+#When using sending code to Ruby using an interactive prompt, this method will change the prompt to an R prompt. From the R prompt commands can be sent to R exactly as if the R program was actually running. When the user is ready to return to Ruby, then the command exit() will return the prompt to Ruby. This is the ideal situation for the explorative programmer who needs to run several lines of code in R, and see the results after each command. This is also an easy way to execute loops without the use of a here document. It should be noted that the prompt command does not work in a script, just Ruby's interaction irb.
+#
+#<b>Parameters that can be passed to the prompt method:</b>
+#
+#* regular_prompt: This defines the string used to denote the R prompt.
+#
+#* continue_prompt: This is the string used to denote R's prompt for an incomplete statement (such as a multiple for loop).
+
   def prompt(regular_prompt="> ", continue_prompt="+ ")
     raise "The 'prompt' method only available in 'interactive' mode" if ! @interactive
     return false if ! eval("0",false)
@@ -170,6 +274,25 @@ class RinRuby
     true
   end
 
+#If a method is called which is not defined, then it is assumed that the user is attempting to either pull or assign a variable to R.  This allows the user to do a simplified notation.  When an undefined method is followed by an equals sign, then it is assumed to be an assignment.  Thus
+#
+#      >> R.x = 2
+#
+#is the same as
+#
+#      >> R.assign("x",2)
+#
+#If an equals sign does not follow the method, then it is assumed to be a pull.  Thus
+#
+#      >> n = R.x
+#
+#is the same as
+#
+#      >> n = R.pull("x")
+#
+#This is also the reason is it not recommended that any variables be named after a method already defined, since this simplified notation would not work for that variable.
+#The parameters passed to method_missing are those used for the pull or assign depending on the context.
+
   def method_missing(symbol, *args)
     name = symbol.id2name
     if name =~ /(.*)=$/
@@ -181,6 +304,42 @@ class RinRuby
     end
   end
 
+#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
+#
+#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), Float (i.e., double), String, and arrays of one of those three fundamental types. Data in other formats must be coerced when copying to R.
+#
+#<b>Parameters that can be passed to the assign method:</b>
+#
+#* name: The name of the variable desired in R.
+#
+#* value: The value the R variable should have. The assign method supports Ruby variables of type Fixnum (i.e., integer), Float (i.e., double), String, and arrays of one of those three fundamental types. Data in other formats must be coerced when copying to R.
+#
+#* as_integer: Numerical variables in R are stored as doubles by default, but R provides the ability to have vectors of integers. A vector of integers may be required when interfacing between programs such as R, Fortran, C, or C++. Setting as_integer to true will specify that the value should be type cast into integers. The default is false.
+#
+#The assign method is an alternative to the simplified method, with some additional flexibility. When using the simplified method, the parameters of name and value are automatically used, in other words:
+#
+#      >> R.test = 144
+#
+#is the same as
+#
+#      >> R.assign("test",144)
+#
+#Of course it would be confusing to use the shorthand notation to assign a variable named eval, echo, or any other already defined function. RinRuby would assume you were calling the function, rather than trying to assign a variable.
+
   def assign(name, value, as_integer=false)
     if value.kind_of?(String)
       type = RinRuby_Type_String
@@ -240,6 +399,59 @@ class RinRuby
     nil
   end
 
+#Data is copied from R to Ruby using the pull method or a short-hand equivalent. The R object x defined with an eval method can be copied to Ruby object copy_of_x as follows:
+#
+#      >> R.eval "x <- rnorm(10)"
+#      >> 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-defined R object (whose name conforms to Ruby's requirements for method names). For example:
+#
+#      >> 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 of numerics (i.e., integers or doubles) and characters (i.e., strings). Data in other formats must be coerced when copying to Ruby.
+#
+#<b>Parameters that can be passed to the pull method:</b>
+#
+#* string: The name of the variable that should be pulled from R. The pull method only supports R vectors of numerics (i.e., integers or doubles) and characters (i.e., strings). Data in other formats must be coerced when copying to Ruby. 
+#
+#* singletons: R represents a single number as a vector of length one, but in Ruby it is often more convenient to use a number rather than an array of length one. Setting singleton=false will cause the pull method to shed the array, while singletons=true will return the number of string within an array.  The default is false.
+#
+#The pull method is an alternative to the simplified form where the parameters are automatically used, in other words:
+#
+#      >> puts R.test
+#
+#is the same as
+#
+#      >> puts R.pull("test")
+
   def pull(string, singletons=false)
     @writer.puts <<-EOF
       #{RinRuby_Variable} <- try(#{string})
@@ -303,6 +515,12 @@ class RinRuby
     result
   end
 
+#The eval method displays the output from R by default, but this can be turned off by using the echo method. This method is useful when the output behavior needs to be changed
+#
+#<b>Parameters that can be passed to the eval method</b>
+#
+#* enable: Setting enable to false will turn all output off until the echo command is used again with enable equal to true. Warnings are still sent to the output. The default is nil, which will return the current setting.
+
   def echo(enable=nil)
     @echo_enabled = enable if enable != nil
     @echo_enabled
@@ -384,6 +602,8 @@ class RinRuby
 end
 
 if ! defined?(R)
+  #R is an instance of RinRuby.  If for some reason the user does not want R to be initialized (to save system resources), then create a default value for R (e.g., <b>R=2</b> ) in which case RinRuby will not overwrite the value of R.
+
   R = RinRuby.new
 end
 

metadata

@@ -1,54 +1,47 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements: 
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: !str 0
+  version: 
+email: rinruby@ddahl.org
+cert_chain: []
+summary: Accessing the R interpreter from pure Ruby
+post_install_message: 
+extra_rdoc_files: []
+homepage: http://rinruby.ddahl.org
+signing_key: 
 name: rinruby
-version: !ruby/object:Gem::Version 
-  version: 0.99.1
-platform: ruby
-authors: 
-- David B. Dahl
+rdoc_options: []
 autorequire: 
-bindir: bin
-cert_chain: []
-
-date: 2008-06-16 00:00:00 -05:00
-default_executable: 
-dependencies: []
-
-description: 
-email: rinruby@ddahl.org
+rubyforge_project: rinruby
 executables: []
-
-extensions: []
-
-extra_rdoc_files: []
-
+description: 
+specification_version: 2
+default_executable: 
 files: 
 - lib/rinruby.rb
 - README.txt
-has_rdoc: true
-homepage: http://rinruby.ddahl.org
-post_install_message: 
-rdoc_options: []
-
-require_paths: 
-- lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-  version: 
-required_rubygems_version: !ruby/object:Gem::Requirement 
+required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: !str 0
   version: 
-requirements: []
-
-rubyforge_project: rinruby
-rubygems_version: 1.1.1
-signing_key: 
-specification_version: 2
-summary: Accessing the R interpreter from pure Ruby
+extensions: []
+rubygems_version: 1.1.0
+requirements: 
+- R (http://www.r-project.org), an environment for statistical computing and graphics
+authors: 
+- David B. Dahl
+date: 2008-07-02 05:00:00 +00:00
+platform: ruby
 test_files: []
-
+version: !ruby/object:Gem::Version
+  version: 0.99.3
+require_paths: 
+- lib
+dependencies: []
+bindir: bin
+has_rdoc: true