bandit 0.0.3 → 0.0.4

data/README.rdoc

@@ -1,6 +1,6 @@
 = bandit
 
-Bandit is a multi-armed bandit optmization framework for Rails.
+Bandit is a multi-armed bandit optimization framework for Rails.  It provides an alternative to A/B testing in Rails.  For background and a comparison with A/B testing, see the whybandit.rdoc document.
 
 = Installation
 First, add the following to your Gemfile in your Rails 3 app:
@@ -42,7 +42,7 @@ You can force a particular alternative by adding a query parameter named "bandit
 will then force the alternative to be "40".
 
 == Controller
-To track a converstion in your controller:
+To track a conversion in your controller:
 
    bandit_convert! :click_test
 
@@ -65,7 +65,11 @@ To run tests:
 
 To produce fake data for the past week, first create an experiment definition.  Then, run the following rake task:
 
-    rake bandit:populate_data[experiment_name]
+    rake bandit:populate_data[<experiment_name>]
 
-= Reference
-http://untyped.com/untyping/2011/02/11/stop-ab-testing-and-make-out-like-a-bandit
+For instance, to generate a week's worth of fake data for the click_test above:
+
+    rake bandit:populate_data[click_test]
+
+= Fault Tolerance
+If the storage mechanism fails, then Bandit will automatically switch to in memory storage.  It will then check every 5 minutes after that to see if the original storage mechanism is back up.  If you have distributed front ends then each front end will continue to optimize (based on the in memory storage), but this optimization will be inefficient compared to shared storage among all front ends.

data/Rakefile

@@ -8,6 +8,7 @@ Rake::RDocTask.new("doc") { |rdoc|
   rdoc.rdoc_dir = 'docs'
   rdoc.rdoc_files.include('README.rdoc')
   rdoc.rdoc_files.include('players.rdoc')
+  rdoc.rdoc_files.include('whybandit.rdoc')
   rdoc.rdoc_files.include('lib/**/*.rb')
 }
 

data/bandit.gemspec

@@ -17,5 +17,6 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
   s.add_dependency("rails", ">= 3.0.5")
-  s.add_dependency("rdoc")
+  s.add_dependency("redis", "= 2.2.2")
+  s.add_development_dependency('rdoc')
 end

data/lib/bandit/experiment.rb

@@ -20,8 +20,8 @@ module Bandit
       @@instances
     end
 
-    def choose(default = nil)
-      if not default.nil? and alternatives.include? default
+    def choose(default=nil)
+      if default && alternatives.include?(default)
         alt = default
       else
         alt = Bandit.player.choose_alternative(self)

data/lib/bandit/extensions/array.rb

@@ -0,0 +1,3 @@
+class Array
+  alias_method :sample, :choice unless method_defined?(:sample)
+end

data/lib/bandit/memoizable.rb

@@ -11,5 +11,22 @@ module Bandit
       end
       @memoized[key]
     end
+  
+    module ClassMethods
+      def memoize_method(method, time=60)
+        original_method = "unmemoized_#{method}_#{Time.now.to_i}"
+        alias_method original_method, method
+        module_eval(<<-EVAL, __FILE__, __LINE__)
+        def #{method}(*args, &block)
+          memoize(:#{original_method}, #{time}) { send(:#{original_method}, *args, &block) }
+        end
+        EVAL
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
   end
 end

data/lib/bandit/players/epsilon_greedy.rb

@@ -9,7 +9,7 @@ module Bandit
       if rand <= (1-epsilon)
         best_alternative(experiment)
       else
-        experiment.alternatives.choice
+        experiment.alternatives.sample
       end
     end
 

data/lib/bandit/players/round_robin.rb

@@ -1,7 +1,7 @@
 module Bandit
   class RoundRobinPlayer < BasePlayer
     def choose_alternative(experiment)
-      experiment.alternatives.choice
+      experiment.alternatives.sample
     end
   end
 end

data/lib/bandit/storage/base.rb

@@ -120,5 +120,15 @@ module Bandit
     def make_key(parts)
       parts.join(":")
     end
+
+    def with_failure_grace(fail_default=0)
+      begin
+        yield
+      rescue
+        Bandit.storage_failed!
+        Rails.logger.error "Storage method #{self.class} failed.  Falling back to memory storage."
+        fail_default
+      end
+    end
   end
 end

data/lib/bandit/storage/memcache.rb

@@ -9,26 +9,36 @@ module Bandit
     # increment key by count
     def incr(key, count=1)
       # memcache incr seems to be broken in memcache-client gem
-      set(key, get(key, 0) + count)
+      with_failure_grace(count) {
+        set(key, get(key, 0) + count)
+      }
     end
 
     # initialize key if not set
-    def init(key, value)      
-      @memcache.add(key, value)
+    def init(key, value)    
+      with_failure_grace(value) {
+        @memcache.add(key, value)
+      }
     end
 
     # get key if exists, otherwise 0
     def get(key, default=0)
-      @memcache.get(key) || default
+      with_failure_grace(default) {
+        @memcache.get(key) || default
+      }
     end
 
     # set key with value, regardless of whether it is set or not
     def set(key, value)
-      @memcache.set(key, value)
+      with_failure_grace(value) {
+        @memcache.set(key, value)
+      }
     end
 
     def clear!
-      @memcache.flush_all
+      with_failure_grace(nil) {
+        @memcache.flush_all
+      }
     end
   end
 end

data/lib/bandit/storage/redis.rb

@@ -10,28 +10,38 @@ module Bandit
 
     # increment key by count
     def incr(key, count=1)
-      @redis.incrby(key, count)
+      with_failure_grace(count) {
+        @redis.incrby(key, count)
+      }
     end
 
     # initialize key if not set
     def init(key, value)
-      @redis.set(key, value) if get(key, nil).nil?
+      with_failure_grace(value) {
+        @redis.set(key, value) if get(key, nil).nil?
+      }
     end
 
     # get key if exists, otherwise 0
     def get(key, default=0)
-      val = @redis.get(key)
-      return default if val.nil?
-      val.numeric? ? val.to_i : val
+      with_failure_grace(default) {
+        val = @redis.get(key)
+        return default if val.nil?
+        val.numeric? ? val.to_i : val
+      }
     end
 
     # set key with value, regardless of whether it is set or not
     def set(key, value)
-      @redis.set(key, value)
+      with_failure_grace(value) {
+        @redis.set(key, value)
+      }
     end
 
     def clear!
-      @redis.flushdb
+      with_failure_grace(nil) {
+        @redis.flushdb
+      }
     end
   end
 end

data/lib/bandit/version.rb

@@ -1,3 +1,3 @@
 module Bandit
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/lib/bandit.rb

@@ -15,11 +15,14 @@ require "bandit/storage/memcache"
 require "bandit/storage/redis"
 
 require "bandit/extensions/controller_concerns"
+require "bandit/extensions/array"
 require "bandit/extensions/view_concerns"
 require "bandit/extensions/time"
 require "bandit/extensions/string"
 
 module Bandit
+  @@storage_failure_at = nil
+
   def self.config
     @config ||= Config.new
   end
@@ -32,13 +35,23 @@ module Bandit
   end  
 
   def self.storage
-    @storage ||= BaseStorage.get_storage(Bandit.config.storage.intern, Bandit.config.storage_config)
+    # try using configured storage at least once every 5 minutes until resolved
+    if @@storage_failure_at.nil? or (Time.now.to_i - @@storage_failure_at) > 300
+      @storage ||= BaseStorage.get_storage(Bandit.config.storage.intern, Bandit.config.storage_config)
+    else
+      Rails.logger.warn "storage failure detected #{Time.now.to_i - @@storage_failure_at} seconds ago - using memory storage for 5 minutes"
+      BaseStorage.get_storage(:memory, Bandit.config.storage_config)
+    end
   end
 
   def self.player
     @player ||= BasePlayer.get_player(Bandit.config.player.intern, Bandit.config.player_config)
   end
 
+  def self.storage_failed!
+    @@storage_failure_at = Time.now.to_i
+  end
+
   def self.get_experiment(name)
     exp = Experiment.instances.select { |e| e.name == name } 
     exp.length > 0 ? exp.first : nil

data/lib/generators/bandit/USAGE

@@ -1,3 +1,3 @@
-To copy bandit config and initilizer:
+To copy bandit config and initializer:
 
     rails generate bandit:install

data/players.rdoc

@@ -1,5 +1,5 @@
 = Bandit Players
-There are a number of different possible players that each seek to explore/exploit using different methods.
+There are a number of different possible players that each seek to explore/exploit using different methods.  Each can be configured in the *bandit.yml* file in the config directory under your *Rails.root*.
 
 == Epsilon Greedy
 The epsilon greedy player selects the best alternative with a probability of 1 - epsilon, and selects uniformly among the other alternatives with a probability of epsilon.  You can set the value of epsilon in the config file like this:
@@ -15,7 +15,6 @@ The epsilon greedy player selects the best alternative with a probability of 1 -
 == Round Robin
 This is included for testing purposes only.  It will not optimize.  There are no config options.
 
-
     production:
       ...
       player: round_robin

data/test/redis_storage_test.rb

@@ -1,7 +1,7 @@
 require File.join File.dirname(__FILE__), 'helper'
 require File.join File.dirname(__FILE__), 'storage_test_base'
 
-class MemCacheStorageTest < Test::Unit::TestCase
+class RedisStorageTest < Test::Unit::TestCase
   include StorageTestBase
   include SetupHelper
 

data/whybandit.rdoc

@@ -0,0 +1,31 @@
+= Bandit vs A/B Testing
+In a typical A/B test, two alternatives are compared to see which produces the most "conversions" (that is, desired results).  For instance, if you have a website with a big "Sign Up" button that you want visitors to click, you may wish to choose different background colors.  Under typical A/B testing guildlines, you would pick a number (say, *N*) of users for a test and show half of them one color and half of them another color.  After users are shown the button, you record the number of clicks that result from viewing each color.  Once *N* users view one of the two alternatives, a statistical test (generally categorical, like a Chi-Square Test or a G-Test) is run to determine whether or not the number of clicks (aka, "conversions") for one color were higher than the number of clicks for the other color.  This test determines whether the difference you observed was likely due simply to chance or whether the difference you saw was more likely due to an actual difference in the rate of conversion.
+
+This method of testing is popular, but is fraught with issues (practical and statistical).  Bandit provides an implementation of an alternative method of testing that solves many of these issues.
+
+== Issues with A/B Testing
+There are a number of issues with A/B testing (some of which have been described in more detail here[http://untyped.com/untyping/2011/02/11/stop-ab-testing-and-make-out-like-a-bandit]):
+
+1. You can't try anything too crazy without having to worry about half of your users not converting.  For instance, you may want to try a horrendous color for your "Buy Now" button but are too afraid about potentially harming sales if your users hate it.  In this case, the risk of a big change may outweigh the possible benefit if your users like it.
+1. A/B testing provides a way of only testing two alternatives at once.  Pick two, wait, pick two more, wait - this is not the easiest workflow if you want to test 50 options.
+1. With A/B Testing, you need to have a fixed sample size to make the test valid (otherwise, you run the risk of repeated significance testing errors, as described in more detail here[http://www.evanmiller.org/how-not-to-run-an-ab-test.html]).
+1. Due to the fixed sample size requirement, you may have to wait a while before you get any results from your test (especially if the expected improvement is marginal, in which case your sample size would need to be larger).  This problem can be compounded if you don't get much traffic.
+1. Designers and developers don't want to (and shouldn't have to) understand statistical concepts like power[http://en.wikipedia.org/wiki/Statistical_power], p-values[http://en.wikipedia.org/wiki/P-value], or confidence[http://en.wikipedia.org/wiki/Confidence_intervals] when creating and evaluating tests.
+1. There are no guidelines for what you should do when A performs just as well as B.
+
+== The Bandit Method
+The ultimate goal of A/B testing is to increase conversions.  The problem can be described terms that differ greatly from the multitude of questions A/B testing brings (i.e., "Is A better than B?" followed by "Is B better than C?" followed by "Is C better than D?" _ad_ _infinitum_).  Instead, imagine you have a multitude of possible alternatives, and you want to make a decent choice between alternatives you know perform well and alternatives you haven't tried very often each time a user requests a page.  With each page load, pick the best alternative most of the time and an alternative that hasn't been displayed much some of the time.  After each display, monitor the conversions and update what you consider the "better" alternatives to be.  This is the basic method of a solution to what is called the multi-armed bandit problem.
+
+With a bandit solution, there is no concept of a "test".  At no point does the system announce a winner and a loser.  Alternatives can be added or removed at any time.  The better performing alternatives will be displayed more often, and the worst alternatives will rarely be displayed.  At any point, if one of the poorly performing alternatives begins to perform better it will be shown more often.  This provides solutions to all of the problems listed above:
+
+1. Go ahead and try something crazy.  If it performs poorly, it won't be shown very often.
+1. Pick as many alternatives as you'd like and add them.
+1. There's no "test", and no minimal sample size needed before optimization can start.
+1. Information about conversions is utilized as users convert or do not convert.  There is no pause before results can be immediately used in selecting the next alternative to display to a visitor.
+1. Designers and developers can add alternatives or remove them at any time.  The system will adjust immediately.  If an alternative seems to be consistently performing poorly, it can be removed at any time.  Alternatively, it can just be left forever.  The best option will always be displayed the most often.  There are no complicated decisions that have to be made up front or requirements that designers or developers know anything about proper statistical hypothesis testing.
+1. If one alternative performs the same as another, they will both be displayed with the same regularity.  There would be no need to choose one over the other or remove either of them.
+
+== Reference
+* http://untyped.com/untyping/2011/02/11/stop-ab-testing-and-make-out-like-a-bandit
+* http://en.wikipedia.org/wiki/Multi-armed_bandit
+* http://www.evanmiller.org/how-not-to-run-an-ab-test.html

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: bandit
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 23
   prerelease: false
   segments: 
   - 0
   - 0
-  - 3
-  version: 0.0.3
+  - 4
+  version: 0.0.4
 platform: ruby
 authors: 
 - Brian Muller
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-13 00:00:00 -04:00
+date: 2011-11-06 01:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -35,9 +35,25 @@ dependencies:
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: rdoc
+  name: redis
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 2
+        - 2
+        - 2
+        version: 2.2.2
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -46,8 +62,8 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :runtime
-  version_requirements: *id002
+  type: :development
+  version_requirements: *id003
 description: Bandit provides a way to do multi-armed bandit optimization of alternatives in a rails website
 email: 
 - brian.muller@livingsocial.com
@@ -69,6 +85,7 @@ files:
 - lib/bandit/date_hour.rb
 - lib/bandit/exceptions.rb
 - lib/bandit/experiment.rb
+- lib/bandit/extensions/array.rb
 - lib/bandit/extensions/controller_concerns.rb
 - lib/bandit/extensions/string.rb
 - lib/bandit/extensions/time.rb
@@ -111,6 +128,7 @@ files:
 - test/memory_storage_test.rb
 - test/redis_storage_test.rb
 - test/storage_test_base.rb
+- whybandit.rdoc
 has_rdoc: true
 homepage: https://github.com/bmuller/bandit
 licenses: []