rust 0.9 → 0.12

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

data/lib/rust/plots/core.rb

@@ -1,25 +1,45 @@
 require_relative '../core'
 
+##
+# Module that contains classes for plotting.
+
 module Rust::Plots
+    
+    ##
+    # Represents a generic plot in R.
+    
     class BasePlot
+        
+        ##
+        # Creates a new base plot object.
+        
         def initialize
             @renderables = []
             @options = Rust::Options.new
             @override_options = true
         end
         
+        ##
+        # Sets the x-axis label.
+        
         def x_label(label)
             @options['xlab'] = label
             
             return self
         end
         
+        ##
+        # Sets the y-axis label.
+        
         def y_label(label)
             @options['ylab'] = label
             
             return self
         end
         
+        ##
+        # Returns a color palette of the given +size+.
+        
         def palette(size)
             if size <= 1
                 return ['black']
@@ -28,17 +48,28 @@ module Rust::Plots
             end
         end
         
+        ##
+        # Sets the limits for the x-axis.
+        
         def x_range(range)
             @options['xlim'] = range
             
             return self
         end
+        alias :xlim :x_range
+        
+        ##
+        # Sets the limits for the y-axis.
         
         def y_range(range)
             @options['ylim'] = range
             
             return self
         end
+        alias :ylim :y_range
+        
+        ##
+        # Adds an +axis+ to show instead of the default ones.
         
         def axis(axis)
             @options['xaxt'] = 'n'
@@ -49,18 +80,27 @@ module Rust::Plots
             return self
         end
         
+        ##
+        # Shows the given +grid+.
+        
         def grid(grid)
             self._add_renderable(grid)
             
             return self
         end
         
+        ##
+        # Sets the +title+ of the plot.
+        
         def title(title)
             @options['main'] = title
             
             return self
         end
         
+        ##
+        # Sets the +color+ of the plot.
+        
         def color(color)
             @options['col'] = color
             
@@ -74,6 +114,9 @@ module Rust::Plots
             return self
         end
         
+        ##
+        # Sets any R +option+ with the given +value+.
+        
         def []=(option, value)
             @options[option.to_s] = value
         end
@@ -82,6 +125,9 @@ module Rust::Plots
             @override_options = false
         end
         
+        ##
+        # Shows the plot in a window.
+        
         def show()
             Rust.exclusive do
                 self._show
@@ -91,6 +137,9 @@ module Rust::Plots
             return self
         end
         
+        ##
+        # Prints the plot on a PDF file at path. +options+ can be specified for the PDF (e.g., width and height).
+        
         def pdf(path, **options)
             pdf_function = Rust::Function.new("pdf")
             pdf_function.options = Rust::Options.from_hash(options)
@@ -133,11 +182,21 @@ module Rust::Plots
         end
     end
     
+    ##
+    # Represents any element that can be rendered in a plot (e.g., axes or grids).
+    
     class Renderable
+        
+        ##
+        # Creates a new empty renderable object.
+        
         def initialize
             @options = Rust::Options.new
         end
         
+        ##
+        # Sets an option for the renderable object.
+        
         def []=(option, value)
             @options[option] = value
             
@@ -150,12 +209,18 @@ module Rust::Plots
         end
     end
     
+    ##
+    # Represents an axis for a plot.
+    
     class Axis < Renderable
         BELOW = 1
         LEFT  = 2
         ABOVE = 3
         RIGHT = 4
         
+        ##
+        # Creates a new axis at the given +side+ (constants BELOW, LEFT, ABOVE, and RIGHT are available).
+        
         def initialize(side)
             super()
             
@@ -198,7 +263,14 @@ module Rust::Plots
         end
     end
     
+    ##
+    # Represents a grid for a plot.
+    
     class Grid < Renderable
+        
+        ##
+        # Creates a new grid
+        
         def initialize
             super()
             
@@ -206,36 +278,54 @@ module Rust::Plots
             @y = Float::NAN
         end
         
+        ##
+        # Sets the x intervals.
+        
         def x(value)
             @x = value
             
             return self
         end
         
+        ##
+        # Sets the y intervals.
+        
         def y(value)
             @y = value
             
             return self
         end
         
+        ##
+        # Automatically sets the x intervals.
+        
         def auto_x
             @x = nil
             
             return self
         end
         
+        ##
+        # Automatically sets the y intervals.
+        
         def auto_y
             @y = nil
             
             return self
         end
         
+        ##
+        # Hides x axis lines.
+        
         def hide_x
             @x = Float::NAN
             
             return self
         end
         
+        ##
+        # Hides y axis lines.
+        
         def hide_y
             @y = Float::NAN
             

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

@@ -1,12 +1,19 @@
 require_relative 'core'
 
 module Rust::Plots
+    
+    ##
+    # Represents any distribution-related plot (e.g., boxplots).
+    
     class DistributionPlot < BasePlot
         def initialize
             super()
             @series = []
         end
         
+        ##
+        # Adds a series of data points. +options+ can be specified and directly passed to the R plotting function.
+        
         def series(data, **options)
             @series << [data, options]
             
@@ -14,6 +21,9 @@ module Rust::Plots
         end
     end
     
+    ##
+    # Represents a density plot in R.
+    
     class DensityPlot < DistributionPlot
         protected
         def _show()
@@ -38,6 +48,9 @@ module Rust::Plots
         end
     end
     
+    ##
+    # Represents a boxplot in R.
+    
     class BoxPlot < DistributionPlot
         protected
         def _show()

data/lib/rust/stats/correlation.rb

@@ -1,7 +1,18 @@
 require_relative '../core'
 
+##
+# Module containing all the correlation-related statistics.
+
 module Rust::Correlation
+    
+    ##
+    # Pearson correlation utility methods.
+    
     class Pearson
+        
+        ##
+        # Runs the Pearson correlation test between +d1+ and +d2+.
+        
         def self.test(d1, d2)
             raise TypeError, "Expecting Array of numerics" if !d1.is_a?(Array) || !d1.all? { |e| e.is_a?(Numeric) }
             raise TypeError, "Expecting Array of numerics" if !d2.is_a?(Array) || !d2.all? { |e| e.is_a?(Numeric) }
@@ -23,12 +34,22 @@ module Rust::Correlation
             end
         end
         
+        ##
+        # Returns the Pearson correlation index between +d1+ and +d2+
+        
         def self.estimate(d1, d2)
             self.test(d1, d2).correlation
         end
     end
     
+    ##
+    # Spearman correlation utility methods.
+    
     class Spearman
+        
+        ##
+        # Runs the Spearman correlation test between +d1+ and +d2+.
+        
         def self.test(d1, d2)
             raise TypeError, "Expecting Array of numerics" if !d1.is_a?(Array) || !d1.all? { |e| e.is_a?(Numeric) }
             raise TypeError, "Expecting Array of numerics" if !d2.is_a?(Array) || !d2.all? { |e| e.is_a?(Numeric) }
@@ -50,12 +71,22 @@ module Rust::Correlation
             end
         end
         
+        ##
+        # Returns the Spearman correlation index between +d1+ and +d2+
+        
         def self.estimate(d1, d2)
             self.test(d1, d2).correlation
         end
     end
     
+    ##
+    # Kendall correlation utility methods.
+    
     class Kendall
+        
+        ##
+        # Runs the Kendall correlation test between +d1+ and +d2+.
+        
         def self.test(d1, d2)
             raise TypeError, "Expecting Array of numerics" if !d1.is_a?(Array) || !d1.all? { |e| e.is_a?(Numeric) }
             raise TypeError, "Expecting Array of numerics" if !d2.is_a?(Array) || !d2.all? { |e| e.is_a?(Numeric) }
@@ -77,11 +108,17 @@ module Rust::Correlation
             end
         end
         
+        ##
+        # Returns the Kendall correlation index between +d1+ and +d2+
+        
         def self.estimate(d1, d2)
             self.test(d1, d2).correlation
         end
     end
     
+    ##
+    # Result of a correlation test.
+    
     class Result
         attr_accessor   :name
         attr_accessor   :statistics
@@ -96,10 +133,16 @@ module Rust::Correlation
             @exact = true
         end
         
+        ##
+        # Returns the statistic with the specified +name+.
+        
         def [](name)
             return @statistics[name.to_sym]
         end
         
+        ##
+        # Sets the +value+ for the the statistic with the specified +name+.
+        
         def []=(name, value)
             @statistics[name.to_sym] = value
         end

data/lib/rust/stats/descriptive.rb

@@ -1,13 +1,23 @@
 require_relative '../core'
 
+##
+# Module containing utilities for descriptive statistics.
+
 module Rust::Descriptive
     class << self
+        
+        ##
+        # Computes the arithmetic mean of the given +data+.
+        
         def mean(data)
             raise TypeError, "Expecting Array of numerics" if !data.is_a?(Array) || !data.all? { |e| e.is_a?(Numeric) }
             
             return data.sum.to_f / data.size
         end
         
+        ##
+        # Computes the standard deviation of the given +data+.
+        
         def standard_deviation(data)
             raise TypeError, "Expecting Array of numerics" if !data.is_a?(Array) || !data.all? { |e| e.is_a?(Numeric) }
             
@@ -16,6 +26,9 @@ module Rust::Descriptive
         alias :sd     :standard_deviation
         alias :stddev :standard_deviation
         
+        ##
+        # Computes the variance of the given +data+.
+        
         def variance(data)
             raise TypeError, "Expecting Array of numerics" if !data.is_a?(Array) || !data.all? { |e| e.is_a?(Numeric) }
             return Float::NAN if data.size < 2
@@ -25,6 +38,9 @@ module Rust::Descriptive
         end
         alias :var     :variance
         
+        ##
+        # Computes the median of the given +data+.
+        
         def median(data)
             raise TypeError, "Expecting Array of numerics" if !data.is_a?(Array) || !data.all? { |e| e.is_a?(Numeric) }
             
@@ -39,12 +55,18 @@ module Rust::Descriptive
             end
         end
         
+        ##
+        # Sums the given +data+.
+        
         def sum(data)
             raise TypeError, "Expecting Array of numerics" if !data.is_a?(Array) || !data.all? { |e| e.is_a?(Numeric) }
             
             return data.sum
         end
         
+        ##
+        # Returns the quantiles of the given +data+, given the +percentiles+ (optional).
+        
         def quantile(data, percentiles = [0.0, 0.25, 0.5, 0.75, 1.0])
             raise TypeError, "Expecting Array of numerics" if !data.is_a?(Array) || !data.all? { |e| e.is_a?(Numeric) }
             raise TypeError, "Expecting Array of numerics" if !percentiles.is_a?(Array) || !percentiles.all? { |e| e.is_a?(Numeric) }
@@ -77,10 +99,17 @@ module Rust::Descriptive
             return percentiles.zip(result).to_h
         end
         
+        ##
+        # Returns the outliers in +data+ using Tukey's fences, with a given +k+.
+        
         def outliers(data, k=1.5, **opts)
             outliers_according_to(data, data, k, **opts)
         end
         
+        ##
+        # Returns the outliers in +data+ using Tukey's fences, with a given +k+, with respect to different data
+        # distribution (+data_distribution+).
+        
         def outliers_according_to(data, data_distribution, k=1.5, **opts)
             quantiles = Rust::Descriptive.quantile(data_distribution, [0.25, 0.75])
             q1 = quantiles[0.25]

data/lib/rust/stats/effsize.rb

@@ -2,7 +2,14 @@ require_relative '../core'
 
 Rust.prerequisite('effsize')
 
+##
+# Module containing utilities for computing effect size statistics.
+
 module Rust::EffectSize
+    
+    ##
+    # Effect size results.
+    
     class Result
         attr_accessor   :name
         attr_accessor   :estimate
@@ -15,7 +22,14 @@ module Rust::EffectSize
         end
     end
 
+    ##
+    # Cliff delta effect size statistics.
+    
     class CliffDelta
+        
+        ##
+        # Computes and returns the effect size for +d1+ and +d2+.
+        
         def self.compute(d1, d2)
             raise TypeError, "Expecting Array of numerics" if !d1.is_a?(Array) || !d1.all? { |e| e.is_a?(Numeric) }
             raise TypeError, "Expecting Array of numerics" if !d2.is_a?(Array) || !d2.all? { |e| e.is_a?(Numeric) }
@@ -42,7 +56,14 @@ module Rust::EffectSize
         end
     end
     
+    ##
+    # Cohen D effect size statistics.
+    
     class CohenD
+        
+        ##
+        # Computes and returns the effect size for +d1+ and +d2+.
+        
         def self.compute(d1, d2)
             raise TypeError, "Expecting Array of numerics" if !d1.is_a?(Array) || !d1.all? { |e| e.is_a?(Numeric) }
             raise TypeError, "Expecting Array of numerics" if !d2.is_a?(Array) || !d2.all? { |e| e.is_a?(Numeric) }