nuggets 0.9.9 → 1.0.0

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,169 @@
+#--
+###############################################################################
+#                                                                             #
+# 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 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.probability_mass_function => aHash
+  #   array.probability_mass_function { |x| ... } => aHash
+  #
+  # Calculates the {probability mass function}[http://en.wikipedia.org/wiki/Probability_mass_function]
+  # (normalized 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 probability (via #histogram).
+  def probability_mass_function(&block)
+    hist, n = histogram(&block), size.to_f
+    hist.each { |k, v| hist[k] = v / n }
+  end
+
+  alias_method :pmf, :probability_mass_function
+
+  # 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.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/in_order.rb

@@ -0,0 +1,50 @@
+#--
+###############################################################################
+#                                                                             #
+# 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.in_order(*ordered) => new_array
+  #
+  # Force order, but ignore non-existing and keep remaining.
+  #
+  # Examples:
+  #   [:created_at, :email, :login, :updated_at].in_order(:login, :email)    #=> [:login, :email, :created_at, :updated_at]
+  #   [:created_at, :email, :login, :updated_at].in_order(:email, :address)  #=> [:email, :created_at, :login, :updated_at]
+  def in_order(*ordered)
+    ordered &= self
+    ordered + (self - ordered)
+  end
+
+  # call-seq:
+  #   array.in_order!(*ordered) => array
+  #
+  # Destructive version of #in_order.
+  def in_order!(*ordered)
+    replace(in_order(*ordered))
+  end
+
+end

data/lib/nuggets/array/limit.rb

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

data/lib/nuggets/array/limit_mixin.rb

@@ -0,0 +1,56 @@
+#--
+###############################################################################
+#                                                                             #
+# 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 LimitMixin
+
+  # call-seq:
+  #   array.limit(min, max) => anArray
+  #
+  # Returns a new array of all distinct values in _array_ limited to +min+
+  # and +max+ (cf. Numeric#limit). If +uniq+ is +true+, resulting duplicates
+  # will be removed.
+  def limit(min, max, uniq = true)
+    limited = cap(min..max)
+    limited.uniq! if uniq
+    limited
+  end
+
+  alias_method :between, :limit
+
+  def cap(max)
+    if max.respond_to?(:begin)
+      min, max = max.begin, max.end
+      map { |item| item.limit(min, max) }
+    else
+      map { |item| item.max(max) }
+    end
+  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,202 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2013 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 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.0 / 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
+
+  # call-seq:
+  #   array.report_mean => anArray
+  #   array.report_mean(method[, precision]) => anArray
+  #
+  # Expects _array_ to be an array of arrays ("rows") of numeric values;
+  # the first "row" may consist of strings (labels) instead. Returns an
+  # array of strings with the mean (according to +method+, default #mean)
+  # of each "column", prepended with the label, if present, and appended
+  # with the standard deviation, if available; all values are subject to
+  # +precision+.
+  #
+  # If _array_ is a flat array of numeric values, it is treated as a single
+  # "column".
+  #
+  # Returns +nil+ if _array_ is empty.
+  #
+  # Examples (with standard deviation):
+  #
+  #   [[9.4, 34.75], [9.46, 34.68], [9.51, 34.61]].report_mean
+  #   #=> ["9.4567 +/- 0.0450", "34.6800 +/- 0.0572"]
+  #
+  #   [[9.4, 34.75], [9.46, 34.68], [9.51, 34.61]].report_mean(:harmonic)
+  #   #=> ["9.4565 +/- 0.0450", "34.6799 +/- 0.0572"]
+  #
+  #   [["a", "b"], [9.4, 34.75], [9.46, 34.68], [9.51, 34.61]].report_mean(nil, 2)
+  #   #=> ["a  9.46 +/- 0.04", "b  34.68 +/- 0.06"]
+  #
+  #   CSV.read('csv', headers: true, converters: :numeric).to_a.report_mean
+  #   #=> ["a    9.4567 +/- 0.0450", "b    34.6800 +/- 0.0572"]
+  #
+  #   [9.4, 9.46, 9.51].report_mean
+  #   #=> ["9.4567 +/- 0.0450"]
+  #
+  #   [34.75, 34.68, 34.61].report_mean
+  #   #=> ["34.6800 +/- 0.0572"]
+  #
+  #   [].report_mean
+  #   #=> nil
+  def report_mean(method = nil, precision = 4)
+    return if empty?
+
+    return clone.replace(self.class.new.push(self).transpose).
+      report_mean(method, precision) unless first.is_a?(self.class)
+
+    met, sep = [method ||= :mean, 'mean'], ['', '_']
+    lab, std = first.first.is_a?(::String), respond_to?(:std)
+
+    fmt = ["%-#{precision}s", "%.#{precision}f", "+/- %.#{precision}f"]
+
+    until respond_to?(method) || sep.empty?
+      method = met.join(sep.shift)
+    end
+
+    transpose.map! { |x|
+      i, a = [], []
+
+      i << 0 and a << x.shift if lab
+      i << 1 and a << x.send(method)
+      i << 2 and a << x.std if std
+
+      fmt.values_at(*i).join(' ') % a
+    }
+  end
+
+    end
+  end
+end