ruby-nuggets 0.6.9 → 0.7.0

data/lib/nuggets/array/mode.rb

@@ -0,0 +1,5 @@
+require 'nuggets/array/mode_mixin'
+
+class Array
+  include Nuggets::Array::ModeMixin
+end

data/lib/nuggets/array/mode_mixin.rb

@@ -0,0 +1,70 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of ruby-nuggets, some extensions to the Ruby programming        #
+# language.                                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# ruby-nuggets is free software; you can redistribute it and/or modify it     #
+# under the terms of the GNU General Public License as published by the Free  #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# ruby-nuggets is distributed in the hope that it will be useful, but WITHOUT #
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or       #
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for    #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with ruby-nuggets. If not, see <http://www.gnu.org/licenses/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+require 'nuggets/array/histogram_mixin'
+
+module Nuggets
+  class Array
+    module ModeMixin
+
+  def self.included(base)
+    base.send :include, Nuggets::Array::HistogramMixin
+  end
+
+  # call-seq:
+  #   array.mode => anObject
+  #   array.mode(+true+) => anArray
+  #
+  # Returns the mode[http://en.wikipedia.org/wiki/Mode_%28statistics%29] of
+  # the values in _array_ (via #histogram).
+  #
+  # If parameter +true+ is passed, an Array of all modes is returned.
+  def mode(all = false, &block)
+    hist, modes = histogram(&block), []
+    freq = hist.values.max
+
+    hist.each { |key, value|
+      if value == freq
+        modes << key
+        break unless all
+      end
+    }
+
+    all ? modes : modes.first
+  end
+
+  # call-seq:
+  #   array.modes => anArray
+  #
+  # Returns an Array of all modes of the values in _array_ (see #mode).
+  def modes(&block)
+    mode(true, &block)
+  end
+
+    end
+  end
+end

data/lib/nuggets/array/monotone.rb

@@ -28,7 +28,7 @@
 class Array
 
   # call-seq:
-  #   array.monotone?(operator) => true or false
+  #   array.monotone?(operator) => +true+ or +false+
   #
   # Check whether _array_ is monotone according to +operator+.
   def monotone?(operator)
@@ -42,7 +42,7 @@ class Array
   alias_method :monotonic?, :monotone?
 
   # call-seq:
-  #   array.ascending? => true or false
+  #   array.ascending? => +true+ or +false+
   #
   # Check whether _array_ is (strictly) ascending.
   def ascending?(strict = false)
@@ -51,7 +51,7 @@ class Array
   alias_method :increasing?, :ascending?
 
   # call-seq:
-  #   array.strictly_ascending? => true or false
+  #   array.strictly_ascending? => +true+ or +false+
   #
   # Check whether _array_ is strictly ascending.
   def strictly_ascending?
@@ -60,7 +60,7 @@ class Array
   alias_method :strictly_increasing?, :strictly_ascending?
 
   # call-seq:
-  #   array.descending? => true or false
+  #   array.descending? => +true+ or +false+
   #
   # Check whether _array_ is (strictly) descending.
   def descending?(strict = false)
@@ -69,7 +69,7 @@ class Array
   alias_method :decreasing?, :descending?
 
   # call-seq:
-  #   array.strictly_descending? => true or false
+  #   array.strictly_descending? => +true+ or +false+
   #
   # Check whether _array_ is strictly descending.
   def strictly_descending?

data/lib/nuggets/array/only.rb

@@ -28,10 +28,11 @@
 class Array
 
   # call-seq:
-  #   array.only(relax = true or false) => anObject
+  #   array.only => anObject
+  #   array.only(+true+) => anObject
   #
   # Returns the only element of _array_. Raises an IndexError if _array_'s
-  # size is not 1, unless +relax+ is true.
+  # size is not 1, unless parameter +true+ is passed.
   #
   # Idea stolen from Gavin Sinclair's Ruby Extensions Project.
   def only(relax = size == 1)

data/lib/nuggets/array/regression.rb

@@ -0,0 +1,5 @@
+require 'nuggets/array/regression_mixin'
+
+class Array
+  include Nuggets::Array::RegressionMixin
+end

data/lib/nuggets/array/regression_mixin.rb

@@ -0,0 +1,63 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of ruby-nuggets, some extensions to the Ruby programming        #
+# language.                                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# ruby-nuggets is free software; you can redistribute it and/or modify it     #
+# under the terms of the GNU General Public License as published by the Free  #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# ruby-nuggets is distributed in the hope that it will be useful, but WITHOUT #
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or       #
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for    #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with ruby-nuggets. If not, see <http://www.gnu.org/licenses/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+require 'nuggets/array/correlation_mixin'
+
+module Nuggets
+  class Array
+    module RegressionMixin
+
+  def self.included(base)
+    base.send :include, Nuggets::Array::CorrelationMixin
+  end
+
+  # call-seq:
+  #   array.linear_least_squares => anArray
+  #
+  # Calculates the {linear least squares regression}[http://en.wikipedia.org/wiki/Ordinary_least_squares]
+  # for the <tt>{x,y}</tt> pairs in _array_.
+  def linear_least_squares
+    sx, sy = 0.0, 0.0
+
+    return [] if empty?
+
+    each { |x, y|
+      sx += x
+      sy += y
+    }
+
+    b = corr * sy / sx
+    a = (sy - b * sx) / size.to_f
+
+    map { |x, _| [x, a + b * x] }
+  end
+
+  alias_method :llsq, :linear_least_squares
+
+    end
+  end
+end

data/lib/nuggets/array/runiq_mixin.rb

@@ -38,7 +38,7 @@ module Nuggets
   end
 
   # call-seq:
-  #   array.runiq! => an_array or nil
+  #   array.runiq! => an_array or +nil+
   #
   # Reverse #uniq!.
   def runiq!

data/lib/nuggets/array/standard_deviation_mixin.rb

@@ -4,7 +4,7 @@
 # A component of ruby-nuggets, some extensions to the Ruby programming        #
 # language.                                                                   #
 #                                                                             #
-# Copyright (C) 2007-2009 Jens Wille                                          #
+# Copyright (C) 2007-2011 Jens Wille                                          #
 #                                                                             #
 # Authors:                                                                    #
 #     Jens Wille <jens.wille@uni-koeln.de>                                    #
@@ -38,13 +38,10 @@ module Nuggets
   # call-seq:
   #   array.standard_deviation => aFloat
   #
-  # Calculates the standard deviation of the items contained in _array_.
-  def standard_deviation
-    begin
-      Math.sqrt(block_given? ? variance { |*a| yield(*a) } : variance)
-    rescue Errno::EDOM
-      0.0
-    end
+  # Calculates the {standard deviation}[http://en.wikipedia.org/wiki/Standard_deviation]
+  # of the values in _array_.
+  def standard_deviation(&block)
+    Math.sqrt(variance(&block))
   end
 
   alias_method :std, :standard_deviation

data/lib/nuggets/array/variance_mixin.rb

@@ -4,7 +4,7 @@
 # A component of ruby-nuggets, some extensions to the Ruby programming        #
 # language.                                                                   #
 #                                                                             #
-# Copyright (C) 2007-2009 Jens Wille                                          #
+# Copyright (C) 2007-2011 Jens Wille                                          #
 #                                                                             #
 # Authors:                                                                    #
 #     Jens Wille <jens.wille@uni-koeln.de>                                    #
@@ -32,27 +32,46 @@ module Nuggets
   # call-seq:
   #   array.variance => aFloat
   #
-  # Calculates the variance of the items in _array_.
-  #
-  # Based on <http://warrenseen.com/blog/2006/03/13/how-to-calculate-standard-deviation/>.
+  # Calculates the variance[http://en.wikipedia.org/wiki/Variance] of the
+  # values in _array_.
   def variance
-    s, mean = 0.0, 0.0
+    sx, sq = 0.0, 0.0
 
-    return s if empty?
+    return sx if empty?
 
-    each_with_index { |x, n|
+    each { |x|
       x = yield x if block_given?
 
-      delta = x - mean
-      mean += delta / (n + 1)
-      s += delta * (x - mean)
+      sx += x
+      sq += x ** 2
     }
 
-    s / size
+    (sq - sx ** 2 / size) / size
   end
 
   alias_method :var, :variance
 
+  # call-seq:
+  #   array.covariance => aFloat
+  #
+  # Calculates the covariance[http://en.wikipedia.org/wiki/Covariance] of the
+  # <tt>{x,y}</tt> pairs in _array_.
+  def covariance
+    sx, sy, sp = 0.0, 0.0, 0.0
+
+    return sx if empty?
+
+    each { |x, y|
+      sx += x
+      sy += y
+      sp += x * y
+    }
+
+    (sp - sx * sy / size) / size
+  end
+
+  alias_method :cov, :covariance
+
     end
   end
 end

data/lib/nuggets/enumerable/all_any_extended.rb

@@ -31,23 +31,23 @@ module Enumerable
   alias_method :_nuggets_original_any?, :any?
 
   # call-seq:
-  #   enum.all?(obj[, operator]) => true or false
-  #   enum.all? { ... } => true or false
+  #   enum.all?(obj[, operator]) => +true+ or +false+
+  #   enum.all? { ... } => +true+ or +false+
   #
   # Adds the ability to pass an +object+ instead of a block, which will then
   # be tested against each item in _enum_ according to +operator+, defaulting
-  # to :===.
+  # to <tt>:===</tt>.
   def all?(object = default = Object.new, operator = :===, &block)
     _nuggets_original_all?(&_block_for_all_any_extended(object, default, operator, &block))
   end
 
   # call-seq:
-  #   enum.any?(obj[, operator]) => true or false
-  #   enum.any? { ... } => true or false
+  #   enum.any?(obj[, operator]) => +true+ or +false+
+  #   enum.any? { ... } => +true+ or +false+
   #
   # Adds the ability to pass an +object+ instead of a block, which will then
   # be tested against each item in _enum_ according to +operator+, defaulting
-  # to :===.
+  # to <tt>:===</tt>.
   def any?(object = default = Object.new, operator = :===, &block)
     _nuggets_original_any?(&_block_for_all_any_extended(object, default, operator, &block))
   end

data/lib/nuggets/enumerable/minmax.rb

@@ -85,7 +85,7 @@ module Enumerable
   # call-seq:
   #   enum.max(what) => aValue
   #
-  # Maximum #minmax. If +what+ is omitted, or nil, the original Enumerable#max
+  # Maximum #minmax. If +what+ is omitted, or +nil+, the original Enumerable#max
   # is called.
   def max(what = nil)
     what ? minmax(:max, what) : block_given? ?
@@ -95,7 +95,7 @@ module Enumerable
   # call-seq:
   #   enum.min(what) => aValue
   #
-  # Minimum #minmax. If +what+ is omitted, or nil, the original Enumerable#min
+  # Minimum #minmax. If +what+ is omitted, or +nil+, the original Enumerable#min
   # is called.
   def min(what = nil)
     what ? minmax(:min, what) : block_given? ?

data/lib/nuggets/env/set_mixin.rb

@@ -30,10 +30,10 @@ module Nuggets
     module SetMixin
 
   # call-seq:
-  #   ENV.set(env = {}, clear = true) => aHash
-  #   ENV.set(env = {}, clear = true) { ... } => anObject
+  #   ENV.set([env[, clear]]) => aHash
+  #   ENV.set([env[, clear]]) { ... } => anObject
   #
-  # Overrides ENV with +env+, clearing it beforehand if +clear+ is true. If a
+  # Overrides ENV with +env+, clearing it beforehand if +clear+ is +true+. If a
   # block is given, restores ENV to its original state afterwards and returns
   # the result of the block; otherwise returns the original ENV as a hash.
   def set(env = {}, clear = true)
@@ -56,7 +56,7 @@ module Nuggets
   alias_method :without, :set
 
   # call-seq:
-  #   ENV.with(env = {}, clear = false) { ... } => anObject
+  #   ENV.with([env[, clear]]) { ... } => anObject
   #
   # Temporarily overrides ENV with +env+ for the block execution. See #set.
   def with(env = {}, clear = false)

data/lib/nuggets/env/user_home_mixin.rb

@@ -30,7 +30,7 @@ module Nuggets
     module UserHomeMixin
 
   # call-seq:
-  #   ENV.user_home(default = '/') => aString
+  #   ENV.user_home([default]) => aString
   #
   # Returns the user's home directory, or +default+ if it could not be found.
   def user_home(default = ::File::ALT_SEPARATOR ? 'C:/' : '/')

data/lib/nuggets/file/replace_mixin.rb

@@ -30,13 +30,13 @@ module Nuggets
     module ReplaceMixin
 
   # call-seq:
-  #   File.replace(name, create_if_missing = false) { ... } => aString
-  #   File.replace(name, create_if_missing = false) { |content| ... } => aString
+  #   File.replace(name[, create_if_missing]) { ... } => aString
+  #   File.replace(name[, create_if_missing]) { |content| ... } => aString
   #
   # Replaces the contents of file +name+ with the result of the block. Yields
   # the file's contents to the block if requested. Returns the new content.
   #
-  # If +create_if_missing+ is true and the file does not exist, it will be
+  # If +create_if_missing+ is +true+ and the file does not exist, it will be
   # created.
   def replace(name, create_if_missing = false, &block)
     open(name, create_if_missing && !exist?(name) ? 'w+' : 'r+') { |f|

data/lib/nuggets/file/sub_mixin.rb

@@ -47,7 +47,7 @@ module Nuggets
   end
 
   # call-seq:
-  #   File.sub!(name, *args, &block) => aString or nil
+  #   File.sub!(name, *args, &block) => aString or +nil+
   #
   # Calls String#sub! on file +name+'s contents with +args+ and (optional)
   # +block+ and replaces the file with the new content. Returns the result
@@ -75,7 +75,7 @@ module Nuggets
   end
 
   # call-seq:
-  #   File.gsub!(name, *args, &block) => aString or nil
+  #   File.gsub!(name, *args, &block) => aString or +nil+
   #
   # Calls String#gsub! on file +name+'s contents with +args+ and (optional)
   # +block+ and replaces the file with the new content. Returns the result

data/lib/nuggets/file/which_mixin.rb

@@ -34,7 +34,7 @@ module Nuggets
   DEFAULT_EXTENSIONS = [RbConfig::CONFIG['EXEEXT']]
 
   # call-seq:
-  #   File.which(executable, extensions = DEFAULT_EXTENSIONS) => aString or nil
+  #   File.which(executable[, extensions]) => aString or +nil+
   #
   # Returns +executable+ if it's executable, or the full path to +executable+
   # found in PATH, or +nil+ otherwise. Checks +executable+ with each extension
@@ -44,27 +44,28 @@ module Nuggets
   def which(executable, extensions = DEFAULT_EXTENSIONS)
     extensions |= ['']
 
-    extensions.each { |extension|
-      executable += extension
-      return executable if executable?(executable)
+    if env = ENV['PATH']
+      dirs = env.split(self::PATH_SEPARATOR)
+      dirs.map! { |dir| expand_path(dir) }
+    end
 
-      if path = ENV['PATH']
-        path.split(::File::PATH_SEPARATOR).each { |dir|
-          candidate = join(expand_path(dir), executable)
-          return candidate if executable?(candidate)
-        }
-      end
-    }
+    extensions.find { |extension|
+      file = "#{executable}#{extension}"
+      return file if file?(file) && executable?(file)
 
-    nil
+      dirs.find { |dir|
+        path = join(dir, file)
+        return path if file?(path) && executable?(path)
+      } if dirs
+    }
   end
 
   # call-seq:
-  #   File.which_command(commands) => aString or nil
+  #   File.which_command(commands) => aString or +nil+
   #
   # Returns the first of +commands+ that is executable (according to #which).
   def which_command(commands, extensions = DEFAULT_EXTENSIONS)
-    commands.find { |command| which(command[/\S+/], extensions) }
+    commands.find { |command| which(command.to_s[/\S+/], extensions) }
   end
 
     end