ruby-nuggets 0.9.9 → 1.0.0

data/lib/nuggets/array/histogram.rb

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

data/lib/nuggets/array/histogram_mixin.rb

@@ -1,170 +0,0 @@
-#--
-###############################################################################
-#                                                                             #
-# A component of ruby-nuggets, some extensions to the Ruby programming        #
-# language.                                                                   #
-#                                                                             #
-# Copyright (C) 2007-2011 Jens Wille                                          #
-#                                                                             #
-# Authors:                                                                    #
-#     Jens Wille <jens.wille@gmail.com>                                       #
-#                                                                             #
-# ruby-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.                                                  #
-#                                                                             #
-# 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 Affero General Public License #
-# for more details.                                                           #
-#                                                                             #
-# You should have received a copy of the GNU Affero 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.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

@@ -1,51 +0,0 @@
-#--
-###############################################################################
-#                                                                             #
-# A component of ruby-nuggets, some extensions to the Ruby programming        #
-# language.                                                                   #
-#                                                                             #
-# Copyright (C) 2007-2011 Jens Wille                                          #
-#                                                                             #
-# Authors:                                                                    #
-#     Jens Wille <jens.wille@gmail.com>                                       #
-#                                                                             #
-# ruby-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.                                                  #
-#                                                                             #
-# 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 Affero General Public License #
-# for more details.                                                           #
-#                                                                             #
-# You should have received a copy of the GNU Affero General Public License    #
-# along with ruby-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

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

data/lib/nuggets/array/limit_mixin.rb

@@ -1,57 +0,0 @@
-#--
-###############################################################################
-#                                                                             #
-# A component of ruby-nuggets, some extensions to the Ruby programming        #
-# language.                                                                   #
-#                                                                             #
-# Copyright (C) 2007-2011 Jens Wille                                          #
-#                                                                             #
-# Authors:                                                                    #
-#     Jens Wille <jens.wille@gmail.com>                                       #
-#                                                                             #
-# ruby-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.                                                  #
-#                                                                             #
-# 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 Affero General Public License #
-# for more details.                                                           #
-#                                                                             #
-# You should have received a copy of the GNU Affero General Public License    #
-# along with ruby-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

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

data/lib/nuggets/array/mean_mixin.rb

@@ -1,203 +0,0 @@
-#--
-###############################################################################
-#                                                                             #
-# A component of ruby-nuggets, some extensions to the Ruby programming        #
-# language.                                                                   #
-#                                                                             #
-# Copyright (C) 2007-2013 Jens Wille                                          #
-#                                                                             #
-# Authors:                                                                    #
-#     Jens Wille <jens.wille@gmail.com>                                       #
-#                                                                             #
-# ruby-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.                                                  #
-#                                                                             #
-# 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 Affero General Public License #
-# for more details.                                                           #
-#                                                                             #
-# You should have received a copy of the GNU Affero 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.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