nuggets 0.9.9 → 1.0.0

data/lib/nuggets/array/median.rb

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

data/lib/nuggets/array/median_mixin.rb

@@ -0,0 +1,73 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# 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 Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+module Nuggets
+  class Array
+    module MedianMixin
+
+  # call-seq:
+  #   array.median([prefer]) => anObject
+  #   array.median { |left, right| ... } => anObject
+  #
+  # Determines the median[http://en.wikipedia.org/wiki/Median] of the values
+  # in _array_. _array_ must be sortable.
+  #
+  # If _array_ contains an even number of values, a block may be passed to
+  # decide what the "middle" (average) should be. For Numeric values, the
+  # block is optional and the arithmetic mean will be used when no block
+  # is passed; for other values, the block is mandatory.
+  #
+  # Alternatively, +prefer+ may either be set to +true+, 1, or <tt>:left</tt>
+  # to use the left "middle", or to +false+, 2, or <tt>:right</tt> to use the
+  # right "middle". The block will then be ignored.
+  def median(prefer = nil)
+    return if empty?
+
+    sorted, index = sort, (size / 2.0).ceil - 1
+
+    case prefer
+      when true,  1, :left  then prefer_left  = true
+      when false, 2, :right then prefer_right = true
+    end
+
+    middle1 = sorted[index]
+    return middle1 if prefer_left || size.odd?
+
+    middle2 = sorted[index + 1]
+    return middle2 if prefer_right
+
+    unless block_given?
+      # simple arithmetic mean
+      (middle1 + middle2) / 2.0
+    else
+      # make your own average
+      yield middle1, middle2
+    end
+  end
+
+    end
+  end
+end

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,69 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# 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 Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with 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

@@ -0,0 +1,83 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# 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 Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+class Array
+
+  # call-seq:
+  #   array.monotone?(operator) => +true+ or +false+
+  #
+  # Check whether _array_ is monotone according to +operator+.
+  def monotone?(operator = nil)
+    if [nil, true, false].include?(operator)
+      ascending?(operator) || descending?(operator)
+    else
+      inject { |a, b|
+        return false unless a.send(operator, b)
+        b
+      }
+
+      true
+    end
+  end
+  alias_method :monotonic?, :monotone?
+
+  # call-seq:
+  #   array.ascending? => +true+ or +false+
+  #
+  # Check whether _array_ is (strictly) ascending.
+  def ascending?(strict = false)
+    monotone?(strict ? :< : :<=)
+  end
+  alias_method :increasing?, :ascending?
+
+  # call-seq:
+  #   array.strictly_ascending? => +true+ or +false+
+  #
+  # Check whether _array_ is strictly ascending.
+  def strictly_ascending?
+    ascending?(true)
+  end
+  alias_method :strictly_increasing?, :strictly_ascending?
+
+  # call-seq:
+  #   array.descending? => +true+ or +false+
+  #
+  # Check whether _array_ is (strictly) descending.
+  def descending?(strict = false)
+    monotone?(strict ? :> : :>=)
+  end
+  alias_method :decreasing?, :descending?
+
+  # call-seq:
+  #   array.strictly_descending? => +true+ or +false+
+  #
+  # Check whether _array_ is strictly descending.
+  def strictly_descending?
+    descending?(true)
+  end
+  alias_method :strictly_decreasing?, :strictly_descending?
+
+end

data/lib/nuggets/array/only.rb

@@ -0,0 +1,41 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# 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 Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+class Array
+
+  # call-seq:
+  #   array.only => anObject
+  #   array.only(+true+) => anObject
+  #
+  # Returns the only element of _array_. Raises an IndexError if _array_'s
+  # size is not 1, unless parameter +true+ is passed.
+  #
+  # Idea stolen from Gavin Sinclair's Ruby Extensions Project.
+  def only(relax = size == 1)
+    relax ? first : raise(::IndexError, 'not a single-element array')
+  end
+
+end

data/lib/nuggets/array/rand.rb

@@ -0,0 +1,44 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# 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 Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+class Array
+
+  # call-seq:
+  #   array.rand => anItem
+  #
+  # Randomly pick an item from _array_.
+  def rand
+    at(::Kernel.rand(size))
+  end
+
+end
+
+if $0 == __FILE__
+  a = %w[a b c d]
+  p a
+  p a.rand
+  p a.rand
+end

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,149 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2012 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# 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 Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+module Nuggets
+  class Array
+    module RegressionMixin
+
+  # call-seq:
+  #   array.linear_least_squares => anArray
+  #
+  # Calculates the {linear least squares regression}[http://en.wikipedia.org/wiki/Simple_linear_regression]
+  # for the <tt>{x,y}</tt> pairs in _array_. If _array_ only contains
+  # values instead of pairs, +y+ will be the value and +x+ will be each
+  # value's position (rank) in _array_.
+  def linear_least_squares
+    return [] if empty?
+
+    sx, sy, sq, sp, xys = 0.0, 0.0, 0.0, 0.0, first.respond_to?(:to_ary) ?
+      self : self.class.new(size) { |i| [i + 1, at(i)] }
+
+    xys.each { |x, y| sx += x; sy += y; sq += x ** 2; sp += x * y }
+
+    b = (v = sq * size - sx ** 2) == 0 ? 0 : (sp * size - sx * sy) / v
+    a = (sy - b * sx) / size
+
+    xys.map { |x, _| [x, a + b * x] }
+  end
+
+  alias_method :llsq, :linear_least_squares
+
+  # call-seq:
+  #   array.linear_least_squares_incremental => anIncrementalLinearRegression
+  #
+  # Returns an instance of IncrementalLinearRegression for _array_; _array_
+  # being a list of values (in contrast to #linear_least_squares, which also
+  # accepts <tt>{x,y}</tt> pairs). Use IncrementalLinearRegression directly,
+  # or apply this method to an empty _array_, for more control over its input
+  # data.
+  def linear_least_squares_incremental
+    IncrementalLinearRegression.new(*self)
+  end
+
+  alias_method :llsqi, :linear_least_squares_incremental
+
+  # Inspired by {Incremental Simple Linear Regression in Ruby}[http://blog.codewren.ch/post/31378435699].
+  #
+  # Use #push to add a single <tt>{x,y}</tt> pair, #add to add a list of +y+
+  # values, and #<< to add a single +y+ value. Whenever a single +y+ value is
+  # added, it's associated with an +x+ value of its position (rank) in the
+  # data series.
+  #
+  # Call #to_a (or any Enumerable method) to work with the regression points.
+  class IncrementalLinearRegression
+
+    include ::Enumerable
+
+    def initialize(*ys)
+      clear
+      add(*ys)
+    end
+
+    def clear
+      @x = @y = @xx = @xy = 0.0
+      @cnt, @slope = 0, nil
+      self
+    end
+
+    def push(x, y)
+      cnt, @slope = @cnt += 1, nil
+
+      @x  += (x     - @x)  / cnt
+      @y  += (y     - @y)  / cnt
+      @xx += (x * x - @xx) / cnt
+      @xy += (x * y - @xy) / cnt
+
+      self
+    end
+
+    def add(*ys)
+      ys.each { |y| self << y }
+      self
+    end
+
+    def <<(y)
+      push(@cnt + 1, y)
+    end
+
+    def slope
+      @slope ||= @cnt < 2 ? 0 : (@xy - @x * @y) / (@xx - @x * @x)
+    end
+
+    def intercept
+      at(0)
+    end
+
+    def at(x)
+      @y + slope * (x - @x)
+    end
+
+    alias_method :[], :at
+
+    def each
+      @cnt.times { |i| yield [x = i + 1, at(x)] }
+      self
+    end
+
+    def to_a(range = nil)
+      range ? range.map { |x| [x, at(x)] } : super()
+    end
+
+    def to_s
+      s, i = slope, intercept
+
+      y = s == 0 ? i : begin
+        x = s.abs == 1 ? "#{'-' if s < 0}x" : "#{s} * x"
+        i == 0 ? x : "#{x} #{i < 0 ? '-' : '+'} #{i.abs}"
+      end
+
+      "y := #{y}".gsub(/\.0\b/, '')
+    end
+
+  end
+
+    end
+  end
+end