rri 0.1.0

data/.document

@@ -0,0 +1,3 @@
+- 
+ChangeLog.*
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "rri Documentation" --protected

data/ChangeLog.md

@@ -0,0 +1,4 @@
+### 0.1.0 / 2011-03-27
+
+* Initial release:
+

data/Gemfile

@@ -0,0 +1,16 @@
+source :rubygems
+
+#gemspec
+
+group :development do
+  gem 'rake',         '~> 0.8.7'
+  gem 'ore-tasks',    '~> 0.4'
+  gem 'rspec',        '~> 2.5'
+  gem 'kramdown'
+  gem 'yard',         '~> 0.6.0'
+  gem 'yardstick'
+  gem 'awesome_print'
+  gem 'guard',        '~> 0.3.0'
+  gem 'guard-rspec',  '~> 0.2.0'
+  gem 'rcov',         '~> 0.9.9'
+end

data/Guardfile

@@ -0,0 +1,6 @@
+# rspec
+guard 'rspec' do
+  watch(%r{^spec/.+_spec\.rb})
+  watch(%r{^lib/(.+)\.rb})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb') { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Patrik Sundberg
+
+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,131 @@
+# rri
+
+* [Homepage](https://github.com/sundbp/rri)
+* [Documentation](http://rubydoc.info/gems/rri/frames)
+
+## Description
+
+This gem provides an interface from ruby to R by using [JRI](http://www.rforge.net/JRI/) 
+(the Java/R Interface) from JRuby. JRI is a well established way of interfacing with R from Java
+and hence a great building block to enable JRuby to interface with R.
+
+This gem also enables the use of the R package [JavaGD](http://www.rforge.net/JavaGD/). JavaGD is
+a R graphics device used to output graphics to a Java class. This makes it possible to easily
+integrate R graphics with java/JVM GUI applications (for example it is used by
+[JGR](http://www.rforge.net/JGR/)). JavaGD allows you to provide a custom class used for painting 
+which could well be implemented in jruby. Read the JavaGD package documentation for more information.
+
+At the moment this gem is mostly aimed towards using R from ruby, but there's nothing stopping us
+from taking advantage of [rJava](http://www.rforge.net/rJava/) to also allow R to call into jruby.
+
+## Features
+
+* Call R functions from ruby
+* An extendible system for converting between R and ruby data types (in both directions)
+* Plot R graphics using user supplied class
+
+## Examples
+
+    require 'rri'
+    
+    engine = Rri::Engine.new
+    
+    # high level API, converts results and arguments from and to R/ruby
+    result = engine.eval_and_convert("1.23 + 4.56") # result will be a noromal ruby Float (5.79)
+    engine.convert_and_assign(result, :x)           # x = 5.79 in R
+    result = engine.get_and_convert(:x)             # result is a ruby Float
+    
+    # helpers for the low level API, useful when you're not bothered
+    # about converting any values to/from R/ruby
+    result = engine.simple_eval("x + 1")            # returns a reference to R object
+    engine.simple_assign("y", result)               # y = 6.79 in R, assumes the value is an R object, 
+                                                    # no conversion takes place.
+    result = engine.simple_get(:y)                  # returns a reference to R object
+    
+    # we should always close an engine, if we don't the R thread
+    # seem to hang around forever causing the ruby program to not
+    # exit. There is however also a finalizer defined that should
+    # automatically take care of this.
+    #
+    # use normal JRIEngine API via method missing forwarding
+    engine.close
+    
+Please also see the examples in the 'examples/' directory for more interesting use cases.
+
+## Requirements
+
+* An installation of [R](http://www.r-project.org/)
+* The R packages **rJava** and **JavaGD**
+
+## Install
+
+First we need the rri gem:
+
+    $ gem install rri
+
+Next we switch to R to install the required R packages:
+
+    > install.packages(c("rJava", "JavaGD"))
+
+After this we need to make sure rri is able to find the needed jar-files. rri will attempt
+to read the jars in the path specified by the environment variables:
+
+* **RRI_JRI_JAR_PATH**
+* **RRI_JAVAGD_JAR_PATH**
+
+Set the first environment variable to the path given by the following R command:
+
+    > system.file("jri",package="rJava")
+  
+and the second one to the path given by:
+
+    > system.file("java", package="JavaGD")
+
+Make sure the OS can load dynamic libraries from the R directory. On Windows that means
+making it part of the path. On my machine it means adding "C:\Program Files\R\R-2.12.1\bin\i386"
+to the **PATH**.
+
+The last thing we need to make sure of is that the shared library distributed with JRI is
+accessible by the operating system. I have not gone over this exercise on unix type systems
+yet but on Windows this means that the path set in **RRI_JRI_JAR_PATH** is also part of the
+**PATH**.
+
+I tried to add this to the path within the rri gem itself before loading the JRI jars
+but it seems the jruby class loader fails to pick it up so it needs to be part of the **PATH** 
+before a program using rri is launched. On linux like systems I'd expect there may be a need
+for something similar in relation to **LD_LIBRARY_PATH** but I haven't had a chance to test it yet.
+
+## Type conversions
+
+R and ruby have quite different type systems, but at least for the most common types of
+data we can implement some natural conversions (in both directions).
+
+Type conversion in both directions are tried in 3 levels:
+* first custom specified (user) converters for a given engine are tried
+* then custom specified (user) converters applicable to all engines are tried
+* and finally a set of default converters specified by rri itself are applied
+
+For custom converters the order in which they are tried is the reverse order
+in which they were added, so the latest added converter is tried first.
+
+To write your own custom converters please take a look at the default ones
+in rri/r_converters and rri/ruby_converters. For help with the R type system
+the REXP [JavaDocs](http://www.rforge.net/org/docs/org/rosuda/REngine/REXP.html)
+are a good place to start.
+
+**TODO**: describe the default converters, for now best docs are the specs
+
+## Note about instantiating engines many times in the same process
+
+There seem to be issues in the C layer of either JRI or the R library when
+you create an engine many times in the same process. That applies also if
+you never have more than one engine created at any one time.
+
+Emperically I get an infinite hang in the C layer if I re-create an engine
+more than ~12 times in the same process.
+
+## Copyright
+
+Copyright (c) 2011 Patrik Sundberg
+
+See {file:LICENSE.txt} for details.

data/Rakefile

@@ -0,0 +1,66 @@
+require 'rubygems'
+
+begin
+  require 'bundler'
+rescue LoadError => e
+  STDERR.puts e.message
+  STDERR.puts "Run `gem install bundler` to install Bundler."
+  exit e.status_code
+end
+
+begin
+  Bundler.setup(:development)
+rescue Bundler::BundlerError => e
+  STDERR.puts e.message
+  STDERR.puts "Run `bundle install` to install missing gems."
+  exit e.status_code
+end
+
+require 'rake'
+
+require 'ore/tasks'
+Ore::Tasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task :test => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new  
+task :doc => :yard
+
+require 'yardstick/rake/measurement'
+Yardstick::Rake::Measurement.new(:yardstick_measure) do |measurement|
+  measurement.output = 'measurement/report.txt'
+end
+
+require 'yardstick/rake/verify'
+Yardstick::Rake::Verify.new do |verify|
+  verify.threshold = 80
+end
+
+desc "Run specs with rcov"
+RSpec::Core::RakeTask.new("spec:rcov") do |t|
+  t.rcov = true
+  t.rcov_opts = %w{--exclude "spec\/,jsignal_internal"}
+end
+
+# for rcov threshold testing
+rcov_coverage_threshold = 90
+require_exact_rcov_threshold = false
+
+desc "Verify that rcov coverage is at least #{rcov_coverage_threshold}%"
+task :verify_rcov => "spec:rcov" do
+  total_coverage = 0
+  File.open("coverage/index.html").each_line do |line|
+    if line =~ /<tt class='coverage_total'>\s*(\d+\.\d+)%\s*<\/tt>/
+      total_coverage = $1.to_f
+      break
+    end
+  end
+  puts "Coverage: #{total_coverage}% (threshold: #{rcov_coverage_threshold}%)"
+  raise "Coverage must be at least #{rcov_coverage_threshold}% but was #{total_coverage}%" if total_coverage < rcov_coverage_threshold
+  raise "Coverage has increased above the threshold of #{rcov_coverage_threshold}% to #{total_coverage}%. You should update your threshold value." if (total_coverage > threshold) and require_exact_rcov_threshold
+end

data/examples/create_pdf.rb

@@ -0,0 +1,18 @@
+# example of producing a pdf from an R plot
+
+$LOAD_PATH << File.dirname(__FILE__) + "/../lib"
+require 'rri'
+
+engine = Rri::Engine.new
+
+filename = "plot_from_r.pdf"
+begin
+  engine.simple_eval("data(iris)")
+  engine.simple_eval("pdf('#{filename}')")
+  engine.simple_eval("print(stripchart(iris[, 1:4], method = 'stack', pch = 16, cex = 0.4, offset = 0.6))")
+  engine.simple_eval("dev.off()")
+rescue => e
+  puts "Caught exception: " + e
+end
+
+puts "Checkout plot generated in file: #{filename}"

data/examples/ggplot.rb

@@ -0,0 +1,42 @@
+# example of drawing a density with ggplot2
+
+$LOAD_PATH << File.dirname(__FILE__) + "/../lib"
+require 'rri'
+
+# Ruby Gaussian Random Number Generator
+# Author: Glenn
+# http://webhost101.net/rails/typo/articles/2007/07/31/ruby-gaussian-random-number-generator
+
+def gaussian_rand 
+   u1 = u2 = w = g1 = g2 = 0  # declare
+   begin
+     u1 = 2 * rand - 1
+     u2 = 2 * rand - 1
+     w = u1 * u1 + u2 * u2
+   end while w >= 1
+   
+   w = Math::sqrt( ( -2 * Math::log(w)) / w )
+   g2 = u1 * w;
+   g1 = u2 * w;
+   # g1 is returned  
+end
+
+random_numbers = []
+1000.times { random_numbers << gaussian_rand }
+
+# use the std out callback object to get some printouts from R, good for debugging.
+engine = Rri::Engine.new(:callback_object => Rri::CallbackObjects::REngineStdOutput.new)
+
+filename = "ggplot.pdf"
+begin
+  engine.simple_eval("library(ggplot2)")
+  engine.convert_and_assign(random_numbers, :y)
+  engine.simple_eval("df <- data.frame(y)")
+  engine.simple_eval("pdf('#{filename}')")
+  engine.simple_eval("print(qplot(y, data=df, geom='histogram', binwidth=0.1))")
+  engine.simple_eval("dev.off()")
+rescue => e
+  puts "Caught exception: " + e
+end
+
+puts "Checkout plot generated in file: #{filename}"

data/examples/simple.rb

@@ -0,0 +1,19 @@
+# example of just setting up an engine, adding two numbers in R and retrieving the result
+
+$LOAD_PATH << File.dirname(__FILE__) + "/../lib"
+require 'rri'
+
+engine = Rri::Engine.new
+
+# low level interface
+result = engine.simple_eval("1.23 + 4.56")
+puts "Result is: #{result} (which is of type #{result.class})"
+engine.simple_assign(:x, result)
+
+# higher level interface including conversions
+result = engine.eval_and_convert("y <- x + 1")
+result = engine.get_and_convert(:y)
+puts "Result is: #{result} (which is of type #{result.class})"
+
+# close the engine
+engine.close

data/gemspec.yml

@@ -0,0 +1,11 @@
+name: rri
+summary: "Ruby/R Interface for JRuby"
+description: "Ruby/R Interface - A wrapper of jri (Java/R Interface) for JRuby"
+license: MIT
+authors: Patrik Sundberg
+homepage: http://rubygems.org/gems/rri
+has_yard: true
+
+development_dependencies:
+  bundler: ~> 1.0.0
+  yard: ~> 0.6.0

data/lib/rri.rb

@@ -0,0 +1,11 @@
+require 'rri/version'
+
+require 'rri/rri_exception'
+
+require 'rri/jri'
+require 'rri/java_gd'
+require 'rri/rexp'
+
+require 'rri/engine'
+
+require 'rri/callback_objects'

data/lib/rri/callback_objects.rb

@@ -0,0 +1 @@
+require 'rri/callback_objects/r_engine_std_output'

data/lib/rri/callback_objects/r_engine_std_output.rb

@@ -0,0 +1,6 @@
+
+module Rri
+  module CallbackObjects
+    java_import "org.rosuda.REngine.REngineStdOutput"
+  end
+end

data/lib/rri/engine.rb

@@ -0,0 +1,390 @@
+require 'rri/jri'
+require 'rri/r_converters'
+require 'rri/ruby_converters'
+
+module Rri
+  
+  # The main class to interface with R
+  # 
+  # Engine internally holds an instance of the java class JRIEngine
+  # which is used for all interaction with R. On top of this it provides
+  # a few abstractions to easily convert between ruby and R types.
+  # 
+  # The main methods of the high level API are {#eval_and_convert} and {#convert_and_assign}.
+  # The high level API converts to/from R/ruby using a type conversion system described 
+  # in the README.
+  #
+  # It also provides a couple of helper methods just to make the users life easier when
+  # working with the lower level java API, most notably {#simple_eval} and {#simple_assign}.
+  # These functions do not convert values but instead work with references to R objects
+  # and are preferred when you don't really care about converting to/from ruby (e.g.
+  # intermediate steps of calculations and similar)
+  # 
+  # Apart from the methods on this ruby class the user can also use any other method
+  # on JRIEngine, it will be forwarded via {#method_missing}.
+  class Engine
+    
+    # Default options used when creating an engine
+    DEFAULT_ENGINE_OPTIONS = {
+      :r_arguments => ["--no-save"],
+      :callback_object => nil,
+      :run_repl => false
+    }
+
+    # Add a custom converter used to convert ruby objects to R objects
+    #
+    # @param [#convert] converter the converter to add
+    # @return [Array] known (class level) converters
+    def self.add_r_converter(converter)
+      @@r_converters ||= []
+      @@r_converters << converter
+    end
+    
+    # Get all class level custom converters to convert ruby objects to R objects
+    #
+    # Converters are returned in the reversed order to how they were added
+    # (i.e. the last added is applied first)
+    #
+    # @return [Array] all class level custom converters
+    def self.r_converters
+      @@r_converters ||= []
+      @@r_converters.reverse
+    end
+
+    # Clear all class level custom R converters
+    def self.clear_r_converters
+      @@r_converters = []
+    end
+    
+    # Get default converters to convert ruby objects to R objects
+    #
+    # @return [Array] all default converters
+    def self.default_r_converters
+      [
+        RConverters::FloatConverter.new,
+        RConverters::IntegerConverter.new,
+        RConverters::StringConverter.new,
+        RConverters::ArrayConverter.new
+      ]
+    end
+
+    # Add a custom converter used to convert R objects to ruby objects
+    #
+    # @param [#convert] converter the converter to add
+    # @return [Array] known (class level) converters
+    def self.add_ruby_converter(converter)
+      @@ruby_converters ||= []
+      @@ruby_converters << converter
+    end
+    
+    # Get all class level custom converters to convert R objects to ruby objects
+    #
+    # Converters are returned in the reversed order to how they were added
+    # (i.e. the last added is applied first)
+    #
+    # @return [Array] all class level custom converters
+    def self.ruby_converters
+      @@ruby_converters ||= []
+      @@ruby_converters.reverse
+    end
+
+    # Clear all class level custom ruby converters
+    def self.clear_ruby_converters
+      @@ruby_converters = []
+    end
+
+    # Get default converters to convert R objects to ruby objects
+    #
+    # @return [Array] all default converters
+    def self.default_ruby_converters
+      [
+        RubyConverters::DoubleConverter.new,
+        RubyConverters::IntegerConverter.new,
+        #RubyConverters::StringConverter.new,
+      ]
+    end
+
+    # Helper to make sure all engines are finalized so the R thread dies as it should
+    #
+    # @param engine engine to finalize
+    # @return [Proc] that closes the engine
+    def self.finalize(engine)
+      proc { engine.close }
+    end
+    
+    # Create a new instance of Engine
+    # 
+    # @param [Hash] options A Hash of options to override the defaults, or not given
+    #   in which case the defaults will be used.
+    def initialize(options = {})
+      combined_options = DEFAULT_ENGINE_OPTIONS.merge(options)
+      
+      @engine = Jri::JRIEngine.new(combined_options[:r_arguments].to_java(:string),
+                                   combined_options[:callback_object],
+                                   combined_options[:run_repl])
+                                  
+      # the R thread wont die unless we call #close on @engine, so make sure this
+      # happens when this object is finalized.
+      ObjectSpace.define_finalizer(self, self.class.finalize(@engine))
+    end
+
+    # Forward any method calls not recognized to JRIEngine
+    def method_missing(method, *args, &block)
+      if @engine.respond_to? method
+        @engine.send(method, *args, &block)
+      else
+        super
+      end
+    end
+
+    # Add a custom converter used to convert ruby objects to R objects
+    #
+    # @param [#convert] converter the converter to add
+    # @return [Array] known (instance level) converters
+    def add_r_converter(converter)
+      @r_converters ||= []
+      @r_converters << converter
+    end
+    
+    # Get all instance level custom converters to convert ruby objects to R objects
+    #
+    # Converters are returned in the reversed order to how they were added
+    # (i.e. the last added is applied first)
+    #
+    # @return [Array] all instance level custom converters
+    def r_converters
+      @r_converters ||= []
+      @r_converters.reverse
+    end
+
+    # Clear all instance level custom R converters
+    def clear_r_converters
+      @r_converters = []
+    end
+    
+    # Add a custom converter used to convert R objects to ruby objects
+    #
+    # @param [#convert] converter the converter to add
+    # @return [Array] known (instance level) converters
+    def add_ruby_converter(converter)
+      @ruby_converters ||= []
+      @ruby_converters << converter
+    end
+
+    # Clear all instance level custom R converters
+    def clear_ruby_converters
+      @ruby_converters = []
+    end
+
+    # Get all instance level custom converters to convert R objects to ruby objects
+    #
+    # Converters are returned in the reversed order to how they were added
+    # (i.e. the last added is applied first)
+    #
+    # @return [Array] all instance level custom converters
+    def ruby_converters
+      @ruby_converters ||= []
+      @ruby_converters.reverse
+    end
+    
+    # Helper method to evaluate expressions but avoid any R-to-ruby conversions
+    # 
+    # Always uses the global environment and returns an R reference which the
+    # user can pass along to other R functions later on.
+    # 
+    # @param [String] expression the R expression to evaluate
+    # @return [REXPReference] reference to the result of the expression
+    def simple_eval(expression)
+      parsed_expression = @engine.parse(expression, false)
+      @engine.eval(parsed_expression, nil, false)
+    end
+    
+    # Eval expression and convert result to the corresponding ruby type
+    #
+    # @param [String] expression the R epxression to evaluate
+    # @return the result converted to the corresponding ruby type
+    def eval_and_convert(expression)
+      success, value = convert_to_ruby_object(@engine.parseAndEval(expression))
+      raise RriException.new("Failed to convert R object to ruby object for: #{value}") unless success
+      value
+    end
+
+    # Helper method to assign expressions to R variables
+    # 
+    # Always uses the global environment.
+    # 
+    # @param [#to_s] symbol what to call the R variable
+    # @return [nil]
+    def simple_assign(symbol, rexp)
+      @engine.assign(symbol.to_s, rexp, nil)
+    end
+    
+    # Convert a ruby value to an R type and assign it to an R variable.
+    #
+    # @param obj ruby object to convert and assign to R varible
+    # @param [#to_s] symbol what to call the R variable
+    # @return [nil]
+    def convert_and_assign(obj, symbol)
+      success, rexp = convert_to_r_object(obj)
+      raise RriException.new("Failed to convert ruby object to R object for: #{obj}") unless success
+      simple_assign(symbol, rexp)
+    end
+    
+    # Helper method to get a variable from R
+    #
+    # Always uses the global environment.
+    # 
+    # @param [#to_s] symbol name of the R variable to get
+    # @return [REXPReference] reference to the R variable
+    def simple_get(symbol)
+      @engine.get(symbol.to_s, nil, false)
+    end
+
+    # Get a variable from R and convert it to a ruby object
+    #
+    # Always uses the global environment.
+    # 
+    # @param [#to_s] symbol name of the R variable to get
+    # @return the R variable converted to a ruby object
+    def get_and_convert(symbol)
+      rexp = @engine.get(symbol.to_s, nil, true)
+      success, value = convert_to_ruby_object(rexp)
+      raise RriException.new("Failed to convert R object to ruby object for: #{value}") unless success
+      value
+    end
+    
+    # Convert a ruby object to a R object
+    #
+    # Applies converters in 3 levels:
+    # * custom converters that is set for only this engine instance
+    # * custom converters that are set for all engine instances
+    # * default converters
+    #
+    # Converters are applied in the reverse order they were added in.
+    #
+    # @param obj ruby object to convert
+    # @return [Array] an array of size 2 where first element is a boolean indicating succes,
+    #   and the second element is the converted object if conversion successful (otherwise
+    #   the original obj)
+    def convert_to_r_object(obj)
+      # first try converters defined for just this instance
+      success, value = apply_local_r_converters(obj)
+      return [success, value] if success
+
+      # then try converters defined in general
+      success, value = apply_r_converters(obj)
+      return [success, value] if success
+
+      # and finally apply the default converters   
+      success, value = apply_default_r_converters(obj)
+      return [success, value] if success
+
+      # give up
+      [false, obj]
+    end
+
+    # Convert an R object to a ruby object
+    #
+    # Applies converters in 3 levels:
+    # * custom converters that is set for only this engine instance
+    # * custom converters that are set for all engine instances
+    # * default converters
+    #
+    # Converters are applied in the reverse order they were added in.
+    #
+    # @param [REXP] rexp R object to convert
+    # @return [Array] an array of size 2 where first element is a boolean indicating succes,
+    #   and the second element is the converted object if conversion was successful (otherwise
+    #   the original rexp)
+    def convert_to_ruby_object(rexp)
+      # first try converters defined for just this instance
+      success, value = apply_local_ruby_converters(rexp)
+      return [success, value] if success
+
+      # then try converters defined in general
+      success, value = apply_ruby_converters(rexp)
+      return [success, value] if success
+
+      # and finally apply the default converters   
+      success, value = apply_default_ruby_converters(rexp)
+      return [success, value] if success
+
+      # give up
+      [false, rexp]
+    end
+
+    ############################ PRIVATE METHODS ##############################
+
+    private
+
+    # Helper method to apply converters
+    #
+    # @param [Array] converters array of converters to try to apply
+    # @param obj object to try to convert
+    # @return [Array] an array of size 2 where first element is a boolean indicating succes,
+    #   and the second element is the converted object if conversion was successful    
+    def apply_converters(converters, obj)
+      converters.each do |converter|
+        success, value = converter.convert(obj)
+        return [success, value] if success
+      end
+      # if no success, return failure and nil for value
+      [false, nil]
+    end
+      
+    # Apply custom converters that are defined just for this engine to a ruby object
+    #
+    # @param obj ruby object to convert to R type
+    # @return [Array] an array of size 2 where first element is a boolean indicating succes,
+    #   and the second element is the converted object if conversion was successful
+    def apply_local_r_converters(obj)
+      apply_converters(r_converters, obj)
+    end
+
+    # Apply custom converters that are defined for all engines to a ruby object
+    #
+    # @param obj ruby object to convert to R type
+    # @return [Array] an array of size 2 where first element is a boolean indicating succes,
+    #   and the second element is the converted object if conversion was successful
+    def apply_r_converters(obj)
+      apply_converters(Engine.r_converters, obj)
+    end
+
+    # Apply default converters to ruby object
+    #
+    # @param obj ruby object to convert to R type
+    # @return [Array] an array of size 2 where first element is a boolean indicating succes,
+    #   and the second element is the converted object if conversion was successful
+    def apply_default_r_converters(obj)
+      apply_converters(Engine.default_r_converters, obj)
+    end
+
+    # Apply custom converters that are defined just for this engine to an R object
+    #
+    # @param [REXP] rexp object to convert to ruby object
+    # @return [Array] an array of size 2 where first element is a boolean indicating succes,
+    #   and the second element is the converted object if conversion was successful
+    def apply_local_ruby_converters(rexp)
+      apply_converters(ruby_converters, rexp)
+    end
+
+    # Apply custom converters that are defined for all engines to an R object
+    #
+    # @param [REXP] rexp R object to convert to ruby object
+    # @return [Array] an array of size 2 where first element is a boolean indicating succes,
+    #   and the second element is the converted object if conversion was successful
+    def apply_ruby_converters(rexp)
+      apply_converters(Engine.ruby_converters, rexp)
+    end
+
+    # Apply default converters to R object
+    #
+    # @param [REXP] rexp R object to convert to ruby object
+    # @return [Array] an array of size 2 where first element is a boolean indicating succes,
+    #   and the second element is the converted object if conversion was successful
+    def apply_default_ruby_converters(rexp)
+      apply_converters(Engine.default_ruby_converters, rexp)
+    end
+
+  end
+end