rsugar 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c80b764190509a7f1474d4ea707ef88c6a42e25c
+  data.tar.gz: 0a4ba36be557a03e99620f18c8d732e69f6f09f6
+SHA512:
+  metadata.gz: 6b243bf9489ad07af200c8292e7edd2c626d6a41788afedd26b15284c6cba705bff7236b5ebd7ed213c2c3437e09ff329b268a8f1a251eb642298fd8f9aa2866
+  data.tar.gz: 8a6b51393b74d00143de2a1ef848017ca8ff8362d2b5f3c4e4e3e16c01859808610e2f63fc9a6d9db5ca5f65c6bce00d76d7d0627b35efe0ab40dcfda0db0713

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rsugar.gemspec
+gemspec
+
+gem 'rserve-client'
+
+group :development do
+  gem "rspec"
+  gem "pry"
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Justin Wiley
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,94 @@
+# Rsugar
+
+RSugar allows you to execute R language commands from Ruby.  It wraps rserve_client gem, providing some syntactic sugar and a few helper methods.
+
+## Installation
+
+Install rserve:
+
+    http://www.rforge.net/Rserve/doc.html
+
+Add this line to your application's Gemfile:
+
+    gem 'rsugar'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rsugar
+
+## Usage
+
+RSugar allows you to execute R language code on a seperate RServe.  It is essentially a wrapper that provides some nice sugar and block style execution for the rserve_client gem.
+
+R.exec is the main entry point.  You pass it a block, within which you have access to a few methods corresponding directly to the RServe gem API:
+
+    a - assign
+    e - eval
+    ve - void eval
+
+assign serializes the given Ruby object, sends it over to Rserve.  eval sends a given string to Rserve, executes it, and returns the result.  void eval executes the string on Rserve, but does not return the results.
+
+```ruby
+require 'rsugar'
+
+R.exec do
+  a 'x', 2
+  a 'y', 4
+  ve 'x = -x'
+  xy = e "x + y"
+  xdivy = e "x / y"
+  [xy, xdivy]
+end 
+=> [2, -0.5]
+```
+
+You can optionally pass a hash of Ruby objects, which will automatically be passed and initialized in the R environment.
+
+```ruby
+R.exec({xvals: [1,2,3,4], yvals: [4,3,2,1]}) do
+  e 'xvals + yvals'
+end
+=> [5,5,5,5]
+```
+
+### Packages
+
+Finally, you can ask rserver to use specific R packages.
+
+```ruby
+R.exec do
+  library('xtable')
+  e 'd <- data.frame(col1=c(1,2,3))'
+  e('xtable(d)')
+end.to_a
+=> [[1.0, 2.0, 3.0]]
+```
+
+The 'library' method also tries to install the package for you if it doesn't exist.  This requires the creation of an r-packages directory, and is somewhat dicey, since it can fail for a number of reasons (network connectivity, inability of R to install dependant packages, for example).
+
+For production systems, it's recommended you manually install R packages first.
+
+#### Default locations:
+
+| Environment        | Location                              |
+| ------------------ | ------------------------------------: |
+| Rails defined?     |   File.join(Rails.root, 'r-packages') |
+| Rails not defined? |   ./r-packages                        |
+
+### Note:
+
+There are some ramifications to using R this way, the first is that its sloooooow, since Ruby objects have to be serialized, transmitted over rserve's wire protocol, executed and round-tripped back to the Ruby process.
+
+In addition, each time R.exec is called, it creates a seperate connection to rserver, via Rserve::Connection.new.  After the block returns, this connection should be freed/garbage collected.  There is probably some not insignificant overhead with this, but you probably won't run into issues unless you're calling R.exec dozens or hundreds of times in an inner loop.  Which is a bad idea anyway since rserver is sloooooow.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/r.rb

@@ -0,0 +1,115 @@
+require 'rserve'
+require 'timeout'
+require 'matrix'  # seems to be required under the hood by rserve gem
+
+# R server wrapper
+#
+# The purpose of this class is to allow us to easily send R commands to the R server, process and return the results.
+#
+# R.exec is the key entry point
+class R
+  # Execute a block of R commands, using optional syntactic sugar, returning the results
+  #
+  # Creates a new connection to the RServe after every connection.
+  #
+  # Example:
+  # 
+  # require 'r'
+  # 
+  # R.exec do
+  #   a 'x', 2
+  #   a 'y', 4
+  #   ve 'x = -x'
+  #   xy = e "x + y"
+  #   xdivy = e "x / y"
+  #   [xy, xdivy]
+  # end 
+  # => [2, -0.5]
+  #
+  def self.exec args={}, &block
+    raise "Expected hash, keys will be defined as R variable names, example: {xvals: [1,2,3], yvals: [3,2,1]}" unless args.is_a?(Hash)
+    begin
+      conn = Rserve::Connection.new
+      dsl = R::RserveConnectionDsl.new conn, args
+      res = dsl.instance_eval &block
+      dsl.clear   # since connection is recycled, make an attempt to clean up all defined vars
+      return res
+    rescue => e
+      conn = dsl = nil    # ensure cleanup
+      raise e
+    end
+  end
+
+  # defines nice dsl for working with rserve-client
+  class RserveConnectionDsl
+    attr_accessor :conn, :args, :pkg_dir
+
+    def initialize conn, args={}
+      self.conn = conn
+      self.args = args
+      self.pkg_dir ||= args.delete(:pkg_dir)
+      self.pkg_dir ||= File.join(Rails.root, '/r-packages') if defined?(Rails)
+      self.pkg_dir ||= 'r-packages'      
+      args.each{|k,v| a(k.to_s, v)} if args.any?
+    end
+
+    def do_conn meth, *args
+      conn.send(meth, *args)
+    end
+
+    def assert_defined *keys
+      keys.map do |k|
+        begin
+          e k.to_s
+        rescue
+          raise ArgumentError.new("expected #{k} to be defined in R envionment, but was not")
+        end
+      end
+    end
+
+    # short for 'eval', execute given arguments, collect results, convert to ruby
+    def e *args
+      do_conn(:eval, *args).to_ruby
+    end
+
+    # short for 'void_eval', just execute the arguments, don't return results
+    def ve *args
+      do_conn :void_eval, *args
+    end
+
+    # short for 'assign', send ruby objects to r, save as variable
+    def a *args
+      args[1] = args[1].to_s if args[1].is_a?(Symbol)
+      do_conn :assign, *args
+    end
+
+    def package_installed? pkgname
+      e "('#{pkgname}' %in% rownames(installed.packages()) == TRUE)"
+    end
+
+    def installed_packages
+      e "rownames(installed.packages())"
+    end
+
+    def install_package pkgname
+      FileUtils.mkdir_p pkg_dir
+
+      unless package_installed? pkgname
+        ve "install.packages('#{pkgname}', repos='http://cran.cnr.Berkeley.edu/', depends=c('Depends'))"
+      end        
+    end
+
+    # attempts to install given R package if necessary and require in the environment via 'library'
+    def library pkgname, fail_after=300
+      Timeout::timeout(fail_after) do
+        install_package pkgname
+        e "library(#{pkgname})"
+      end
+    end
+
+    # remove defined variables from the R environment
+    def clear
+      ve 'rm(list=ls())'
+    end
+  end
+end

data/lib/rsugar.rb

@@ -0,0 +1,6 @@
+require "rsugar/version"
+require 'rserve'
+require 'r'
+
+module Rsugar
+end

data/lib/rsugar/version.rb

@@ -0,0 +1,3 @@
+module Rsugar
+  VERSION = "0.0.1"
+end

data/rsugar.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rsugar/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rsugar"
+  spec.version       = Rsugar::VERSION
+  spec.authors       = ["Justin Wiley"]
+  spec.email         = ["justin.wiley@gmail.com"]
+  spec.description   = %q{RSugar allows you to execute R language commands from Ruby.  It wraps rserve_client gem, providing some syntactic sugar and a few helper methods.}
+  spec.summary       = %q{RSugar allows you to execute R language commands from Ruby.  It wraps rserve_client gem, providing some syntactic sugar and a few helper methods.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "rserve-client"
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/spec/lib/r_spec.rb

@@ -0,0 +1,118 @@
+require 'pry'
+require_relative '../../lib/rsugar'
+
+describe R do
+  let(:conn) { Rserve::Connection.new }
+  let(:dsl) { R::RserveConnectionDsl.new conn }
+
+  before do
+    FileUtils.rm_rf(dsl.pkg_dir) if File.exist?(dsl.pkg_dir)
+  end
+  
+  it 'should execute R language statements using the DSL, and return results' do
+    R.exec do
+      a 'x', 2
+      a 'y', 4
+      ve 'x = -x'
+      xy = e "x + y"
+      xdivy = e "x / y"
+      [xy, xdivy]
+    end.should == [2, -0.5]
+  end
+
+  it 'should accept an optional hash of values, assign to named R values' do
+    R.exec({xvals: [1,2,3,4], yvals: [4,3,2,1]}) do
+      e 'xvals + yvals'
+    end.should == [5,5,5,5]
+  end
+
+  it 'should convert assigned values to string if they are symbol to prevent Rserve exceptions' do
+    R.exec({foobar: :stuff}){ e('foobar') }.should == 'stuff'
+  end
+
+  it 'should clean up defined R variables after block exists' do
+    R.exec { a 'x', 1 }
+    expect do
+      R.exec { e('x') }
+    end.to raise_error(Rserve::Connection::EvalError)
+  end
+
+  describe R::RserveConnectionDsl do
+    let(:pkgname) { "base" }
+
+    it 'should expose Rserve methods with shorter syntactic sugar accessors' do
+      val = "1"
+      return_val = Rserve::REXP::Integer.new 1
+      {eval: :e, assign: :a, void_eval: :ve}.each do |rserve_method, sugar|
+        conn.should_receive(rserve_method).with(val).and_return(return_val)
+        dsl.send(sugar, val)
+      end
+    end
+
+    it '#assert_defined should raise if given variables do not exist in R' do
+      dsl.a 'x', 2
+      dsl.assert_defined('x')
+      expect { dsl.assert_defined('y') }.to raise_error(ArgumentError)
+    end
+
+    it '#clear should remove bound variables from R environment (to the extent R allows this)' do
+      dsl.should_receive(:ve).with('rm(list=ls())')
+      dsl.clear
+    end
+
+    context 'package management' do
+      it '#installed_packages should return a list of installed R packages available on the server' do
+        dsl.installed_packages.should include("base")
+      end
+
+      it '#package_installed? should return true if specified package installed, false if not' do
+        dsl.package_installed?("base").should be_true
+        dsl.package_installed?("foobar").should be_false
+      end
+    end
+
+    context '#install_package' do
+      let(:do_install) { dsl.install_package(pkgname) }
+
+      it 'should -attempt- to install missing R library and all dependencies if it doesnt exist (dicey)' do
+        dsl.should_receive(:package_installed?).and_return(false)
+        dsl.should_receive(:ve).with("install.packages('#{pkgname}', repos='http://cran.cnr.Berkeley.edu/', depends=c('Depends'))")
+        do_install
+      end
+
+      it 'should not attempt to install if library already exists' do
+        dsl.should_receive(:package_installed?).and_return(true)
+        dsl.should_not_receive(:ve)
+        do_install
+      end
+
+      it 'should create a directory to store R packages if it doesnt already exist' do
+        File.exist?(dsl.pkg_dir).should be_false
+        do_install
+        File.exist?(dsl.pkg_dir).should be_true
+      end
+    end
+
+    context '#library' do
+      let(:do_library) { dsl.library(pkgname) }
+
+      it 'should install package if it doesnt exist and require R library' do
+        dsl.should_receive(:package_installed?).and_return(false)
+        dsl.should_receive(:e).with("library(#{pkgname})")
+        do_library
+      end
+
+      it 'should just require the package via R library function if it exists' do
+        dsl.should_receive(:package_installed?).and_return(true)
+        dsl.should_receive(:e).with("library(#{pkgname})")
+        do_library
+      end
+
+      it 'should actually do all this outside of stubs' do
+        dsl.library('xtable')
+        dsl.e 'd <- data.frame(col1=c(1,2,3))'
+        dsl.e('xtable(d)').should == [[1.0, 2.0, 3.0]]
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: rsugar
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Justin Wiley
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rserve-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: RSugar allows you to execute R language commands from Ruby.  It wraps
+  rserve_client gem, providing some syntactic sugar and a few helper methods.
+email:
+- justin.wiley@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/r.rb
+- lib/rsugar.rb
+- lib/rsugar/version.rb
+- rsugar.gemspec
+- spec/lib/r_spec.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: RSugar allows you to execute R language commands from Ruby.  It wraps rserve_client
+  gem, providing some syntactic sugar and a few helper methods.
+test_files:
+- spec/lib/r_spec.rb