accumulators 0.3.0 → 0.4.0

data/README.md

@@ -2,10 +2,23 @@ accumulators
 ============
 
 A set of statistical accumulators for Ruby. There is a range of containers for
-different measures, such as count, mean, and mean-variance. You can add values to
-the containers, and ask for their respective statistical measures. The accumulators
-use incremental algorithms to update their measures with each addition, so you can
-add lots of values without needing lots of memory.
+different measures, such as count, sum, mean, and mean-variance. You can add values to
+the containers, and ask for their respective statistical measures. 
+
+Where appropriate the accumulators use incremental algorithms to update their
+measures with each addition, so you can add lots of values without needing lots of
+memory. (see http://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#On-line_algorithm)
+
+The accumulators can be combined. e.g. if you have two mean-variance
+accumulators, each of which has their own mean and variance, you can add them
+together to get the mean and variance of the combined samples.
+
+Always remember that floating-point arithmetic is not precise, so if you are
+using these accumulators for anything important, and especially if you are
+accumulating lots of samples, you should run your own tests on the accuracy of
+the calculations. I am not aware of any significant issues, but I make no promises
+and provide no assurances as to the accuracy or stability of these
+calculations.
 
 Installation
 ------------
@@ -16,31 +29,75 @@ Example Usage
 
     $ irb
     >> require 'accumulators'
-    >> mean = Accumulators::Mean.new
-    >> mean.add 1
-    >> mean.add 2
-    >> mean.add 3
-    >> mean.add 4
-    >> mean.count
+    >> meanvar = Accumulators:MeanVariance.new
+    >> meanvar.add 1
+    >> meanvar.add 2
+    >> meanvar.add 3
+    >> meanvar.add 4
+    >> meanvar.count
     => 4
-    >> mean.mean
+    >> meanvar.mean
     => 2.5
+    >> meanvar.variance
+    => 1.0
+    >> meanvar.variance(type: :sample)
+    => 1.0
+    >> meanvar.variance(type: :population)
+    => 1.25
+    >> meanvar.stddev
+    => 1.0
+    >> meanvar.stddev(type: :population)
+    => 1.118033988749895
+
+Example of combining accumulators
+---------------------------------
+Accumulators of the same type can be added together. Here we will add three
+numbers to one mean-variance accumulator, three to another, and show that their
+combined mean and variance is equal to that of the single accumulator which
+saw all the values, within the usual constraints of floating-point arithmetic.
+
+    >> mv1 = Accumulators::MeanVariance.new  # sees the first 3 values
+    >> mv2 = Accumulators::MeanVariance.new  # sees the second 3 values
+    >> mv  = Accumulators::MeanVariance.new  # sees all values
+    >>
+    >> [1.1, 2.2, 3.3].each {|n| mv1.add n; mv.add n}
+    >> [4.4, 5.5, 6.6].each {|n| mv2.add n; mv.add n}
+    >>
+    >> mv1.mean
+    => 2.2
+    >> mv1.variance
+    => 0.6049999999999998
+    >>
+    >> mv2.mean
+    => 5.5
+    >> mv2.variance
+    => 0.6049999999999998
+    >>
+    >> mv.mean
+    => 3.8499999999999996
+    >> mv.variance
+    => 3.025
+    >>
+    >> mv1.add mv2
+    >> mv1.mean
+    => 3.8499999999999996
+    >> mv1.variance
+    >> 3.0249999999999995  # close to 3.025 - discrepancy from floating-point
 
 Available accumulators
 ----------------------
 
 * Count
+* Sum
 * Mean
 * MeanVariance
 
 TODO
 ----
 
-* Allow choosing between biased & unbiased variance/standard devation
 * Skew?
 * Weighted Means
 * min, max, and min-max
-* sum
 
 Contributing to accumulators
 ----------------------------

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

data/accumulators.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{accumulators}
-  s.version = "0.3.0"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Gavin Heavyside"]
@@ -31,9 +31,11 @@ Gem::Specification.new do |s|
     "lib/accumulators/count.rb",
     "lib/accumulators/mean.rb",
     "lib/accumulators/mean_variance.rb",
+    "lib/accumulators/sum.rb",
     "spec/lib/accumulators/count_spec.rb",
     "spec/lib/accumulators/mean_spec.rb",
     "spec/lib/accumulators/mean_variance_spec.rb",
+    "spec/lib/accumulators/sum_spec.rb",
     "spec/spec_helper.rb"
   ]
   s.homepage = %q{http://github.com/hgavin/accumulators}

data/lib/accumulators.rb

@@ -1,5 +1,6 @@
 module Accumulators
   autoload :Count, "accumulators/count"
+  autoload :Sum, "accumulators/sum"
   autoload :Mean, "accumulators/mean"
   autoload :MeanVariance, "accumulators/mean_variance"
 end

data/lib/accumulators/sum.rb

@@ -0,0 +1,19 @@
+module Accumulators
+  class Sum
+    attr_reader :sum
+
+    def initialize
+      @sum = 0
+    end
+    
+    def add(rhs)
+      if rhs.is_a? Numeric
+        @sum += rhs
+      elsif rhs.is_a? self.class
+        @sum += rhs.sum
+      else
+        raise ArgumentError.new("You may not add #{rhs.class} to #{self.class}")
+      end
+    end
+  end
+end

data/spec/lib/accumulators/sum_spec.rb

@@ -0,0 +1,93 @@
+require 'spec_helper'
+
+module Accumulators
+  describe Sum do
+    let(:sum){ Sum.new }
+
+    context "Creation" do
+      it "can be created" do
+        lambda{ Sum.new }.should_not raise_error
+      end
+
+      it "returns a sum of 0 before anything is added to it" do
+        sum.sum.should == 0
+      end
+    end
+
+    context "adding numbers or distributions" do
+      it "allows integers to be added" do
+        lambda { sum.add 5 }.should_not raise_error
+      end
+
+      it "allows floats to be added" do
+        lambda { sum.add 3.4 }.should_not raise_error
+      end
+
+      it "allows other Sum distributions to be added" do
+        lambda { sum.add Sum.new }.should_not raise_error
+      end
+
+      it "raises an ArgumentError if a String is added" do
+        lambda { sum.add "1.5" }.should raise_error(
+          ArgumentError,
+          "You may not add String to Accumulators::Sum")
+      end
+    end
+
+    context "Correctness of int additions" do
+      it "should return an Integer 6 when 1,2,3 is added" do
+        (1..3).each{ |i| sum.add i }
+
+        sum.sum.should be_a Integer
+        sum.sum.should == 6
+      end
+      
+      it "should calculate the sum correctly for a set of 1000 random integers" do
+        vals = []
+        1000.times do 
+          vals << rand(100000)
+          sum.add vals.last
+        end
+        sum.sum.should be_a Integer
+        sum.sum.should == vals.reduce(:+)
+      end
+    end
+
+    context "Correctness of float additions" do
+      it "should return a Float 6.1 when 1.1, 2.8, 2.2 is added" do
+        [1.1,2.8,2.2].each{|f| sum.add f}
+
+        sum.sum.should be_a Float
+        sum.sum.should be_within(EPSILON).of(6.1)
+      end
+
+      it "should calculate the sum correctly for a set of 1000 random floats" do
+        vals = []
+        1000.times do
+          vals << rand * 1000000
+          sum.add vals.last
+        end
+
+        sum.sum.should be_a Float
+        sum.sum.should be_within(EPSILON).of(vals.reduce(:+))
+      end
+    end
+
+    context "Correctness of accumulator additions" do
+      it "combines two sums correctly" do
+        s2 = Sum.new
+        vals = []
+        500.times do 
+          vals << rand * 1000*1000
+          sum.add vals.last
+          vals << rand * 100*1000
+          s2.add vals.last
+        end
+
+        sum.add(s2)
+        sum.sum.should be_a Float
+        sum.sum.should be_within(EPSILON).of(vals.reduce(:+))
+      end
+    end
+  end
+end

metadata

@@ -2,7 +2,7 @@
 name: accumulators
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Gavin Heavyside
@@ -103,9 +103,11 @@ files:
 - lib/accumulators/count.rb
 - lib/accumulators/mean.rb
 - lib/accumulators/mean_variance.rb
+- lib/accumulators/sum.rb
 - spec/lib/accumulators/count_spec.rb
 - spec/lib/accumulators/mean_spec.rb
 - spec/lib/accumulators/mean_variance_spec.rb
+- spec/lib/accumulators/sum_spec.rb
 - spec/spec_helper.rb
 has_rdoc: true
 homepage: http://github.com/hgavin/accumulators
@@ -121,7 +123,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -417395174434128828
+      hash: -3603142917674474649
       segments: 
       - 0
       version: "0"