rust 0.9 → 0.10

data/lib/rust/core/types/factor.rb

@@ -1,6 +1,10 @@
 require_relative 'datatype'
 
 module Rust
+    
+    ##
+    # Mirror of the factor type in R.
+    
     class Factor < RustDatatype
         def self.can_pull?(type, klass)
             return klass == "factor"
@@ -20,11 +24,17 @@ module Rust
             Rust._eval("#{variable_name} <- factor(tmp.values, labels=tmp.levels)")
         end
         
+        ##
+        # Creates a new factor given an array of numeric +values+ and symbolic +levels+.
+        
         def initialize(values, levels)
             @levels = levels.map { |v| v.to_sym }
             @values = values
         end
         
+        ##
+        # Returns the levels of the factor.
+        
         def levels
             @levels
         end
@@ -35,10 +45,17 @@ module Rust
             return @levels == other.levels && self.to_a == other.to_a
         end
         
+        ##
+        # Returns the value of the +i+-th element in the factor.
+        
         def [](i)
             FactorValue.new(@values[i], @levels[@values[i] - 1])
         end
         
+        ##
+        # Sets the +value+ of the +i+-th element in the factor. If it is an Integer, the +value+ must be between 1 and 
+        # the number of levels of the factor. +value+ can be either a FactorValue or a String/Symbol.
+        
         def []=(i, value)
             raise "The given value is outside the factor bounds" if value.is_a?(Integer) && (value < 1 || value > @levels.size)
             
@@ -57,6 +74,9 @@ module Rust
             @values[i] = value
         end
         
+        ##
+        # Returns an array of FactorValue for the values in this factor.
+        
         def to_a
             @values.map { |v| FactorValue.new(v, @levels[v - 1]) }
         end
@@ -76,7 +96,14 @@ module Rust
         end
     end
     
+    ##
+    # Represents a single value in a factor.
+    
     class FactorValue
+        
+        ##
+        # Creates a factor with a given +value+ (numeric) and +level+ (symbolic).
+        
         def initialize(value, level)
             @value = value
             @level = level

data/lib/rust/core/types/language.rb

@@ -1,6 +1,10 @@
 require_relative 'datatype'
 
 module Rust
+    
+    ##
+    # Mirror of the formula type in R.
+    
     class Formula < RustDatatype
         def self.can_pull?(type, klass)
             return klass == "formula" || (klass.is_a?(Array) && klass.include?("formula"))
@@ -24,6 +28,9 @@ module Rust
         attr_reader     :left_part
         attr_reader     :right_part
         
+        ##
+        # Creates a new formula with a given +left_part+ (optional) and +right_part+ (as strings). 
+        
         def initialize(left_part, right_part)
             raise ArgumentError, "Expected string" if left_part && !left_part.is_a?(String)
             raise ArgumentError, "Expected string" if !right_part.is_a?(String)
@@ -46,7 +53,10 @@ module Rust
             return self.to_R.strip
         end
     end
-        
+    
+    ##
+    # Mirror of the call type in R.
+    
     class Call < RustDatatype
         def self.can_pull?(type, klass)
             return klass == "call"
@@ -61,6 +71,9 @@ module Rust
             Rust._eval("#{variable_name} <- str2lang(call.str)")
         end
         
+        ##
+        # Creates a new call with the given +value+ (String).
+        
         def initialize(value)
             @value = value
         end
@@ -74,6 +87,9 @@ module Rust
         end
     end
     
+    ##
+    # Mirror of the environment type in R. Currently not supported.
+    
     class Environment < RustDatatype
         def self.can_pull?(type, klass)
             return type == "environment" && klass == "environment"
@@ -90,23 +106,36 @@ module Rust
         end
     end
     
+    ##
+    # Represents a function call in R. After having set up its name (constructor) and, optionally, its arguments
+    # and options, it can be used the call method to execute it in the R environment.
+    
     class Function
         attr_reader     :name
         attr_reader     :arguments
         attr_reader     :options
         
+        ##
+        # Creates a new function with a given +name+.
+        
         def initialize(name)
             @function = name
             @arguments  = Arguments.new
             @options    = Options.new
         end
         
+        ##
+        # Sets the +options+ (Options type) of the function.
+        
         def options=(options)
             raise TypeError, "Expected Options" unless options.is_a?(Options)
             
             @options = options
         end
         
+        ##
+        # Sets the +arguments+ (Arguments type) of the function.
+        
         def arguments=(arguments)
             raise TypeError, "Expected Arguments" unless options.is_a?(Arguments)
             
@@ -118,23 +147,21 @@ module Rust
             return "#@function(#{params})"
         end
         
+        ##
+        # Calls the function in the R environment.
+        
         def call
             Rust._eval(self.to_R)
         end
     end
     
-    class SimpleFormula
-        def initialize(dependent, independent)
-            @dependent = dependent
-            @independent = independent
-        end
-        
-        def to_R
-            return "#@dependent ~ #@independent"
-        end
-    end
+    ##
+    # Represents an R variable.
     
     class Variable
+        ##
+        # Creates a variable with the given +name+.
+        
         def initialize(name)
             @name = name
         end
@@ -144,12 +171,18 @@ module Rust
         end
     end
     
+    ##
+    # Represents the arguments of a function in R. Works as an Array of objects.
+    
     class Arguments < Array
         def to_R
             return self.map { |v| v.to_R }.join(", ")
         end
     end
     
+    ##
+    # Represents the options of a function in R. Works as a Hash associating option names to objects.
+    
     class Options < Hash
         def to_R
             return self.map { |k, v| "#{k}=#{v.to_R}" }.join(", ")

data/lib/rust/core/types/list.rb

@@ -1,6 +1,10 @@
 require_relative 'datatype'
 
 module Rust
+    
+    ##
+    # Mirror of the list type in R.
+    
     class List < RustDatatype
         def self.can_pull?(type, klass)
             return type == "list"
@@ -27,12 +31,18 @@ module Rust
             end
         end
         
+        ##
+        # Creates an empty list of a given class (+klass+) and the specified +names+.
+        
         def initialize(klass, names = [])
             @data = {}
             @names = names
             @klass = klass
         end
         
+        ##
+        # Returns the elements for the name +key+.
+        
         def [](key)
             key = get_key(key)
             
@@ -40,12 +50,18 @@ module Rust
         end
         alias :| :[]
         
+        ##
+        # Sets the +value+ for name +key+.
+        
         def []=(key, value)
             key = get_key(key)
             
             return @data[key] = value
         end
         
+        ##
+        # Returns the names of the list.
+        
         def names
             @names
         end

data/lib/rust/core/types/matrix.rb

@@ -1,6 +1,10 @@
 require_relative 'datatype'
 
 module Rust
+    
+    ##
+    # Mirror of the matrix type in R.
+    
     class Matrix < RustDatatype
         def self.can_pull?(type, klass)
             return klass.is_a?(Array) && klass.include?("matrix")
@@ -27,6 +31,10 @@ module Rust
             Rust[variable_name] = matrix
         end
         
+        ##
+        # Creates a new matrix with the given +data+ (Ruby Matrix). Optionally, +row_names+ and +column_names+ can 
+        # be specified.
+        
         def initialize(data, row_names = nil, column_names = nil)
             @data = data.clone
             
@@ -48,30 +56,45 @@ module Rust
             end
         end
         
+        ##
+        # Returns the matrix element at row +i+ and column +j+.
+        
         def [](i, j)
             i, j = indices(i, j)
             
             return @data[i][j]
         end
         
+        ##
+        # Sets the matrix element at row +i+ and column +j+ with +value+.
+        
+        def []=(i, j, value)
+            i, j = indices(i, j)
+            
+            @data[i][j] = value
+        end
+        
+        ##
+        # Returns the number of rows.
+        
         def rows
             @data.size
         end
         
+        ##
+        # Returns the number of columns.
+        
         def cols
             @data[0].size
         end
         
+        ##
+        # Returns a flattened version of the matrix (Array).
+        
         def flatten
             return @data.flatten
         end
         
-        def []=(i, j, value)
-            i, j = indices(i, j)
-            
-            @data[i][j] = value
-        end
-        
         def inspect
             row_names = @row_names || (0...self.rows).to_a.map { |v| v.to_s }
             column_names = @column_names || (0...self.cols).to_a.map { |v| v.to_s }

data/lib/rust/core/types/s4class.rb

@@ -1,6 +1,10 @@
 require_relative 'datatype'
 
 module Rust
+    
+    ##
+    # Mirror for the S4 class in R.
+    
     class S4Class < RustDatatype
         def self.can_pull?(type, klass)
             return type == "S4"
@@ -20,6 +24,9 @@ module Rust
             "immutable"
         end
         
+        ##
+        # Creates a new S4 element, given its +variable_name+, class name (+klass+), and +slots+.
+        
         def initialize(variable_name, klass, slots)
             @klass = klass
             @slots = slots
@@ -27,6 +34,9 @@ module Rust
             self.r_mirror_to(variable_name)
         end
         
+        ##
+        # Returns the slot +key+ for the class name (+klass+).
+        
         def [](key)
             raise ArgumentError, "Unknown slot `#{key}` for class `#@klass`" unless @slots.include?(key)
             
@@ -36,6 +46,9 @@ module Rust
         end
         alias :| :[]
         
+        ##
+        # Returns the slot +key+ for the class name (+klass+) with +value+.
+        
         def []=(key, value)
             raise ArgumentError, "Unknown slot `#{key}` for class `#@klass`" unless @slots.include?(key)
             
@@ -44,10 +57,16 @@ module Rust
             end
         end
         
+        ##
+        # Returns the slots.
+        
         def slots
             @slots
         end
         
+        ##
+        # Returns the class name.
+        
         def class_name
             @klass
         end

data/lib/rust/core/types/utils.rb

@@ -1,6 +1,10 @@
 require_relative 'datatype'
 
 module Rust
+    
+    ##
+    # Represents a sequence of values in R (through a call to the seq function).
+    
     class Sequence < RustDatatype
         attr_reader :min
         attr_reader :max
@@ -9,15 +13,24 @@ module Rust
             return false
         end
         
+        ##
+        # Creates a new sequence from +min+ to +max+ with a given +step+ (default = 1).
+        
         def initialize(min, max, step=1)
             @min = min
             @max = max
             @step = step
         end
         
-        def step(step)
+        ##
+        # Sets the step to +step+.
+        
+        def step=(step)
             @step = step
+            
+            return self
         end
+        alias :step :step=
         
         def each
             (@min..@max).step(@step) do |v|

data/lib/rust/models/anova.rb

@@ -1,6 +1,10 @@
 require_relative '../core'
 
 module Rust
+    
+    ##
+    # Mirror for an ANOVA model type in R. To create a new ANOVA model (aov), call the #generate method.
+    
     class ANOVAModel < RustDatatype
         def self.can_pull?(type, klass)
             return type == "list" && [klass].flatten.include?("aov")
@@ -16,6 +20,10 @@ module Rust
             @model.load_in_r_as(variable_name)
         end
         
+        ##
+        # Generates a new ANOVA model with a given +formula+, +data+. +options+ can be specified and directly passed
+        # to the aov function in R.
+        
         def self.generate(formula, data, **options)
             mapped = ""
             if options.size > 0
@@ -32,14 +40,23 @@ module Rust
             end
         end
         
+        ##
+        # Creates a new +model+.
+        
         def initialize(model)
             @model = model
         end
         
+        ##
+        # Returns the model.
+        
         def model
             @model
         end
         
+        ##
+        # Returns a summary of the ANOVA model through the summary function in R.
+        
         def summary
             unless @summary
                 Rust.exclusive do

data/lib/rust/models/regression.rb

@@ -5,7 +5,14 @@ require_relative '../stats/correlation'
 module Rust::Models
 end
 
+##
+# Contains classes that allow to run regression models.
+
 module Rust::Models::Regression
+    
+    ##
+    # Generic regression model in R.
+    
     class RegressionModel < Rust::RustDatatype
         def self.can_pull?(type, klass)
             # Can only pull specific sub-types
@@ -16,6 +23,11 @@ module Rust::Models::Regression
             @model.load_in_r_as(variable_name)
         end
 
+        ##
+        # Generates a new regression model. +object_type+ is the Ruby class of the model object; +model_type+ represents 
+        # the type of model at hand; +dependent_variable+ and +independent_variables+ are directly used as part of the 
+        # model formula. +data+ represents the dataset to be used. +options+ can be specified and directly passed to the
+        # model.
         
         def self.generate(object_type, model_type, dependent_variable, independent_variables, data, **options)
             mapped = ""
@@ -36,6 +48,9 @@ module Rust::Models::Regression
                 return result
             end
         end
+        
+        ##
+        # Creates a new +model+.
             
         def initialize(model)
             raise StandardError if model.is_a?(RegressionModel)
@@ -46,6 +61,9 @@ module Rust::Models::Regression
             @model
         end
         
+        ##
+        # Returns the residuals of the model.
+        
         def residuals
             Rust.exclusive do
                 @residuals = Rust["residuals(#{self.r_mirror})"] unless @residuals
@@ -54,6 +72,9 @@ module Rust::Models::Regression
             return @residuals
         end
         
+        ##
+        # Returns the fitted values of the model.
+        
         def fitted
             Rust.exclusive do
                 @fitted = Rust["fitted(#{self.r_mirror})"] unless @fitted
@@ -62,22 +83,37 @@ module Rust::Models::Regression
             return @fitted
         end
         
+        ##
+        # Returns the actual values in the dataset.
+        
         def actuals            
             return self.fitted.zip(self.residuals).map { |couple| couple.sum }
         end
         
+        ##
+        # Returns the r-squared of the model.
+        
         def r_2
             return self.summary|"r.squared"
         end
         
+        ##
+        # Returns the adjusted r-squared of the model.
+        
         def r_2_adjusted
             return self.summary|"adj.r.squared"
         end
         
+        ##
+        # Returns the mean squared error of the model.
+        
         def mse
             Rust::Descriptive.variance(self.residuals)
         end
         
+        ##
+        # Returns the coefficients of the model.
+        
         def coefficients
             a = self.summary|"coefficients"
         end
@@ -86,6 +122,9 @@ module Rust::Models::Regression
             return model|name.to_s
         end
         
+        ##
+        # Returns a summary for the model using the summary function in R.
+        
         def summary
             unless @summary
                 Rust.exclusive do
@@ -101,6 +140,9 @@ module Rust::Models::Regression
         end
     end
     
+    ##
+    # Represents a linear regression model in R.
+    
     class LinearRegressionModel < RegressionModel
         def self.can_pull?(type, klass)
             return type == "list" && klass == "lm"
@@ -112,6 +154,10 @@ module Rust::Models::Regression
             return LinearRegressionModel.new(model)
         end
         
+        ##
+        # Generates a linear regression model, given its +dependent_variable+ and +independent_variables+ and its +data+. 
+        # +options+ can be specified and directly passed to the model. 
+        
         def self.generate(dependent_variable, independent_variables, data, **options)
             RegressionModel.generate(
                 LinearRegressionModel,
@@ -124,6 +170,9 @@ module Rust::Models::Regression
         end
     end
     
+    ##
+    # Represents a linear mixed effects model in R.
+    
     class LinearMixedEffectsModel < RegressionModel
         def self.can_pull?(type, klass)
             return type == "S4" && klass == "lmerModLmerTest"
@@ -152,6 +201,10 @@ module Rust::Models::Regression
             return @summary
         end
         
+        ##
+        # Generates a linear mixed effects model, given its +dependent_variable+ and +independent_variables+ and its +data+. 
+        # +options+ can be specified and directly passed to the model. 
+        
         def self.generate(dependent_variable, fixed_effects, random_effects, data, **options)
             Rust.prerequisite("lmerTest")
             Rust.prerequisite("rsq")
@@ -169,7 +222,7 @@ module Rust::Models::Regression
         end
         
         def r_2
-        Rust.exclusive do
+            Rust.exclusive do
                 Rust._eval("tmp.rsq <- rsq(#{self.r_mirror}, adj=F)")
                 return Rust['tmp.rsq']
             end

data/lib/rust/plots/basic-plots.rb

@@ -1,7 +1,16 @@
 require_relative 'core'
 
 module Rust::Plots
+    
+    ##
+    # Allows to create one or many scatter plots.
+    
     class ScatterPlot < BasePlot
+        
+        ##
+        # Creates a new scatter plot, given two arrays of values +x+ and +y+ for the respective axes (optional).
+        # +options+ can be specified and directly passed to the plot function in R.
+        
         def initialize(x = nil, y = nil, **options)
             super()
             @series = []
@@ -10,30 +19,46 @@ module Rust::Plots
             end
         end
         
+        ##
+        # Adds a new data series, given the values for the +x+ and +y+ axes.
+        # +options+ can be specified and directly passed to the plot function in R.
+        
         def series(x, y, **options)
             @series << [x, y, options]
             
             return self
         end
         
+        ##
+        # Sets the thickness of the plot lines.
+        
         def thickness(t)
             self['lwd'] = t
             
             return self
         end
         
+        ##
+        # Changes the plot type to lines.
+        
         def lines()
             self['type'] = "l"
             
             return self
         end
         
+        ##
+        # Changes the plot type to points.
+        
         def points()
             self['type'] = "p"
             
             return self
         end
         
+        ##
+        # Changes the plot type to lines and points.
+        
         def lines_and_points()
             self['type'] = "b"
             
@@ -86,7 +111,14 @@ module Rust::Plots
         end
     end
     
+    ##
+    # Represents a bar plot in R.
+    
     class BarPlot < BasePlot
+        
+        ##
+        # Creates a new bar plot with the given +bars+ values.
+        
         def initialize(bars)
             super()
             @bars = bars