array-statistics 0.1.1

data/History.txt

@@ -0,0 +1,7 @@
+== 0.1.1 2008-10-31
+
+* Fixed badly packaged gem. Whadda ya want? It's my first gem.
+== 0.1.0 2008-10-30
+
+* 1 major enhancement:
+  * Initial release

data/Manifest.txt

@@ -0,0 +1,7 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/array-statistics.rb
+test/test_array-statistics.rb
+

data/README.txt

@@ -0,0 +1,64 @@
+= array-statistics
+
+http://rubyforge.org/projects/array-statistic/
+
+== DESCRIPTION:
+
+array-statistics adds statistical operations to the ruby Array class. array-statistics supercedes the old gem "array_statistics"
+
+== FEATURES/PROBLEMS:
+
+array-statistics add support for:
+* Percentiles
+* Quartiles
+* Median
+* Mean
+* Sum
+* Outliers
+
+== SYNOPSIS:
+
+Array Statistics adds statistical operations to the ruby Array class. 
+The operations work on arrays of numbers or, more interestingly, arrays of _things_.
+Each method added to Array by this gem takes an optional block that defines the "value" on which to base the operation.
+
+For example, 
+require 'rubygems'
+require 'array-statistics' 
+[2,3,55].median #=> 3
+[2,3,55].average #=> 20
+[{:value => 2}, {:value => 3}].sum {|element| element[:value] } #=> 5
+
+
+== REQUIREMENTS:
+
+* rubygems
+
+== INSTALL:
+
+sudo gem install array-statistics
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Bruce Goodwin
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,13 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/array-statistics.rb'
+
+Hoe.new('array-statistics', ArrayStatistics::VERSION) do |p|
+  p.rubyforge_name = 'array-statistic' # if different than lowercase project name
+  p.developer('Bruce Goodwin', 'bgruby@gmail.com')
+  #p.remote_rdoc_dir = '' # Release to root
+end
+
+# vim: syntax=Ruby

data/lib/array-statistics.rb

@@ -0,0 +1,336 @@
+
+#:stopdoc:
+  
+# no need for these yet... maybe later.
+# $:.unshift(File.dirname(__FILE__)) unless
+#  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+#:startdoc:
+
+module ArrayStatistics
+  VERSION = '0.1.1'
+end
+class Array
+  @as_sort_dirty = true
+  @as_last_comparison_block = nil
+
+  # Get percent order statistic based on "order statistic"  from here: http://mathworld.wolfram.com/topics/RankStatistics.html
+  # Given some percentage between 0 and 1 (inclusive) return the greatest value in the subarray of this array which contains
+  # the bottom percent_less_than values of this array.
+  # 
+  # Like most methods in this package, this method takes an optional block that defines the "value" of the objects in the array.
+  # This block can be safely skipped if the array contains numbers.
+  def percentile(percent_less_than, &value_block) #  :yields: element
+    value_block = proc{|element| element} unless block_given?
+    sort! do |x, y|
+      value_block.call(x) <=> value_block.call(y)
+    end
+
+    percent_less_than = 0 if percent_less_than < 0
+    return nil if percent_less_than == 0
+    percent_less_than = 1 if percent_less_than > 1
+    percentile_i = (percent_less_than * (length-1)).floor
+    return self[percentile_i]
+  end
+
+  # Get percent rank based on "statistical rank" from here:http://mathworld.wolfram.com/topics/RankStatistics.html
+  # Given some value, find the percentage of its rank in this array 
+  # the number returned will be the number between 0 and 1 (inclusive) which represents the percentage of values 
+  # in this array which are less than or equal to the value passed in.
+  #
+  # Like most methods in this package, this method takes an optional block that defines the "value" of the objects in the array.
+  # This block can be safely skipped if the array contains numbers.
+  def percentile_rank(value, &value_block) # :yields: element
+    value_block = proc{|element| element} unless block_given?
+    sort! do |x, y|
+      value_block.call(x) <=> value_block.call(y)
+    end
+    return 0.0 if value < value_block.call(self[0])
+    each_index do |i|
+      if(value_block.call(self[i]) > value)
+
+        return i.to_f/length 
+      end
+    end
+    return 1
+  end
+
+  # Get the median value of this array. 
+  #
+  # Like most methods in this package, this method takes an optional block that defines the "value" of the objects in the array.
+  # This block can be safely skipped if the array contains numbers.
+  def median(sort_required=true, &value_block) # :yields: element
+    return 0 if empty? #to reduce instances of calling math methods on nil.
+    value_block = proc{|element| element} unless block_given?
+
+    median_index_arr = median_indices(&value_block)
+    median_vals = median_index_arr.collect do |element_index|
+      value_block.call(self[element_index])
+    end
+
+    median_vals.average
+  end
+
+  # returns either a single or double-value array containing the index or surrounding indeces 
+  #
+  # Like most methods in this package, this method takes an optional block that defines the "value" of the objects in the array.
+  # This block can be safely skipped if the array contains numbers.
+  def median_indices(sort_required=true, &value_block) # :yields: element
+    return 0 if length == 0
+    value_block = proc{|element| element} unless block_given?
+    if(sort_required) 
+      sort! do |x, y|
+        value_block.call(x) <=> value_block.call(y)
+      end
+    end
+
+    median_index_arr = [length / 2]
+    if(length % 2 == 0)
+      median_index_arr.unshift(median_index_arr[0]-1)
+    end
+
+    median_index_arr
+  end
+
+  #returns an array with 2 values. The values are the first and third quartile indices following the same rules as the results of the median_indices method
+  #
+  # Like most methods in this package, this method takes an optional block that defines the "value" of the objects in the array.
+  # This block can be safely skipped if the array contains numbers.
+  def quartile_indices(&value_block) # :yields: element
+    median_i = median_indices(&value_block)
+    low_end = median_i[0] 
+    high_start = median_i[median_i.length() -1] 
+
+    low_arr = self[0..low_end]
+    high_arr = self[high_start..-1]
+
+    q1_indices = low_arr.median_indices(false, &value_block)
+    q3_indices = high_arr.median_indices(false, &value_block)
+    q3_indices.collect! do |index|
+      index + high_start
+    end
+    return [q1_indices, q3_indices]
+  end
+
+  #returns an array containing all the outliers in this set
+  #
+  # Like most methods in this package, this method takes an optional block that defines the "value" of the objects in the array.
+  # This block can be safely skipped if the array contains numbers.
+  def outliers(quartile_range_factor=1.5, &value_block) # :yields: element
+    value_block = proc{|element| element} unless block_given?
+    outlier_arr = []
+    outlier_threshold_is = outlier_threshold_indices(quartile_range_factor, &value_block)
+    # puts("Outlier Thresholds Indeces = [#{outlier_threshold_is[0]} <=> #{outlier_threshold_is[1]}]")
+    outlier_arr << self[0..outlier_threshold_is[0]] unless outlier_threshold_is[0].nil?
+    # puts("upper outliers = #{self[outlier_threshold_is[1]..-1] }")
+    outlier_arr << self[outlier_threshold_is[1]..-1] unless outlier_threshold_is[1].nil?
+    return outlier_arr.flatten
+  end
+
+  #removes all the outliers from this set and returns them.
+  #
+  # Like most methods in this package, this method takes an optional block that defines the "value" of the objects in the array.
+  # This block can be safely skipped if the array contains numbers.
+  def remove_outliers!(quartile_range_factor=1.5, &value_block) # :yields: element
+    outlier_arr = []
+    outlier_threshold_is = outlier_threshold_indices(quartile_range_factor, &value_block)
+
+    outlier_arr = outlier_arr + self.slice!(0..outlier_threshold_is[0]) unless outlier_threshold_is[0].nil?
+    #the preceeding slice!() will, of course shift the upper outlier threshold index down
+    high_outlier_index_offset = (outlier_threshold_is[0].nil?)? 0 : outlier_threshold_is[0] + 1
+    outlier_arr = outlier_arr + self.slice!(outlier_threshold_is[1]-high_outlier_index_offset..-1) unless outlier_threshold_is[1].nil?
+    return outlier_arr
+  end
+
+  # Returns an array with two values. 
+  # The first value is the index of the last low outlier in this sorted array (this array will be sorted as a side-effect of this method)
+  # or nil if there are no low-end outliers
+  # The second value is the index of the first high outlier in this sorted array or nil if there are no high-end outliers
+  #
+  # Like most methods in this package, this method takes an optional block that defines the "value" of the objects in the array.
+  # This block can be safely skipped if the array contains numbers.
+  def outlier_threshold_indices(quartile_range_factor=1.5, &value_block) # :yields: element
+    value_block = proc{|element| element} unless block_given?
+    thresholds = outlier_thresholds(quartile_range_factor, &value_block) #this sorts self!
+    low_index = -1
+    while(value_block.call(self[low_index +1] ) < thresholds[0]) do
+      low_index = low_index + 1
+    end
+    low_index = nil if(low_index == -1)
+
+    high_index = length
+    while(value_block.call(self[high_index -1] ) > thresholds[1]) do
+      high_index = high_index - 1
+    end
+    high_index = nil if(high_index == length) 
+    return [low_index, high_index]
+  end
+
+  #returns an array with two values: 
+  # The first value is the low outlier threshhold for this data set
+  # The second value is the high outlier threshhold for this data set
+  #
+  # Like most methods in this package, this method takes an optional block that defines the "value" of the objects in the array.
+  # This block can be safely skipped if the array contains numbers.
+  def outlier_thresholds(quartile_range_factor=1.5, &value_block) # :yields: element
+    value_block = proc{|element| element} unless block_given?
+
+    quartile_is = quartile_indices(&value_block)
+    q1 = quartile_is[0].collect do |element_index|
+      value_block.call(self[element_index])
+    end
+    q1 = q1.average
+
+    q3 = quartile_is[1].collect do |element_index|
+      value_block.call(self[element_index])
+    end
+    q3 = q3.average
+
+    interquartile_range = q3-q1
+    # puts("Interquartile Range = [#{q1} <=> #{q3}], quartile range factor: #{quartile_range_factor}")
+    low_outlier_threshold = q1 - (interquartile_range * quartile_range_factor)
+    high_outlier_threshold = q3 + (interquartile_range * quartile_range_factor)
+    # puts("Outlier Thresholds = [#{low_outlier_threshold} <=> #{high_outlier_threshold}]")
+
+    return [low_outlier_threshold, high_outlier_threshold]
+  end
+
+  # Returns the average of the values in this array.
+  #
+  # Like most methods in this package, this method takes an optional block that defines the "value" of the objects in the array.
+  # This block can be safely skipped if the array contains numbers.
+  def average(&value_block) # :yields: element
+    s = sum(&value_block)
+    s = s.to_f if s.integer?
+    s / length
+  end
+  alias mean average
+  
+  # Returns the sum of all the values in this array.
+  #
+  # Like most methods in this package, this method takes an optional block that defines the "value" of the objects in the array.
+  # This block can be safely skipped if the array contains numbers.
+  def sum(&value_block) # :yields: element
+    value_block = proc{|element| element} unless block_given?
+    s = 0
+    each  do |element| 
+      s = s + value_block.call(element)
+    end
+    s
+  end
+
+  @as_sort_dirty = true
+  @as_last_comparison_block = nil
+
+  alias old_sort! sort! 
+  # Adds smarter sorting: A lot of methods above need the array sorted and they may call one another. This sort! method only sorts the
+  # array if it isn't currently known to be sorted.
+  #
+  # Like most methods in this package, this method takes an optional block that defines the "value" of the objects in the array.
+  # This block can be safely skipped if the array contains numbers.
+  def sort!(&comparison_block) # :yields: element
+     if(dirty? || (comparison_block != @as_last_comparison_block)) 
+       old_sort!(&comparison_block)
+       @as_last_comparison_block = comparison_block
+       clean
+     end
+     self
+  end
+
+#:stopdoc:  
+  def dirty 
+    @as_sort_dirty = true    
+  end
+
+  def dirty? 
+    dirty unless instance_variable_defined? :@as_sort_dirty
+    @as_sort_dirty
+  end
+
+  def clean 
+    @as_sort_dirty = false
+  end
+
+  # BELOW: Modify the array to mark itself as dirty when the array might need resorting.
+
+  # For our purposes "Dirty" doesn't merely mean that the array has been modified, It means
+  # that the array has been modified in a way that could have messed up the sorting. 
+  # For this reason, not all methods that could modify the array are included. e.g. anything 
+  # that *JUST* removes elements doesn't mess up the order of the array, but insertions might.
+
+  # Side-note: there are a lot of array methods that don't follow the destructive-methods-end-in-! naming pattern
+
+  alias as_old_ass []=  
+  def []=(*as_args) 
+    ret = as_old_ass(*as_args)
+    dirty
+    ret 
+  end
+
+  alias as_old_app <<  
+  def <<(*as_args) 
+    ret = as_old_app(*as_args)
+    dirty
+    ret
+  end
+  
+  alias as_old_push push 
+  def push(*as_args)
+    ret = as_old_push(*as_args)
+    dirty
+    ret
+  end
+
+  alias as_old_collect collect! 
+  def collect!(*as_args, &block) 
+    ret = as_old_collect(*as_args, &block)
+    dirty
+    ret
+  end
+
+  alias as_old_map! map! 
+  def map!(*as_args, &block) 
+    ret = as_old_map!(*as_args, &block)
+    dirty
+    ret
+  end
+
+  alias as_old_fill fill 
+  def fill(*as_args, &block) 
+    ret = as_old_fill(*as_args, &block)
+    dirty
+    ret
+  end
+
+  alias as_old_flatten flatten! 
+  def flatten!(*as_args, &block) 
+    ret = as_old_flatten(*as_args, &block)
+    dirty
+    ret
+  end
+
+  alias as_old_replace replace 
+  def replace(*as_args, &block) 
+    ret = as_old_replace(*as_args, &block)
+    dirty
+    ret
+  end
+
+  alias as_old_reverse reverse! 
+  def reverse!(*as_args, &block) 
+    ret = as_old_reverse(*as_args, &block)
+    dirty
+    ret
+  end
+
+  alias as_old_unshift unshift 
+  def unshift(*as_args, &block) 
+    ret = as_old_unshift(*as_args, &block)
+    dirty
+    ret
+  end
+#:startdoc:
+end
+
+
+

data/test/test_array-statistics.rb

@@ -0,0 +1,51 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+class TestArrayStatistics < Test::Unit::TestCase
+
+  def setup
+  end
+  
+  def test_empty_array
+    assert_same(0, [].median)
+    assert_same(0, [].median_indices)    
+  end
+  
+  def test_percentile
+    assert_nil([].percentile(1))
+    #edge cases
+    assert_nil([1,2,3,4,5,6,8].percentile(0))
+    assert_equal(8, [1,2,3,4,5,6,8].percentile(1))
+    assert_equal([1,2,3,4,5,6,8].percentile(135484), [1,2,3,4,5,6,8].percentile(1))
+    assert_equal([1,2,3,4,5,6,8].percentile(-3), [1,2,3,4,5,6,8].percentile(0))
+    #proper handling of midrange values
+    assert_equal(1, [1,2,3,4].percentile(0.0001))
+    assert_equal(1, [1,2,3,4].percentile(0.25))
+    assert_equal(1, [1,2,3,4].percentile(0.26))
+    assert_equal(2, [1,2,3,4].percentile(0.5))
+  end
+  
+  def test_percentile_rank
+    #edge cases
+    assert_equal(0, [1,2,3,4].percentile_rank(-1))
+    assert_equal(1, [1,2,3,4].percentile_rank(19849))
+    #proper handling of midrange values
+    assert_equal(0, [1,2,3,4].percentile_rank(0.99))
+    assert_equal(0.25, [1,2,3,4].percentile_rank(1))
+    assert_equal(0.25, [1,2,3,4].percentile_rank(1.3))
+  end
+  
+  def test_median
+    assert_equal(0, [].median)
+    assert_equal(666, [666].median)
+    assert_equal(1.5, [1,2].median)
+    assert_equal(3, [2,3,4].median)
+    assert_equal(2.5, [1,2,3,4].median)
+  end
+  
+  def test_outliers
+    assert_equal([-60,999,9999], [-60,1,2,3,1,2,3,4,3,2,1,1,1,1,4,4,4,4,3,999, 9999].outliers)
+    
+  end
+end
+
+

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: array-statistics
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Bruce Goodwin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-10-31 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.8.2
+    version: 
+description: array-statistics adds statistical operations to the ruby Array class. array-statistics supercedes the old gem "array_statistics"
+email: 
+- bgruby@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- lib/array-statistics.rb
+- test/test_array-statistics.rb
+has_rdoc: true
+homepage: http://rubyforge.org/projects/array-statistic/
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: array-statistic
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: array-statistics adds statistical operations to the ruby Array class
+test_files: 
+- test/test_array-statistics.rb