conductor 0.7.0 → 0.7.1

data/VERSION

@@ -1 +1 @@
-0.7.0
+0.7.1

data/lib/conductor.rb

@@ -11,17 +11,19 @@ require 'conductor/helpers/dashboard_helper'
 
 class Conductor
   MAX_WEIGHTING_FACTOR = 1.25
-  MINIMUM_LAUNCH_DAYS = 7
+  EQUALIZATION_PERIOD_DEFAULT = 7
   DBG = false
 
   cattr_writer :cache
-  cattr_writer :days_till_weighting
   
   def self.cache
     @@cache || Rails.cache
   end
 
   class << self
+    # Specifies a unique identity for the current visitor.  If no identity is specified 
+    # then a random value is selected.  Conductor makes sure that the same visitor 
+    # will always see the same alternative selections to reduce confusion.
     def identity=(value)
       @conductor_identity = value
     end
@@ -30,10 +32,26 @@ class Conductor
       return (@conductor_identity || ActiveSupport::SecureRandom.hex(16))
     end
     
-    def minimum_launch_days
-      return (@@days_till_weighting || MINIMUM_LAUNCH_DAYS)
+    # The equalization period is the initial amount of time, in days, that conductor 
+    # should apply the max_weighting_factor towards a new alternative to ensure 
+    # that it receives a far shot of performing.
+    #
+    # If an equalization period was not used then any new alternative would 
+    # immediately be weighed very low since it has no conversions and would 
+    # never have a chance of performing
+    def equalization_period=(value)
+      raise "Conductor.equalization_period must be a positive number > 0" unless value.is_a?(Numeric) && value > 0
+      @equalization_period = value
     end
     
+    def equalization_period
+      return (@equalization_period || EQUALIZATION_PERIOD_DEFAULT)
+    end
+    
+    # The attribute for weighting specifies if the conversion_value OR number of conversions 
+    # should be used to calculate the weight.  The default is conversion_value.
+    #
+    # TODO: Allow of avg_conversion_value where acv = conversion_value / conversions
     def attribute_for_weighting=(value)
       raise "Conductor.attribute_for_weighting must be either :views, :conversions or :conversion_value (default)" unless [:views, :conversions, :conversion_value].include?(value) 
       @attribute_for_weighting = value

data/lib/conductor/weights.rb

@@ -53,7 +53,7 @@ class Conductor
           group_rows.group_by(&:alternative).each do |alternative_name, alternatives|
             days_ago = compute_days_ago(alternatives)
 
-            if days_ago >= Conductor.minimum_launch_days
+            if days_ago >= Conductor.equalization_period
               data << {:name => alternative_name, :weight => (weighted_moving_avg[alternative_name] / total)}
             else
               recently_launched << {:name => alternative_name, :days_ago => days_ago}
@@ -88,8 +88,8 @@ class Conductor
           # slowly lowers its power until the launch period is over
           max_weight = 1 if data.empty?
           recently_launched.each do |alternative|
-            handicap = (alternative[:days_ago].to_f / Conductor.minimum_launch_days)
-            launch_window = (Conductor.minimum_launch_days - alternative[:days_ago]) if Conductor.minimum_launch_days > alternative[:days_ago]
+            handicap = (alternative[:days_ago].to_f / Conductor.equalization_period)
+            launch_window = (Conductor.equalization_period - alternative[:days_ago]) if Conductor.equalization_period > alternative[:days_ago]
             Conductor.log("Handicap for #{alternative[:name]} is #{handicap} (#{alternative[:days_ago]} days ago)")
             data << {:name => alternative[:name], :weight => max_weight * MAX_WEIGHTING_FACTOR * (1 - handicap), :launch_window => launch_window}
           end

data/test/test_conductor.rb

@@ -22,13 +22,20 @@ class TestConductor < Test::Unit::TestCase
       x = Conductor.cache.read('testing')
       assert_equal x, 'value'
     end
-    
-    should "allow for the minimum_launch_days to be configurable" do
-      Conductor.days_till_weighting = 3
-      assert_equal(3, Conductor.minimum_launch_days)
+
+    should "allow for the equalization_period to be configurable" do
+      Conductor.equalization_period = 3
+      assert_equal(3, Conductor.equalization_period)
+    end
+
+    should "raise an error if a non-numeric value, negative or 0 value is specified for the equalization_period" do
+      assert_raise(RuntimeError, LoadError) { Conductor.equalization_period = 'junk'}
+      assert_raise(RuntimeError, LoadError) { Conductor.equalization_period = -1.0}
+      assert_raise(RuntimeError, LoadError) { Conductor.equalization_period = 0}
+      assert_nothing_raised(RuntimeError, LoadError) { Conductor.equalization_period = 3}
     end
-    
-    should "raise an error if an improper attribute is specified for @@attribute_for_weighting" do
+
+    should "raise an error if an improper attribute is specified for @attribute_for_weighting" do
       assert_raise(RuntimeError, LoadError) { Conductor.attribute_for_weighting = :random}
     end
 
@@ -133,7 +140,7 @@ class TestConductor < Test::Unit::TestCase
       assert Conductor::Experiment::Daily.all.detect {|x| x.views > 0}
       assert Conductor::Experiment::Daily.all.detect {|x| x.conversion_value > 0}
     end
-    
+
     should "correctly populate weighting table when selecting a value" do
       selected = Conductor::Experiment.pick('a_group', ["a", "b", "c"])
       assert_equal 3, Conductor::Experiment::Weight.count
@@ -141,48 +148,49 @@ class TestConductor < Test::Unit::TestCase
 
     should "pull weights from the cache" do
       Conductor::Experiment.pick('a_group', ["a", "b", "c"])
-      
+
       (1..100).each do |x|
         Conductor.identity = ActiveSupport::SecureRandom.hex(16)
         Conductor::Experiment.pick('a_group', ["a", "b", "c"])
       end
-      
-      # => if this works the history table should have only been updated one time not 101 so there should 
+
+      # => if this works the history table should have only been updated one time not 101 so there should
       # => be three records (one for a, b and c)
       assert_equal 3, Conductor::Experiment::History.count
     end
-    
+
     should "pull weights from the cache and then recreate weights when the alternative list changes" do
       Conductor::Experiment.pick('a_group', ["a", "b", "c"])
-      
+
       (1..100).each do |x|
         Conductor.identity = ActiveSupport::SecureRandom.hex(16)
         Conductor::Experiment.pick('a_group', ["a", "b", "c"])
       end
 
-      Conductor.identity = ActiveSupport::SecureRandom.hex(16)      
+      Conductor.identity = ActiveSupport::SecureRandom.hex(16)
       Conductor::Experiment.pick('a_group', ["a", "c"])
-      
-      # => if this works the history table should have only been updated one time not 101 so there should 
+
+      # => if this works the history table should have only been updated one time not 101 so there should
       # => be FIVE records (one for a, b and c and then one for a and c)
       assert_equal 5, Conductor::Experiment::History.count
     end
   end
 
   context "conductor" do
-    should "populate the weighting table with equal weights if all new options are launched" do
+    setup do
+      wipe
       seed_raw_data(100, 7)
-
-      # rollup
       Conductor::RollUp.process
+    end
 
+    should "populate the weighting table with equal weights if all new options are launched" do
       # hit after rollup to populare weight table
       Conductor.identity = ActiveSupport::SecureRandom.hex(16)
-      Conductor.days_till_weighting = 7
+      Conductor.equalization_period = 7
       selected = Conductor::Experiment.pick('a_group', ["a", "b", "c"])
 
       # each weight will be equal to 0.18
-      assert_equal 7, Conductor.minimum_launch_days
+      assert_equal 7, Conductor.equalization_period
       assert_equal 0.54, Conductor::Experiment::Weight.all.sum_it(:weight).to_f
     end
   end
@@ -234,7 +242,7 @@ class TestConductor < Test::Unit::TestCase
       assert_not_nil Conductor::Experiment::History.find(:all, :conditions => 'launch_window > 0')
     end
   end
-  
+
   context "conductor" do
     setup do
       seed_raw_data(500, 30)
@@ -242,7 +250,7 @@ class TestConductor < Test::Unit::TestCase
       # rollup
       Conductor::RollUp.process
     end
-    
+
     should "allow for the number of conversions to be used for weighting instead of conversion_value" do
       Conductor.identity = ActiveSupport::SecureRandom.hex(16)
       Conductor::Experiment.pick('a_group', ["a", "b", "c"])
@@ -252,12 +260,12 @@ class TestConductor < Test::Unit::TestCase
       Conductor.attribute_for_weighting = :conversions
       Conductor::Experiment.pick('a_group', ["a", "b", "c"])
       weights_c = Conductor::Experiment::Weight.all.map(&:weight).sort
-      
+
       # since one is using conversion_value and the other is using conversions, they two weight arrays should be different
       assert_equal :conversions, Conductor.attribute_for_weighting
       assert_not_equal weights_cv, weights_c
     end
-  end  
+  end
 
 
   private

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 7
-  - 0
-  version: 0.7.0
+  - 1
+  version: 0.7.1
 platform: ruby
 authors: 
 - Noctivity