Lower bound method, default confidence, and use continuity correction by default - closes #1

Author: ankane

README.md

@@ -9,13 +9,25 @@ Inspired by [How Not To Sort By Average Rating](http://www.evanmiller.org/how-no
 3 positive ratings out of 5 with 95% confidence
 
 ```ruby
-WilsonScore.interval(3, 5, 0.95)
+WilsonScore.lower_bound(3, 5)
 ```
 
-[Continuity correction](http://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval_with_continuity_correction) can improve the score, especially for a small number of samples (n < 30).  Set the last paramter to true to use it.
+[Continuity correction](http://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval_with_continuity_correction) can improve the score, especially for a small number of samples (n < 30).  As of version 0.1.0, it is enabled by default.  To disable continuity correction, use:
 
 ```ruby
-WilsonScore.interval(3, 5, 0.95, true)
+WilsonScore.lower_bound(3, 5, correction: false)
+```
+
+The default confidence level is 95%. To change this, use:
+
+```ruby
+WilsonScore.lower_bound(3, 5, confidence: 0.99)
+```
+
+To get the full interval, use:
+
+```ruby
+WilsonScore.interval(3, 5)
 ```
 
 ## Star Ratings
@@ -28,16 +40,10 @@ A product has two ratings - one 4 star and one 5 star.
 average_rating = 4.5
 total_ratings = 2
 rating_range = 1..5  # 1 to 5 stars
-confidence = 0.95    # 95%
 
-interval = WilsonScore.rating_interval(average_rating, total_ratings, rating_range, confidence)
-lower_bound = interval.first
+WilsonScore.rating_lower_bound(average_rating, total_ratings, rating_range)
 ```
 
-Use the lower bound of the interval to sort items.
-
-Again, you can set the last parameter to `true` for continuity correction.
-
 ## Installation
 
 Add this line to your application's Gemfile:

lib/wilson_score.rb

@@ -3,7 +3,12 @@
 module WilsonScore
 
   # http://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval
-  def self.interval(k, n, confidence, correction = false)
+  def self.interval(k, n, *args)
+    args = args.dup
+    options = args[-1].is_a?(Hash) ? args.pop : {}
+    confidence = args[0] || options[:confidence] || 0.95
+    correction = !args[1].nil? ? args[1] : (options.has_key?(:correction) ? options[:correction] : true)
+
     z = pnorm(1 - (1 - confidence) / 2.0)
     phat = k / n.to_f
     z2 = z**2
@@ -23,14 +28,27 @@ def self.interval(k, n, confidence, correction = false)
     end
   end
 
-  def self.rating_interval(avg, n, score_range, confidence, correction = false)
+  def self.lower_bound(k, n, options = {})
+    interval(k, n, options).first
+  end
+
+  def self.rating_interval(avg, n, score_range, *args)
+    args = args.dup
+    options = args[-1].is_a?(Hash) ? args.pop : {}
+    confidence = args[0] || options[:confidence] || 0.95
+    correction = !args[1].nil? ? args[1] : (options.has_key?(:correction) ? options[:correction] : true)
+
     min = score_range.first
     max = score_range.last
     range = max - min
     interval = interval(n * (avg - min) / range, n, confidence, correction)
     (min + range * interval.first)..(min + range * interval.last)
   end
 
+  def self.rating_lower_bound(avg, n, score_range, options = {})
+    rating_interval(avg, n, score_range, options).first
+  end
+
   protected
 
   # from the statistics2 gem

test/wilson_score_test.rb

@@ -3,63 +3,71 @@
 class TestWilsonScore < Minitest::Test
 
   def test_wilson_score
-    interval = WilsonScore.interval(1, 2, 0.95)
+    interval = WilsonScore.interval(1, 2, correction: false)
     assert_in_delta 0.0945, interval.first
     assert_in_delta 0.9055, interval.last
   end
 
+  def test_lower_bound
+    assert_in_delta 0.0267, WilsonScore.lower_bound(1, 2)
+  end
+
   def test_continuity_correction
-    interval = WilsonScore.interval(1, 2, 0.95, true)
+    interval = WilsonScore.interval(1, 2)
     assert_in_delta 0.0267, interval.first
     assert_in_delta 0.9733, interval.last
   end
 
   def test_continuity_correction_zero_one
-    interval = WilsonScore.interval(0, 1, 0.95, true)
+    interval = WilsonScore.interval(0, 1)
     assert_in_delta 0, interval.first
     assert_in_delta 0.9454, interval.last
   end
 
   def test_continuity_correction_zero_ten
-    interval = WilsonScore.interval(0, 10, 0.95, true)
+    interval = WilsonScore.interval(0, 10)
     assert_in_delta 0, interval.first
     assert_in_delta 0.3445, interval.last
   end
 
   def test_continuity_correction_one_ten
-    interval = WilsonScore.interval(1, 10, 0.95, true)
+    interval = WilsonScore.interval(1, 10)
     assert_in_delta 0.0052, interval.first
     assert_in_delta 0.4588, interval.last
   end
 
   def test_continuity_correction_one_fifty
-    interval = WilsonScore.interval(1, 50, 0.95, true)
+    interval = WilsonScore.interval(1, 50)
     assert_in_delta 0.0010, interval.first
     assert_in_delta 0.1201, interval.last
   end
 
   def test_continuity_correction_one_one
-    interval = WilsonScore.interval(1, 1, 0.95, true)
+    interval = WilsonScore.interval(1, 1)
     assert_in_delta 0.0546, interval.first
     assert_in_delta 1, interval.last
   end
 
   def test_continuity_correction_one_three
-    interval = WilsonScore.interval(1, 3, 0.95, true)
+    interval = WilsonScore.interval(1, 3)
     assert_in_delta 0.0176, interval.first
     assert_in_delta 0.8747, interval.last
   end
 
   def test_rating
-    interval = WilsonScore.rating_interval(5, 1, 1..5, 0.95)
+    interval = WilsonScore.rating_interval(5, 1, 1..5, correction: false)
     assert_in_delta 1.8262, interval.first
     assert_in_delta 5, interval.last
   end
 
   def test_rating_advanced
-    interval = WilsonScore.rating_interval(3.7, 10, 1..5, 0.95)
+    interval = WilsonScore.rating_interval(3.7, 10, 1..5, correction: false)
     assert_in_delta 2.4998, interval.first
     assert_in_delta 4.5117, interval.last
   end
 
+  def test_rating_lower_bound
+    assert_in_delta 1.8262, WilsonScore.rating_lower_bound(5, 1, 1..5, correction: false)
+  end
+
 end