rust 0.7 → 0.11

data/lib/{rust-effsize.rb → rust/stats/effsize.rb}

@@ -1,10 +1,15 @@
-require 'code-assertions'
+require_relative '../core'
 
-Rust.exclusive do
-    Rust._eval("library(effsize)")
-end
+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
@@ -16,11 +21,16 @@ module Rust::EffectSize
             return "#{name} = #{estimate} (#{magnitude}) [#{confidence_interval.min}, #{confidence_interval.max}]"
         end
     end
-end
 
-module Rust::EffectSize::CliffDelta
-    class << self
-        def compute(d1, d2)
+    ##
+    # 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) }
             
@@ -45,11 +55,16 @@ module Rust::EffectSize::CliffDelta
             end
         end
     end
-end
-
-module Rust::EffectSize::CohenD
-    class << self
-        def compute(d1, d2)
+    
+    ##
+    # 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) }
             

data/lib/{rust-probabilities.rb → rust/stats/probabilities.rb}

@@ -1,7 +1,11 @@
-require_relative 'rust-core'
+require_relative '../core'
 
 class Numeric
-    def distance(other)
+    
+    ##
+    # Computes the distance between this and another number.
+    
+    def _rust_prob_distance(other)
         raise TypeError, "no implicit conversion of #{other.class} into Numeric" unless other.is_a? Numeric
         
         return (self - other).abs
@@ -9,14 +13,18 @@ class Numeric
 end
 
 class Array
-    def distance(other)
+    
+    ##
+    # Computes the distance between this and another array.
+    
+    def _rust_prob_distance(other)
         raise TypeError, "no implicit conversion of #{other.class} into Array" unless other.is_a? Array
         
         longest, shortest = self.size > other.size ? [self, other] : [other, self]
         
         distance = 0
         for i in 0...longest.size
-            distance += longest[i].to_i.distance(shortest[i].to_i)
+            distance += longest[i].to_i._rust_prob_distance(shortest[i].to_i)
         end
         
         return distance
@@ -24,21 +32,37 @@ class Array
 end
 
 class String
-    def distance(other)
+    
+    ##
+    # Computes the distance between this and another string.
+    
+    def _rust_prob_distance(other)
         raise TypeError, "no implicit conversion of #{other.class} into String" unless other.is_a? String
         
-        return self.bytes.distance other.bytes
+        return self.bytes._rust_prob_distance other.bytes
     end
 end
 
 module Rust
+    
+    ##
+    # Represents a slice of a random variable, for which no check is made in terms of cumulative probability.
+    
     class RandomVariableSlice
+        
+        ##
+        # Creates a new slice of random variable. +values+ is a hash of values associated with their probabilities.
+        
         def initialize(values)
             raise TypeError, "Expected Hash" unless values.is_a?(Hash)
             
             @values = values
         end
         
+        ##
+        # Gets the probability of a value +v+. If +v+ is not specified, returns the cumulative probability of the whole
+        # slice.
+        
         def probability(v=nil)
             unless v
                 return @values.values.sum
@@ -47,48 +71,84 @@ module Rust
             end
         end
         
+        ##
+        # Returns the value with the maximum probability.
+        
         def ml
             @values.max_by { |k, v| v }[0]
         end
         
+        ##
+        # Returns the expected value for this slice.
+        
         def expected
             @values.map { |k, v| k*v }.sum
         end
         
+        ##
+        # Returns a slice with the values that are greater than +n+.
+        
         def >(n)
-            self.so_that { |k| k > n}
+            self.so_that { |k| k > n }
         end
         
+        ##
+        # Returns a slice with the values that are greater than or equal to +n+.
+        
         def >=(n)
-            self.so_that { |k| k >= n}
+            self.so_that { |k| k >= n }
         end
         
+        ##
+        # Returns a slice with the values that are lower than +n+.
+        
         def <(n)
-            self.so_that { |k| k < n}
+            self.so_that { |k| k < n }
         end
         
+        ##
+        # Returns a slice with the values that are lower than or equal to +n+.
+        
         def <=(n)
-            self.so_that { |k| k <= n}
+            self.so_that { |k| k <= n }
         end
         
+        ##
+        # Returns a slice with the value +n+.
+        
         def ==(n)
-            self.so_that { |k| k == n}
+            self.so_that { |k| k == n }
         end
         
-        def so_that
-            RandomVariableSlice.new(@values.select { |k, v| yield(k) })
-        end
+        ##
+        # Returns a slice with the values between +a+ and +b+.
         
         def between(a, b)
-            RandomVariableSlice.new(@values.select { |k, v| k.between? a, b })
+            self.so_that { |k| k.between(a, b) }
+        end
+        
+        ##
+        # Returns a slice with the values for which the given block returns true.
+        
+        def so_that
+            RandomVariableSlice.new(@values.select { |k, v| yield(k) })
         end
     end
+    
+    ##
+    # Represents a random variable. The cumulative probability of the values must equal 1.
 
     class RandomVariable < RandomVariableSlice
         EPSILON = 1e-7
                 
         attr_reader    :values
 
+        ##
+        # Creates a new random variable. +values+ is a hash of values associated with their probabilities.
+        # +exact+ indicates whether this variable, when combined with others, should force to keep all the values, even
+        # the most unlikely ones. If this is +false+ (default), the most improbable values (lower than EPSILON) are 
+        # removed for efficiency reasons.
+        
         def initialize(values = {0 => 1.0}, exact = false)
             @values = values
             @exact = exact
@@ -99,34 +159,46 @@ module Rust
             approx!
         end
 
+        ##
+        # Returns the probability of value +v+.
+        
         def probability(v)
             return @values[v].to_f
         end
 
-        def +(other)
-        new_hash = {}
+        ##
+        # Returns a new random variable which represents the sum of this and the +other+ random variable.
         
-        @values.each do |my_key, my_value|
-            other.values.each do |other_key, other_value|
-                sum_key = my_key + other_key
-                
-                new_hash[sum_key] = new_hash[sum_key].to_f + (my_value * other_value)
+        def +(other)
+            new_hash = {}
+            
+            @values.each do |my_key, my_value|
+                other.values.each do |other_key, other_value|
+                    sum_key = my_key + other_key
+                    
+                    new_hash[sum_key] = new_hash[sum_key].to_f + (my_value * other_value)
+                end
             end
+            
+            return RandomVariable.new(new_hash, @exact)
         end
         
-        return RandomVariable.new(new_hash, @exact)
-        end
+        ##
+        # Based on the type of +arg+, either mul (product with another random variable) or rep (repeated sum) is called.
         
-        def *(times)
-            if times.is_a? Integer
-                return rep(times)
-            elsif times.is_a? RandomVariable
-                return mul(times)
+        def *(arg)
+            if arg.is_a? Integer
+                return rep(arg)
+            elsif arg.is_a? RandomVariable
+                return mul(arg)
             else
                 raise "The argument must be an Integer or a RandomVariable"
             end
         end
         
+        ##
+        # Returns a new random variable which represents the product of this and the +other+ random variable.
+        
         def mul(other)
             new_hash = {}
         
@@ -141,6 +213,9 @@ module Rust
             return RandomVariable.new(new_hash, @exact)
         end
         
+        ##
+        # Returns a new random variable which represents the sum of this random variable with itself +n+ times.
+        
         def rep(times)
             rv = self
             (times-1).times do
@@ -150,10 +225,16 @@ module Rust
             return rv
         end
         
+        ##
+        # Makes sure that the operations yield all the values, even the most unlikely ones.
+        
         def exact!
             @exact = true
         end
         
+        ##
+        # If this variable is not exact, the values with probability lower than EPSLION are removed.
+        
         def approx!
             return if @exact
             
@@ -164,35 +245,56 @@ module Rust
             
             to_delete.each do |v| 
                 probability = @values.delete v
-                nearest = @values.keys.min_by { |k| k.distance v }
+                nearest = @values.keys.min_by { |k| k._rust_prob_distance v }
                 @values[nearest] += probability
             end
         end
         
+        ##
+        # Returns a random value, according to the data distribution.
+        
         def extract
             v = rand
             
             cumulative = 0
-            @values.each do |key, prob|
+            @values.sort_by { |k, v| k }.each do |key, prob|
                 cumulative += prob
                 
                 return key if cumulative >= v
             end
         end
         
+        ##
+        # Creates a random variable by partially specifying the values through +hash+. The remaining probability is 
+        # attributed to +key+ (0, by default).
+        
         def self.complete(hash, key=0)
             hash[key] = 1 - hash.values.sum
             return RandomVariable.new(hash)
         end
     end
 
+    ##
+    # Represents a uniform random variable.
+    
     class UniformRandomVariable < RandomVariable
+        
+        ##
+        # Creates random variables for which all the +values+ have the same probability (1 / values.size).
+        
         def initialize(values, exact = false)
             super(values.map { |k| [k, 1.0 / values.size]}.to_h, exact)
         end
     end
 
+    ##
+    # Module that contains utilities for handling random variables.
+    
     module Probabilities
+        
+        ##
+        # Computes the probability of the random variable +v+.
+        
         def P(v)
             if v.is_a? RandomVariableSlice
                 raise "Cannot compute the probability of a random variable" if v.is_a? RandomVariable
@@ -202,6 +304,9 @@ module Rust
             end
         end
         
+        ##
+        # Computes the expected value of the random variable +v+.
+        
         def E(v)
             if v.is_a? RandomVariableSlice
                 return v.expected
@@ -211,7 +316,10 @@ module Rust
         end
     end
     
-    class RandomVariable
+    ##
+    # Module containing examples of commonly-used random variables.
+    
+    module RandomVariableExamples
         ENGLISH_ALPHABET = RandomVariable.new({
             "a" => 0.08167,
             "b" => 0.01492,
@@ -240,9 +348,9 @@ module Rust
             "y" => 0.01974, 
             "z" => 0.00074
         })
-        
+            
         DICE = UniformRandomVariable.new([1, 2, 3, 4, 5, 6])
-        
+            
         COIN = UniformRandomVariable.new(["h", "t"])
     end
 end