simpler 0.0.4 → 0.1.0

data/README.rdoc

@@ -12,26 +12,33 @@ to you.
 
 == Examples
 
-FYI - the API is still unstable.
+FYI - the API is still a little unstable.
 
 ==== Basic execution (Raw input, raw output)
 
     require 'simpler'
-    simpler = Simpler.new
-    simpler.run!("mean(c(1,2,3))") # -> "[1] 2\n"  (a Simpler::Reply object)
+
+    r = Simpler.new
+    r.eval! { "mean(c(1,2,3))" } # -> "[1] 2\n"  (a Simpler::Reply object)
 
 ==== Using ruby variables (calculating correlation coefficient):
 
-    xv = [1,2,7]
-    yv = [3,4,8]
-    reply = simpler.with(xv,yv) {|x,y|  "cor(#{x},#{y})"  }.run!   # -> "[1] 0.9994238\n"
+    x = [1,2,7]
+    y = [3,4,8]
+    reply = r.eval!(x,y) {|xr,yr|  "cor(#{xr},#{yr})"  }   # -> "[1] 0.9994238\n"
+
+Any object that has a #to_r method can be passed in.  Currently, Array and
+Simpler::DataFrame are the only objects with this method defined, but one can
+go really far with only these two data types.
 
 ==== Show a plot
 
-"Rscript" writes plotting commands that would normally go to an X window to "Rplots.pdf".  *show!* merely executes your code and opens Rplots.pdf with @pdf_viewer.  It's low tech, but it works.
+Simpler uses <i>Rscript</i> to run R commands.  So, all plots that would
+normally go to X11 are saved to "Rplots.pdf".  *show!* is precisly the same as
+*eval!*, but it also opens "Rplots.pdf" with <i>@pdf_viewer</i>:
 
-    simpler.pdf_viewer = "acroread"
-    simpler.with(xv,yv) {|x,y|  "plot(#{x}, #{y})"  }.show!
+    r.pdf_viewer = "acroread"
+    r.show!(x,y) {|xr,yr| "plot(#{xr}, #{yr})" }
 
 ==== Using DataFrames
 
@@ -42,9 +49,16 @@ FYI - the API is still unstable.
     }
 
     df = Simpler::DataFrame.new(hash)
-    simpler.with(df) {|d|  "plot(#{d})" }.show!
+    r.show!(df) {|dfr|  "plot(#{dfr})" }
+
+One can also make a data frame from an array of structs with Simpler.from_structs
+
+==== When Errors Arise
+
+On an R error, raises a Simpler::RError that returns the R error message and
+shows the R code submitted. (the @command queue is still cleared)
 
-DataFrame also supports named rows and specifying directly column names.
+    r.eval! { "plot(c(1,2,3),c(1,2))" }
 
 == Credit
 

data/VERSION

@@ -1 +1 @@
-0.0.4
+0.1.0

data/lib/simpler.rb

@@ -16,61 +16,91 @@ class Simpler
   RPLOTS_FILE = "Rplots.pdf"
   PDF_VIEWER = "evince"
 
-  # returns the variable name of the object
+  # @param [Object] object a ruby object,  
+  # @return [String] the variable name of the object
   def self.varname(obj)
     "rb#{obj.object_id}"
   end
 
-  # returns it as a symbol, currently recognizes pdf, png, svg
-  def self.filename_to_plottype(name)
-    name.match(/\.([^\.]+)$/)[1].downcase.to_sym
-  end
-
   attr_accessor :commands
   attr_accessor :pdf_viewer
 
+  # @param [Array] commands a list of R commands to execute
+  # @param [Hash] opts options (currently :pdf_viewer which defaults to
+  # PDF_VIEWER)
   def initialize(commands=[], opts={:pdf_viewer => PDF_VIEWER})
     @pdf_viewer = opts[:pdf_viewer]
     @commands = commands
   end
 
-  def r_format(object)
-    case object
-    when String
-      object.inspect
-    when Numeric
-      object.to_s
-    else
-      object.to_s
-    end
+  # @example basic
+  #   # find the p value of a t-test
+  #   r.eval! do 
+  #     %Q{
+  #       x <- c(1,2,3)
+  #       y <- c(4,5,6)
+  #       ttest = t.test(x, y)
+  #       ttest$p.value
+  #     } 
+  #   end     # -> "[1] 0.02131164\n"
+  #   
+  # @example pass in variables (roughly equivalent)
+  #   x = [1,2,3]
+  #   y = [4,5,6]
+  #   r.eval!(x,y) do |xr,yr| 
+  #     %Q{
+  #       ttest = t.test(#{xr}, #{yr})
+  #       ttest$p.value
+  #     } 
+  #   end     # -> "[1] 0.02131164\n"
+  #
+  # (see Simpler#with)
+  def eval!(*objects, &block)
+    with(*objects, &block).run!
   end
 
-  # displays the Rplots.pdf file at the end of execution
-  def show!(string=nil)
-    if File.exist?(RPLOTS_FILE)
-      original_mtime = File.mtime(RPLOTS_FILE)
-    end
-    reply = run!(string)
-    system "#{@pdf_viewer} #{RPLOTS_FILE} &"
+  # (see  Simpler#eval!) same as eval! but also opens "Rplots.pdf" with PDF_VIEWER
+  # @example plotting
+  #   x = [1,2,3]
+  #   y = [4,5,6]
+  #   r.show!(x,y) do |xr,yr|
+  #     "plot(#{xr}, #{yr})"
+  #   end
+  #
+  # Simpler uses Rscript to run its code and Rscript writes X11 output to the
+  # PDF file "Rplots.pdf".  Simpler#show! merely makes a system call to open up
+  # the pdf file for viewing.  Obviously, for more interactive sessions one
+  # should just use R.
+  def show!(*objects, &block)
+    with(*objects, &block)
+    reply = run!
+    open_pdf_viewer(@pdf_viewer, RPLOTS_FILE)
     reply
   end
 
-  def error_message(error_string, r_code)
-    error_message = ""
-    error_message << "\n"
-    error_message << "*************************** Error inside R *****************************\n"
-    error_message << error_string
-    error_message << "------------------------- [R code submitted] ---------------------------\n"
-    error_message << r_code
-    error_message << "------------------------------------------------------------------------\n"
-    error_message
+  # @param [*Objects] objects list of objects
+  # @yield [*r_varnames] yields the R name of each variable (see Simpler.varname)
+  # @return [Simpler] returns self for chaining
+  # @example chaining
+  #   reply = r.with(dataframe) do |df|
+  #     %Q{ ... something with #{df} ... }
+  #   end.with(x,y,z) do |xr,yr,zr|
+  #     %Q{ ... something with #{xy} #{yr} #{zr} ... }
+  #   end.eval!
+  #   # can also .show!
+  def with(*objects, &block)
+    var_names = objects.map {|v| Simpler.varname(v) }
+    conversion_code = objects.map {|v| v.to_r }
+    @commands.push(*conversion_code)
+    unless block.nil?
+      @commands << block.call(*var_names)
+    end
+    self
   end
 
-
-  # pushes string onto command array (if given), executes all commands, and
-  # clears the command array.
-  def run!(string=nil)
-    @commands.push(string) if string
+  # executes all commands and clears the command array.
+  # @return [Simpler::Reply] a String subclass
+  def run!
     reply = nil
     error = nil
     cmds_to_run = @commands.map {|v| v + "\n"}.join
@@ -87,24 +117,38 @@ class Simpler
     Simpler::Reply.new(reply)
   end
 
-  # returns self for chaining
-  def with(*objects, &block)
-    var_names = objects.map {|v| Simpler.varname(v) }
-    conversion_code = objects.map {|v| v.to_r }
-    @commands.push(*conversion_code)
-    @commands << block.call(*var_names)
-    self
+  # formats strings and numbers to fit inside R code (this is for Strings and
+  # numbers mainly in inclusion in options)
+  #   String ==> "\"String\""
+  #   Numeric ==> "Numeric"
+  #   Other objects => "#{object.to_s}"
+  # @param [Object] object the ruby object
+  # @return [String] string suitable for R code
+  def self.r_format(object)
+    case object
+    when String
+      object.inspect
+    when Numeric
+      object.to_s
+    else
+      object.to_s
+    end
   end
 
-  def show_with!(*objects, &block)
-    with(*objects, &block).show!
-  end
- 
-  def run_with!(*objects, &block)
-    with(*objects, &block).run!
+  def error_message(error_string, r_code)
+    error_message = ""
+    error_message << "\n"
+    error_message << "*************************** Error inside R *****************************\n"
+    error_message << error_string
+    error_message << "------------------------- [R code submitted] ---------------------------\n"
+    error_message << r_code
+    error_message << "------------------------------------------------------------------------\n"
+    error_message
   end
 
-  alias_method :go!, :run_with!
+  def open_pdf_viewer(viewer, *files)
+    system "#{@pdf_viewer} #{files.join(" ")} &"
+  end
 
   class RError < StandardError
   end

data/lib/simpler/data_frame.rb

@@ -6,6 +6,23 @@ class Simpler
     attr_accessor :col_names
     attr_accessor :row_names
     attr_accessor :hash
+
+    # takes an array of structs and returns a data frame object
+    def self.from_structs(array)
+      names = array.first.members
+      lengthwise_arrays = names.map { Array.new(names.size) }
+      array.each_with_index do |struct,m|
+        struct.values.each_with_index do |val,n|
+          lengthwise_arrays[n][m] = val
+        end
+      end
+      hash = {}
+      names.zip(lengthwise_arrays) do |name, lengthwise_array|
+        hash[name] = lengthwise_array
+      end
+      self.new(hash)
+    end
+
     # takes a hash, where the col_name is the key and the data rows are an
     # array of values.  The default ordering of the hash keys will be used,
     # unless overridden with col_names.  The row_names can be used to specify

data/lib/simpler/plot.rb

@@ -2,9 +2,14 @@
 class Simpler
   module Plot
 
+    # returns it as a symbol, currently recognizes pdf, png, svg
+    def self.filename_to_plottype(name)
+      name.match(/\.([^\.]+)$/)[1].downcase.to_sym
+    end
+
     def plot(file_w_extension, opts={}, &block)
-      device = self.class.filename_to_plottype(file_w_extension)
-      opts_as_ropts = opts.map {|k,v| "#{k}=#{r_format(v)}"}
+      device = Simpler::Plot.filename_to_plottype(file_w_extension)
+      opts_as_ropts = opts.map {|k,v| "#{k}=#{Simpler.r_format(v)}"}
       string = "#{device}(#{file_w_extension.inspect}, #{opts_as_ropts.join(', ')})\n"
       string << block.call << "\n"
       string << "dev.off()\n"

data/lib/simpler/reply.rb

@@ -1,6 +1,7 @@
 
 class Simpler
   class Reply < String
+    ONE_FLOAT_RE = /] ([\w\.-]+)/o
 
     # removes the [1] from the line
     def rm_leader
@@ -11,11 +12,9 @@ class Simpler
       self.chomp.split("\n").rm_leader.split(" ")
     end
 
-    def to_f
-    end
-
-    def to_i
-      rm_leader.to_f
+    # returns a single float.  Assumes the answer takes the form: "[1] <Float>\n" => Float
+    def to_sf
+      ONE_FLOAT_RE.match(self)[1].to_f
     end
 
   end

data/spec/simpler_spec.rb

@@ -16,7 +16,7 @@ describe "Simpler" do
   end
 
   it 'can get a reply' do
-    reply = @r.run!("typos = c(2,3,0,3,1,0,0,1)\nmean(typos)\nhist(typos)")
+    reply = @r.eval!{"typos = c(2,3,0,3,1,0,0,1)\nmean(typos)\nhist(typos)"}
     reply.chomp.is "[1] 1.25"
   end
 
@@ -26,7 +26,7 @@ describe "Simpler" do
       "plot(c(1,2), c(2))" => %r{'x' and 'y' lengths differ},
     }
     code_matches.each do |code, matches|
-      message = lambda { @r.run!(code) }.should.raise(Simpler::RError).message
+      message = lambda { @r.eval!{code} }.should.raise(Simpler::RError).message
       message.should.match(matches)
       message.should.include code
     end
@@ -51,7 +51,7 @@ wetness             6   2     1
 relative humidity   7   9     7
 }
     df = Simpler::DataFrame.new(@hash, @row_names, @col_names)
-    as_data_frame = Simpler.new.with(df) {|df| df }.run!
+    as_data_frame = Simpler.new.eval!(df) {|df| df }
     as_data_frame.is expected
   end
 
@@ -63,7 +63,7 @@ relative humidity   7   9     7
 4   7   9     7
 }
     df = Simpler::DataFrame.new(@hash, nil, @col_names)
-    as_data_frame = Simpler.new.with(df) {|df| df }.run!
+    as_data_frame = Simpler.new.eval!(df) {|df| df }
     as_data_frame.is expected
   end
 end
@@ -81,13 +81,13 @@ describe 'making plots' do
   it 'has convenience wrappers for plotting to file' do
     @exts.each do |ext|
       file = @file + "." + ext
-      @r.with(@x, @y) do |x,y|
+      @r.eval!(@x, @y) do |x,y|
         @r.plot(file) do
           %Q{
             plot(#{x},#{y}, main="#{ext} scatterplot example", col=rgb(0,100,0,50,maxColorValue=255), pch=16)
           }
         end
-      end.run!
+      end
       File.exist?(file).is true
       IO.read(@file + ".svg").matches(/svg/) if ext == :svg
       File.unlink(file)
@@ -116,9 +116,9 @@ describe 'showing plots' do
   it 'can disply plots' do
     ok $SYSTEM_CALL.nil?
 
-    @r.with(@x, @y) do |x,y| 
+    @r.show!(@x, @y) do |x,y| 
       "plot(#{x}, #{y})"
-    end.show!
+    end
 
     # this shows that we've made a system call to visualize the data
     ok !$SYSTEM_CALL.nil?
@@ -127,7 +127,7 @@ end
 
 describe 'ancillary functions' do
   it 'can get the device from the filename' do
-    Simpler.filename_to_plottype("bob.the.pdf").is :pdf
-    Simpler.filename_to_plottype("larry.the.svg").is :svg
+    Simpler::Plot.filename_to_plottype("bob.the.pdf").is :pdf
+    Simpler::Plot.filename_to_plottype("larry.the.svg").is :svg
   end
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 4
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors: 
 - John Prince
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-13 00:00:00 -06:00
+date: 2010-08-03 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency