facets-glimmer 3.2.0

data/lib/standard/facets/math/gini_coefficient.rb

@@ -0,0 +1,33 @@
+require 'facets/math/approx_equal'
+
+module Math
+
+  # Calculates the Gini Coefficient (a measure of inequality of a distribution
+  # based on the area between the Lorenz curve and the uniform curve).
+  #
+  # http://en.wikipedia.org/wiki/Gini_coefficient
+  #
+  # This is a slightly cleaner way of calculating the Gini Coefficient then
+  # the previous implementationj.
+  #
+  #   GC = \frac{\sum_{i=1}^N (2i-N-1)x_i}{N^2-\bar{x}}
+  #
+  def self.gini_coefficient(array)
+    return -1 if size <= 0 or any? { |x| x < 0 }
+    return 0 if size < 2 or all? { |x| approx_equal(x,0) }
+    s = 0
+    sort.each_with_index { |li,i| s += (2*i+1-size)*li }
+    s.to_f/(size**2*mean).to_f
+  end
+
+  ## OLD WAY
+  ##   GC = \frac{1}{N} \left ( N+1-2\frac{\sum_{i=1}^N (N+1-i)y_i}{\sum_{i=1}^N y_i} \right )
+  ## def self.gini_coefficient2(array)
+  ##   return -1 if size <= 0 or any? { |x| x < 0 }
+  ##   return 0 if size < 2 or all? { |x| Math::float_equal(x,0) }
+  ##   s = 0
+  ##   sort.each_with_index { |yi,i| s += (size - i)*yi }
+  ##   (size+1-2*(s.to_f/sum.to_f)).to_f/size.to_f
+  ## end
+
+end

data/lib/standard/facets/math/kldivergence.rb

@@ -0,0 +1,19 @@
+module Math
+
+  # The Kullback-Leibler divergence from this array to that of +q+.
+  #
+  # NB: You will possibly want to sort both P and Q before calling this
+  # depending on what you're actually trying to measure.
+  #
+  # http://en.wikipedia.org/wiki/Kullback-Leibler_divergence
+  #
+  def self.kldivergence(array, q)
+    fail "Buggy."
+    fail "Cannot compare differently sized arrays." unless size = q.size
+    kld = 0
+    each_with_index { |pi,i| kld += pi*Math::log(pi.to_f/q[i].to_f) }
+    kld
+  end
+
+end
+

data/lib/standard/facets/math/lcm.rb

@@ -0,0 +1,15 @@
+module Math
+
+  # Least common multiple of +m+ and +n+, computed by multiplying
+  # +m+ and +n+ and dividing the product by the gcd of +m+ and +n+,
+  # +nil+ for non-positive numbers.
+  def self.lcm(m, n)
+    m = Integer(m)
+    n = Integer(n)
+    if m <= 0 || n <= 0
+      return nil
+    end
+    m / gcd(m, n) * n
+  end
+
+end

data/lib/standard/facets/math/lgamma.rb

@@ -0,0 +1,23 @@
+require 'facets/math/lngamma'
+
+## This is the old definition by Josef Schugt.
+##
+## Around v2.0, Ruby finally added it's own `lgamma`
+## function. That's good, but unforutnately it returns
+## an array that includes the `sign(gamma(x))` too.
+#
+# def Math.lgamma(x)
+#  h  = x + 5.5
+#  h -= (x + 0.5) * log(h)
+#
+#  sum  =  1.000_000_000_190_015
+#  sum += 76.180_091_729_471_46	     / (x + 1.0)
+#  sum -= 86.505_320_329_416_77	     / (x + 2.0)
+#  sum += 24.014_098_240_830_91	     / (x + 3.0)
+#  sum -=  1.231_739_572_450_155	     / (x + 4.0)
+#  sum +=  0.120_865_097_386_617_9e-2 / (x + 5.0)
+#  sum -=  0.539_523_938_495_3e-5     / (x + 6.0)
+#
+#  -h + log(2.506_628_274_631_000_5 * sum / x)
+# end
+

data/lib/standard/facets/math/linsolve.rb

@@ -0,0 +1,12 @@
+module Math
+
+  # Returns real solution(s) of <code>+a+x + +b+ = +c+</code> or +nil+
+  # if no or an infinite number of solutions exist. If
+  # <code>c</code> is missing it is assumed to be 0.
+  #
+  # @author Josef Schugt
+  def self.linsolve(a, b, c = 0.0)
+    a == 0 ? nil : (c - b) / a
+  end
+
+end

data/lib/standard/facets/math/lngamma.rb

@@ -0,0 +1,18 @@
+module Math
+
+  # Logarithmus naturalis of gamma function of `x`.
+  # 
+  # Notice the use of `ln` prefix to differentiate from
+  # Ruby's built-in `#lgamma` function which returns an Array.
+  #
+  def self.lngamma(x)
+    lgamma(x).first
+  end
+
+  # Old name used by Extmath library.
+  def self.ln_gamma(x)
+    lgamma(x).first
+  end
+
+end
+

data/lib/standard/facets/math/log2.rb

@@ -0,0 +1,14 @@
+module Math
+
+  INVERSE_LN_2 = 1.0 / ::Math.log(2.0)
+
+  unless defined?(log2)
+
+    # Logarithmus dualis of +x+.
+    def self.log2(x)
+      Math.log(x) * INVERSE_LN_2
+    end
+
+  end
+
+end

data/lib/standard/facets/math/max.rb

@@ -0,0 +1 @@
+require 'facets/math/min'

data/lib/standard/facets/math/mean.rb

@@ -0,0 +1,16 @@
+require  'facets/math/sum'
+
+module Math
+
+  # Mean average.
+  def self.mean(array, &blk)
+    s = array.size
+    return 0.0 if s == 0
+    sum(array, &blk) / s
+  end
+
+  class << self
+    alias_method :mean_average, :mean
+  end
+
+end

data/lib/standard/facets/math/median.rb

@@ -0,0 +1,30 @@
+require 'facets/math/percentile'
+
+module Math
+
+  # Returns the numerical median for the an array of values;
+  # or nil if array is empty.
+  #
+  def self.median(array)
+    percentile(array, 50)
+  end
+
+# better definition ?
+=begin
+  #
+  def self.median(array)
+    return 0 if array.size == 0
+
+    tmp = array.sort
+    mid = tmp.size / 2
+
+    if (tmp.size % 2) == 0
+	    (tmp[mid-1] + tmp[mid]).to_f / 2
+    else
+	    tmp[mid]
+    end
+  end
+=end
+
+end
+

data/lib/standard/facets/math/min.rb

@@ -0,0 +1,35 @@
+module Math
+
+  #
+  def self.min(array, &block)
+    if block_given?
+      if min = array.find{ |i| i }
+        min = yield(min)
+        array.each do |i|
+          j = yield(i)
+          min = j if min > j
+        end
+        min
+      end
+    else
+      array.min
+    end
+  end
+
+  #
+  def self.max(array, block)
+    if block_given?
+      if max = find{|i| i}
+        max = yield(max)
+        each{|i|
+          j = yield(i)
+          max = j if max < j
+        }
+        max
+      end
+    else
+      array.max
+    end
+  end
+
+end

data/lib/standard/facets/math/percentile.rb

@@ -0,0 +1,40 @@
+module Math
+
+  # Returns the percentile value for percentile _pcnt_; nil if array is empty.
+  #
+  # +pcnt+ should be expressed as an integer, e.g. `percentile(90)` returns
+  # the 90th percentile of the array.
+  #
+  # Algorithm from NIST[http://www.itl.nist.gov/div898/handbook/prc/section2/prc262.htm]
+  #
+  # NOTE: This is not a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  #
+  # CREDIT: Ben Koski
+  #
+  # @non-core
+  #   require 'facets/math/percentile'
+  #
+  def self.percentile(array, pcnt)
+    sorted_array = array.sort
+
+    return nil if array.length == 0
+
+    rank  = (pcnt.to_f / 100) * (array.length + 1)
+    whole = rank.truncate
+ 
+    # if has fractional part
+    if whole != rank
+      s0 = sorted_array[whole - 1]
+      s1 = sorted_array[whole]
+
+      f = (rank - rank.truncate).abs
+
+      return (f * (s1 - s0)) + s0
+    else
+      return sorted_array[whole - 1]
+    end
+  end
+  
+end
+

data/lib/standard/facets/math/pow.rb

@@ -0,0 +1,13 @@
+module Math
+
+  # `x` to the power `y`.
+  def self.pow(x, y)
+    x ** y
+  end
+
+  # `x` to the power `y`.
+  def self.pwr(x, y)
+    x ** y
+  end
+
+end

data/lib/standard/facets/math/pstd.rb

@@ -0,0 +1 @@
+require 'facets/math/std'

data/lib/standard/facets/math/pvariance.rb

@@ -0,0 +1 @@
+require 'facets/math/variance'

data/lib/standard/facets/math/rmd.rb

@@ -0,0 +1,16 @@
+require 'facets/math/approx_equal'
+
+module Math
+
+  # Calculates the relative mean difference of this sample.
+  # Makes use of the fact that the Gini Coefficient is half the RMD.
+  def self.rmd(array)
+    return 0.0 if approx_equal(mean(array), 0.0)
+    gini_coefficient(array) * 2
+  end
+
+  class << self
+    alias_method  :relative_mean_difference, :rmd
+  end
+
+end

data/lib/standard/facets/math/root.rb

@@ -0,0 +1,8 @@
+module Math
+
+  # The `y` root of `x`.
+  def self.root(x, y)
+    x ** (1.0 / y)
+  end
+
+end

data/lib/standard/facets/math/round.rb

@@ -0,0 +1,9 @@
+module Math
+
+  # Round number to an integer.
+  #
+  def self.round(x)
+    x.round
+  end
+
+end

data/lib/standard/facets/math/sec.rb

@@ -0,0 +1,8 @@
+module Math
+
+  # Secans of +x+.
+  def self.sec(x)
+    1.0 / cos(x)
+  end
+
+end

data/lib/standard/facets/math/sech.rb

@@ -0,0 +1,8 @@
+module Math
+
+  # Secans hyperbolicus of +x+
+  def self.sech(x)
+    1.0 / cosh(x)
+  end
+
+end

data/lib/standard/facets/math/sign.rb

@@ -0,0 +1,20 @@
+module Math
+
+  # Sign of `x`. This function returns `-1.0` if `x` is negative,
+  # `+1.0` if `x` is positive `x`, and `0.0` if `x = 0`.
+  def self.sign(x, zero=0.0)
+    (x > 0.0) ? 1.0 : ((x < 0.0) ? -1.0 : zero)
+  end
+
+  # Same as `Math.sign`.
+  def self.sgn(x, zero=0.0)
+    (x > 0.0) ? 1.0 : ((x < 0.0) ? -1.0 : zero)
+  end
+
+  # The *Heaviside step function*, also called the the *unit step function*.
+  # This functions works like `Math.sign` but by default returns `1.0` for zero.
+  def self.unit_step(x, zero=1.0)
+    (x > 0.0) ? 1.0 : ((x < 0.0) ? -1.0 : zero)
+  end
+
+end

data/lib/standard/facets/math/sinc.rb

@@ -0,0 +1,8 @@
+module Math
+
+  # Sinc function of +x+.
+  def self.sinc(x)
+    (x == 0.0) ? 1.0 : sin(x) / x
+  end
+
+end

data/lib/standard/facets/math/sqr.rb

@@ -0,0 +1,8 @@
+module Math
+
+  # Square of number.
+  def self.sqr(x)
+    x * x
+  end
+
+end

data/lib/standard/facets/math/sqsolve.rb

@@ -0,0 +1,55 @@
+require 'facets/math/linsolve'
+
+module Math
+
+  # Returns array of real solution of <code>ax**2 + bx + c = d</code>
+  # or <code>nil</code> if no or an infinite number of solutions exist.
+  # If +d+ is missing it is assumed to be 0.
+  #
+  # In order to solve <code>ax**2 + bx + c = d</code> +sqsolve+ identifies several cases:
+  # * <code>a == 0:</code>
+  #   The equation to be solved is the linear equation <code>bx + c = d</code>. #sqsolve> delegates the computation to
+  #   #linsolve>. If it results in +nil+, +nil+ is returned (not <code>[nil]</code>!). Otherwise a one-element array
+  #   containing result of #linsolve is returned.
+  # * <code>a != 0:</code>
+  #    The equation to be solved actually is a second order one.
+  #    * <code>c == d</code>
+  #      The equation to be solved is <code>ax**2 + bx = 0</code>. One solution of this equation obviously is
+  #      <code>x = 0</code>, the second one solves <code>ax + b = 0</code>. The solution of the latter is
+  #      delegated to +linsolve+. An array containing both results in ascending order is returned.
+  #    * <code>c != d</code>
+  #      The equation cannot be separated into <code>x</code> times some factor.
+  #      * <code>b == 0</code>
+  #        The equation to be solved is <code>ax**2 + c = d</code>. This can be written as the linear equation
+  #        <code>ay + c = d</code> with <code>y = x ** 2</code>. The solution of the linear equation is delegated
+  #        to +linsolve+. If the returned value for +y+ is +nil+, that becomes the overall return value.
+  #        Otherwise an array containing the negative and positive squareroot of +y+ is returned
+  #      * <code>b != 0 </code>
+  #        The equation cannot be reduced to simpler cases. We now first have to compute what is called the
+  #        discriminant <code>x = b**2 + 4a(d - c)</code> (that's what we need to compute the square root of).
+  #        If the descriminant is negative no real solution exists and <code>nil</code> is returned. The ternary
+  #        operator checking whether <code>b</code> is negative does ensure better numerical stability --only one
+  #        of the two solutions is computed using the widely know formula for solving second order equations.
+  #        The second one is computed from the fact that the product of both solutions is <code>(c - d) / a</code>.
+  #        Take a look at a book on numerical mathematics if you don't understand why this should be done.
+  #
+  # @author Josef Schugt
+  def self.sqsolve(a, b, c, d = 0.0)
+    if a == 0.0
+      x = linsolve(b, c, d)
+      return x.nil? ? nil: [ linsolve(b, c, d) ]
+    else
+      return [0.0, linsolve(a, b)].sort if c == d
+      if b == 0.0
+        x = linsolve(a, c, d)
+        x < 0.0 ? nil : [-Math.sqrt(x), Math.sqrt(x)]
+      else
+        x = b * b + 4.0 * a * (d - c)
+        return nil if x < 0.0
+        x = b < 0 ? b - Math.sqrt(x) : b + Math.sqrt(x)
+        [-0.5 * x / a, 2.0 * (d - c) / x].sort
+      end
+    end
+  end
+
+end

data/lib/standard/facets/math/std.rb

@@ -0,0 +1,27 @@
+require 'facets/math/variance'
+
+module Math
+
+  # Standard deviation of a sample.
+  #
+  def self.std(array, &block)
+    sqrt(variance(array, &block))
+  end
+
+  class << self
+    alias_method :standard_deviation, :std
+  end
+
+  # Standard deviation of a population.
+  #
+  def self.pstd(array, &block)
+    Math::sqrt(pvariance(array, &block))
+  end
+
+  # Calculates the standard error of a sample.
+  def self.stderr(array)
+    return 0.0 if array.size < 2
+    std(array) / sqrt(array.size)
+  end
+
+end

data/lib/standard/facets/math/stderr.rb

@@ -0,0 +1 @@
+require 'facets/math/std'

data/lib/standard/facets/math/sum.rb

@@ -0,0 +1,16 @@
+module Math
+
+  # Returns sum.  When a block is given, summation is taken over the 
+  # each result of block evaluation.
+  #
+  def self.sum(array) #:yield:
+    sum = 0.0
+    if block_given?
+      array.each{|i| sum += yield(i)}
+    else
+      array.each{|i| sum += i}
+    end
+    sum
+  end
+
+end

data/lib/standard/facets/math/summed_sqdevs.rb

@@ -0,0 +1,14 @@
+require 'facets/math/sum'
+require 'facets/math/mean'
+
+module Math
+
+  # The sum of the squared deviations from the mean.
+  #
+  def self.summed_sqdevs(array)
+    return 0 if array.size < 2
+    m = mean(array)
+    sum(array.map{ |x| (x - m) ** 2 })
+  end
+
+end

data/lib/standard/facets/math/tau.rb

@@ -0,0 +1,5 @@
+module Math
+  # See http://tauday.com/tau-manifesto
+  TAU = 2 * PI
+end
+

data/lib/standard/facets/math/tgamma.rb

@@ -0,0 +1,10 @@
+require 'facets/math/lgamma'
+
+module Math
+
+  # Exp of LGamma.
+  def self.tgamma(x)
+    exp(lngamma(x)) #exp(log(gamma(x).abs)
+  end
+
+end

data/lib/standard/facets/math/theil_index.rb

@@ -0,0 +1,24 @@
+require 'facets/math/sum'
+require 'facets/math/mean'
+require 'facets/math/approx_equal'
+
+module Math
+
+  # Calculates the Theil index (a statistic used to measure
+  # economic inequality).
+  #
+  # TI = \sum_{i=1}^N \frac{x_i}{\sum_{j=1}^N x_j} ln \frac{x_i}{\bar{x}}
+  #
+  #   http://en.wikipedia.org/wiki/Theil_index
+  #
+  def self.theil_index(array)
+    return -1 if array.size <= 0 or any? { |x| x < 0 }
+    return  0 if array.size <  2 or all? { |x| approx_equal(x, 0) }
+    m = mean(array)
+    s = sum(array).to_f
+    inject(0) do |theil, xi|
+	    theil + ((xi > 0) ? (log(xi.to_f/m) * xi.to_f/s) : 0.0)
+    end
+  end
+
+end

data/lib/standard/facets/math/variance.rb

@@ -0,0 +1,31 @@
+require 'facets/math/summed_sqdevs'
+
+module Math
+
+  #
+  def self.variance(array, &block)
+    sum2 = if block_given?
+      sum(array){ |i| j = block[i]; j*j }
+    else
+      sum(array){ |i| i**2 }
+    end
+    sum2/array.size - mean(array, &block)**2
+  end
+
+  # Variance of the sample.
+  # Variance of 0 or 1 elements is 0.0.
+  #
+  # TODO: Same as #variance? Then choose one.
+  def self.variance2(array)
+    return 0.0 if array.size < 2
+    summed_sqdevs(array) / (array.size - 1)
+  end
+
+  # Variance of a population.
+  # Variance of 0 or 1 elements is 0.0.
+  def self.pvariance(array)
+    return 0.0 if array.size < 2
+    summed_sqdevs(array) / array.size
+  end
+
+end

data/lib/standard/facets/math.rb

@@ -0,0 +1,58 @@
+require_relative 'math/abs.rb'
+require_relative 'math/acot.rb'
+require_relative 'math/acoth.rb'
+require_relative 'math/acsc.rb'
+require_relative 'math/acsch.rb'
+require_relative 'math/amd.rb'
+require_relative 'math/approx_equal.rb'
+require_relative 'math/asec.rb'
+require_relative 'math/asech.rb'
+require_relative 'math/atkinson_index.rb'
+require_relative 'math/beta.rb'
+require_relative 'math/cdf.rb'
+require_relative 'math/ceil.rb'
+require_relative 'math/cot.rb'
+require_relative 'math/coth.rb'
+require_relative 'math/csc.rb'
+require_relative 'math/csch.rb'
+require_relative 'math/delta.rb'
+require_relative 'math/ec.rb'
+require_relative 'math/epsilon.rb'
+require_relative 'math/exp2.rb'
+require_relative 'math/exp10.rb'
+require_relative 'math/factorial.rb'
+require_relative 'math/floor.rb'
+require_relative 'math/gcd.rb'
+require_relative 'math/gini_coefficient.rb'
+require_relative 'math/kldivergence.rb'
+require_relative 'math/lcm.rb'
+require_relative 'math/lgamma.rb'
+require_relative 'math/lngamma.rb'
+require_relative 'math/linsolve.rb'
+require_relative 'math/log2.rb'
+require_relative 'math/max.rb'
+require_relative 'math/mean.rb'
+require_relative 'math/median.rb'
+require_relative 'math/min.rb'
+require_relative 'math/percentile.rb'
+require_relative 'math/pow.rb'
+require_relative 'math/pstd.rb'
+require_relative 'math/pvariance.rb'
+require_relative 'math/rmd.rb'
+require_relative 'math/root.rb'
+require_relative 'math/round.rb'
+require_relative 'math/sec.rb'
+require_relative 'math/sech.rb'
+require_relative 'math/sign.rb'
+require_relative 'math/sinc.rb'
+require_relative 'math/sqr.rb'
+require_relative 'math/sqsolve.rb'
+require_relative 'math/std.rb'
+require_relative 'math/stderr.rb'
+require_relative 'math/sum.rb'
+require_relative 'math/summed_sqdevs.rb'
+require_relative 'math/tau.rb'
+require_relative 'math/tgamma.rb'
+require_relative 'math/theil_index.rb'
+require_relative 'math/variance.rb'
+