ruby-nuggets 0.6.9 → 0.7.0

data/.rspec

@@ -1 +1,2 @@
 --colour
+--debug

data/README

@@ -2,7 +2,7 @@
 
 == VERSION
 
-This documentation refers to ruby-nuggets version 0.6.9
+This documentation refers to ruby-nuggets version 0.7.0
 
 
 == DESCRIPTION

data/Rakefile

@@ -10,10 +10,10 @@ begin
     },
 
     :gem => {
-      :version     => Nuggets::VERSION,
-      :summary     => 'Some extensions to the Ruby programming language.',
-      :files       => FileList['lib/**/*.rb'].to_a,
-      :extra_files => FileList['[A-Z]*', '.rspec', 'spec/**/*.rb'].to_a
+      :version => Nuggets::VERSION,
+      :summary => %q{Some extensions to the Ruby programming language.},
+      :author  => %q{Jens Wille},
+      :email   => %q{jens.wille@uni-koeln.de}
     }
   }}
 rescue LoadError => err

data/lib/nuggets/array/correlation.rb

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

data/lib/nuggets/array/correlation_mixin.rb

@@ -0,0 +1,62 @@
+#--
+###############################################################################
+#                                                                             #
+# 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/variance_mixin'
+
+module Nuggets
+  class Array
+    module CorrelationMixin
+
+  def self.included(base)
+    base.send :include, Nuggets::Array::VarianceMixin
+  end
+
+  # call-seq:
+  #   array.correlation_coefficient => anArray
+  #
+  # Calculates the {Pearson product-moment correlation
+  # coefficient}[http://en.wikipedia.org/wiki/Pearson_product-moment_correlation_coefficient]
+  # for the <tt>{x,y}</tt> pairs in _array_.
+  def correlation_coefficient
+    sx, sy = 0.0, 0.0
+
+    return sx if empty?
+
+    each { |x, y|
+      sx += x
+      sy += y
+    }
+
+    (sx * cov) / (sy * var { |x, _| x })
+  end
+
+  alias_method :corr, :correlation_coefficient
+  alias_method :pmcc, :correlation_coefficient
+
+    end
+  end
+end

data/lib/nuggets/array/histogram.rb

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

data/lib/nuggets/array/histogram_mixin.rb

@@ -0,0 +1,155 @@
+#--
+###############################################################################
+#                                                                             #
+# 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/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+module Nuggets
+  class Array
+    module HistogramMixin
+
+  # Provides some default formats for #formatted_histogram.
+  #
+  # Example:
+  #
+  #   (default)         ab  [==]  2
+  #   (percent)         xyz [===] 3 (37.50%)
+  #   (numeric)          42 [==]  2
+  #   (numeric_percent) 123 [=]   1 (12.50%)
+  #
+  # The "numeric" variants format the item as a (decimal) number.
+  FORMATS = {
+    :default         => '%-*s [%s]%*s %*d',
+    :percent         => '%-*s [%s]%*s %*d (%.2f%%)',
+    :numeric         =>  '%*d [%s]%*s %*d',
+    :numeric_percent =>  '%*d [%s]%*s %*d (%.2f%%)'
+  }
+
+  # Encapsulates a #histogram item and provides the following attributes (see
+  # also #annotated_histogram):
+  #
+  # item::            The original item
+  # freq::            The item's frequency in the collection
+  # percentage::      The percentage of the item's frequency in the collection
+  # max_freq::        The maximum frequency in the collection
+  # max_freq_length:: The maximum frequency's "width"
+  # max_item_length:: The maximum item length in the collection
+  HistogramItem = ::Struct.new(
+    :item, :freq, :max_freq, :max_freq_length, :max_item_length, :percentage
+  )
+
+  # call-seq:
+  #   array.histogram => aHash
+  #   array.histogram { |x| ... } => aHash
+  #
+  # Calculates the {frequency histogram}[http://en.wikipedia.org/wiki/Histogram]
+  # of the values in _array_. Returns a Hash that maps any value, or the result
+  # of the value yielded to the block, to its frequency.
+  def histogram
+    hist = ::Hash.new(0)
+    each { |x| hist[block_given? ? yield(x) : x] += 1 }
+    hist
+  end
+
+  # call-seq:
+  #   array.annotated_histogram => anArray
+  #   array.annotated_histogram { |hist_item| ... } => aHash
+  #
+  # Calculates the #histogram for _array_ and yields each histogram item
+  # (see HistogramItem) to the block or returns an Array of the histogram
+  # items.
+  def annotated_histogram
+    hist, items = histogram, []
+
+    percentage = size / 100.0
+
+    max_freq = hist.values.max
+    max_freq_length = max_freq.to_s.length
+
+    max_item_length = hist.keys.map { |item| item.to_s.length }.max
+
+    # try to sort the histogram hash
+    begin
+      hist = hist.sort
+    rescue ::ArgumentError
+    end
+
+    hist.each { |item, freq|
+      hist_item = HistogramItem.new(
+        item, freq, max_freq, max_freq_length, max_item_length, freq / percentage
+      )
+
+      block_given? ? yield(hist_item) : items << hist_item
+    }
+
+    block_given? ? hist : items
+  end
+
+  # call-seq:
+  #   array.formatted_histogram([format[, indicator]]) => aString
+  #
+  # Returns the #histogram of _array_ as a formatted String according to
+  # +format+, using +indicator+ to draw the frequency bar.
+  #
+  # +format+ may be a Symbol indicating one of the provided default formats
+  # (see FORMATS) or a format String (see Kernel#sprintf) that will receive
+  # the following arguments (in order):
+  #
+  # 1. +max_item_length+ (Integer)
+  # 1. +item+ (String)
+  # 1. "frequency_bar" (String)
+  # 1. "padding" (String)
+  # 1. +max_freq_length+ (Integer)
+  # 1. +freq+ (Integer)
+  # 1. +percentage+ (Float, optional)
+  #
+  # See HistogramItem for further details on the individual arguments.
+  def formatted_histogram(format = :default, indicator = '=')
+    format = FORMATS[format] if FORMATS.has_key?(format)
+    raise ::TypeError, "String expected, got #{format.class}" unless format.is_a?(::String)
+
+    include_percentage = format.include?('%%')
+    indicator_length   = indicator.length
+
+    lines = []
+
+    annotated_histogram { |hist|
+      arguments = [
+        hist.max_item_length, hist.item,                     # item (padded)
+        indicator * hist.freq,                               # indicator bar
+        (hist.max_freq - hist.freq) * indicator_length, '',  # indicator padding
+        hist.max_freq_length, hist.freq                      # frequency (padded)
+      ]
+
+      arguments << hist.percentage if include_percentage     # percentage (optional)
+
+      lines << format % arguments
+    }
+
+    lines.join("\n")
+  end
+
+    end
+  end
+end

data/lib/nuggets/array/mean.rb

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

data/lib/nuggets/array/mean_mixin.rb

@@ -0,0 +1,139 @@
+#--
+###############################################################################
+#                                                                             #
+# 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/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+module Nuggets
+  class Array
+    module MeanMixin
+
+  # call-seq:
+  #   array.generalized_mean(exponent) => aFloat
+  #   array.generalized_mean(exponent) { |x| ... } => aFloat
+  #
+  # Calculates the {generalized mean}[http://en.wikipedia.org/wiki/Generalized_mean]
+  # of the values in _array_ for +exponent+. Returns the #geometric_mean if
+  # +exponent+ is zero.
+  #
+  # An optional block may be passed to provide a weight for each value.
+  # Defaults to 1. Returns +nil+ if the sum of all weights is zero (this
+  # includes _array_ being empty).
+  def generalized_mean(exponent, &block)
+    return geometric_mean(&block) if exponent.zero?
+
+    total, weights = 0, 0
+
+    each { |x|
+      weight = block ? block[x] : 1
+
+      total   += weight * x ** exponent
+      weights += weight
+    }
+
+    (total / weights.to_f) ** (1 / exponent) unless weights.zero?
+  end
+
+  alias_method :power_mean,     :generalized_mean
+  alias_method :minkowski_mean, :generalized_mean
+
+  # call-seq:
+  #   array.arithmetic_mean => aFloat
+  #   array.arithmetic_mean { |x| ... } => aFloat
+  #
+  # Calculates the {arithmetic mean}[http://en.wikipedia.org/wiki/Arithmetic_mean]
+  # of the values in _array_.
+  #
+  # An optional block may be passed to provide a weight for each value.
+  # Defaults to 1. Returns +nil+ if the sum of all weights is zero (this
+  # includes _array_ being empty).
+  def arithmetic_mean(&block)
+    generalized_mean(1, &block)
+  end
+
+  alias_method :mean,    :arithmetic_mean
+  alias_method :average, :arithmetic_mean
+  alias_method :avg,     :arithmetic_mean
+
+  # call-seq:
+  #   array.root_mean_square => aFloat
+  #   array.root_mean_square { |x| ... } => aFloat
+  #
+  # Calculates the {root mean square}[http://en.wikipedia.org/wiki/Root_mean_square]
+  # (quadratic mean) of the values in _array_.
+  #
+  # An optional block may be passed to provide a weight for each value.
+  # Defaults to 1. Returns +nil+ if the sum of all weights is zero (this
+  # includes _array_ being empty).
+  def root_mean_square(&block)
+    generalized_mean(2, &block)
+  end
+
+  alias_method :rms,            :root_mean_square
+  alias_method :quadratic_mean, :root_mean_square
+
+  # call-seq:
+  #   array.harmonic_mean => aFloat
+  #   array.harmonic_mean { |x| ... } => aFloat
+  #
+  # Calculates the {harmonic mean}[http://en.wikipedia.org/wiki/Harmonic_mean]
+  # of the values in _array_.
+  #
+  # An optional block may be passed to provide a weight for each value.
+  # Defaults to 1. Returns +nil+ if the sum of all weights is zero (this
+  # includes _array_ being empty).
+  def harmonic_mean(&block)
+    generalized_mean(-1, &block)
+  end
+
+  alias_method :harmean, :harmonic_mean
+
+  # call-seq:
+  #   array.geometric_mean => aFloat
+  #   array.geometric_mean { |x| ... } => aFloat
+  #
+  # Calculates the {geometric mean}[http://en.wikipedia.org/wiki/Geometric_median]
+  # of the values in _array_.
+  #
+  # An optional block may be passed to provide a weight for each value.
+  # Defaults to 1. Returns +nil+ if the sum of all weights is zero (this
+  # includes _array_ being empty).
+  def geometric_mean
+    total, weights = 1, 0
+
+    each { |x|
+      weight = block_given? ? yield(x) : 1
+
+      total   *= x ** weight
+      weights += weight
+    }
+
+    total ** (1 / weights.to_f) unless weights.zero?
+  end
+
+  alias_method :geomean, :geometric_mean
+
+    end
+  end
+end

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,74 @@
+#--
+###############################################################################
+#                                                                             #
+# 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/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+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