abingo_port 0.1.0

data/.gitignore

@@ -0,0 +1 @@
+.svn

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Patrick McKenzie
+
+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/README

@@ -0,0 +1,160 @@
+A/Bingo Version 1.0.0 - Rails 3 Version
+=======================================
+
+**This is a port of ABingo to work as a rails 3 plugin. It is not extensivly tested but appears to work. Future work will make it easier to use.**
+
+**Known Issues with rails 3**
+
+  * **Named Conversions do not work (eg :conversion => "signup")**
+
+
+
+Rails A/B testing.  One minute to install.  One line to set up a new A/B test.
+One line to track conversion.
+
+For usage notes, see: http://www.bingocardcreator.com/abingo
+
+Installation instructions are below usage examples.
+
+Key default features:
+
+  * Conversions only tracked once per individual.
+  * Conversions only tracked if individual saw test.
+  * Same individual ALWAYS sees same alternative for same test.
+  * Syntax sugar.  Specify alternatives as a range, array, hash of alternative to weighting, or just let it default to true or false.
+  * A simple z-test of statistical significance, with output so clear anyone in your organization
+       can understand it.
+
+Example: View
+-------------
+
+    <% ab_test("login_button", ["/images/button1.jpg", "/images/button2.jpg"]) do |button_file| %>
+      <%= img_tag(button_file, :alt => "Login!") %>
+    <% end %>
+
+Example: Controller
+-------------------
+
+    def register_new_user
+      #See what level of free points maximizes users' decision to buy replacement points.
+      @starter_points = ab_test("new_user_free_points", [100, 200, 300])
+    end
+
+Example: Controller
+-------------------
+
+    def registration
+      if (ab_test("send_welcome_email"), :conversion => "purchase")
+        #send the email, track to see if it later increases conversion to full version
+      end
+    end
+
+Example: Conversion tracking (in a controller!)
+------------------------------------------------
+
+    def buy_new_points
+      #some business logic
+      bingo!("buy_new_points")  #Either a conversion named with :conversion or a test name.
+    end
+
+Example: Conversion tracking (in a view)
+-----------------------------------------
+
+    Thanks for signing up, dude! <% bingo!("signup_page_redesign") >
+
+Example: Statistical Significance Testing
+------------------------------------------
+
+    Abingo::Experiment.last.describe_result_in_words
+    => "The best alternative you have is: [0], which had 130 conversions from 5000 participants (2.60%).
+        The other alternative was [1], which had 1800 conversions from 100000 participants (1.80%).
+        This difference is 99.9% likely to be statistically significant, which means you can be extremely
+        confident that it is the result of your alternatives actually mattering, rather than being due to
+        random chance.  However, this doesn't say anything about how much the first alternative is really
+        likely to be better by."
+
+Installation
+==================
+
+Configure the Gem
+------------------
+
+    gem 'abingo', :git => "git://github.com/wildfalcon/abingo.git", :branch => "rails3"
+
+    bundle install 
+
+Generate the database tables 
+-----------------------------
+Creates tables "experiments" and "alternatives". If you use these names already you will need to do some hacking)
+
+
+    rails g abingo_migration
+    rake db:migrate
+
+Configure a Cache
+-----------------
+A/Bingo makes HEAVY use of the cache to reduce load on thedatabase and share potentially long-lived "temporary" data, such as what alternative a given visitor should be shown for a particular test.  
+
+A/Bingo defaults to using the same cache store as Rails.  These instructions
+are on how to use the memcache-addon in heroku.
+
+    heroku addons:add memcache:5mb
+
+    #Gemile
+    group :production do
+      gem "memcache-client"
+      gem 'memcached-northscale', :require => 'memcached'
+    end
+
+
+    #config/environments/production.rb
+    # Use a different cache store in production
+    # config.cache_store = :mem_cache_store
+    config.cache_store = :mem_cache_store, Memcached::Rails.new
+
+
+Tell A/Bingo a user's identity
+-------------------------------
+
+So abingo knows who a users is if they come back to a test.  (The same identity will always see the same alternative for the same test.)  How you do this is up to you -- I suggest integrating with your login/account infrastructure.  The simplest thing that can possibly work
+
+    #Somewhere in application.rb
+    before_filter :set_abingo_identity
+
+    def set_abingo_identity  
+      #treat all bots as one user to prevent skewing results
+      if request.user_agent =~ /\b(Baidu|Gigabot|Googlebot|libwww-perl|lwp-trivial|msnbot|SiteUptime|Slurp|WordPress|ZIBB|ZyBorg)\b/i  
+         Abingo.identity = "robot"  
+       elsif current_user  
+         Abingo.identity = current_user.id  
+       else  
+         session[:abingo_identity] ||= rand(10 ** 10)  
+         Abingo.identity = session[:abingo_identity]  
+       end  
+    end
+
+Create the Dashboard
+--------------------
+
+You need to create a controller which includes the methods from the Abingo module, as well as generate the views. You can customise the view if you wish.
+Don't forget to authenticate access to the controller
+
+    rails g controller admin/abingo_dashboard
+    
+    #app/controllers/admin/abingo_dashboard_controller.rb
+    class Admin::AbingoDashboardController < ApplicationController
+      include Abingo::Controller::Dashboard
+    end
+    
+    #routes.rb
+    namespace :admin do
+      get "ab_dashboard"   => "abingo_dashboard#index"
+      post "ab_end_experiment/:id"   => "abingo_dashboard#end_experiment"
+    end
+    
+    rails g abingo_views
+    
+Run your first test
+====================
+
+Copyright (c) 2009-2010 Patrick McKenzie, released under the MIT license

data/Rakefile

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "abingo_port"
+    gem.summary = %Q{A/B Testing for Rails}
+    gem.description = %Q{Incorperate AB Testing into your rails apps}
+    gem.email = "laurie@wildfalcon.com"
+    gem.homepage = "http://github.com/wildfalcon/abingo"
+    gem.authors = ["Wildfalcon"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "baby_railtie #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/abingo.gemspec

@@ -0,0 +1,72 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{abingo}
+  s.version = "0.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Wildfalcon"]
+  s.date = %q{2010-08-07}
+  s.description = %q{Incorperate AB Testing into your rails apps}
+  s.email = %q{laurie@wildfalcon.com}
+  s.extra_rdoc_files = [
+    "README"
+  ]
+  s.files = [
+    ".gitignore",
+     "MIT-LICENSE",
+     "README",
+     "Rakefile",
+     "VERSION",
+     "abingo.gemspec",
+     "init.rb",
+     "install.rb",
+     "lib/abingo.rb",
+     "lib/abingo/alternative.rb",
+     "lib/abingo/controller/dashboard.rb",
+     "lib/abingo/conversion_rate.rb",
+     "lib/abingo/experiment.rb",
+     "lib/abingo/rails/controller/dashboard.rb",
+     "lib/abingo/railtie.rb",
+     "lib/abingo/statistics.rb",
+     "lib/abingo/views/dashboard/_experiment.erb",
+     "lib/abingo/views/dashboard/index.erb",
+     "lib/abingo_sugar.rb",
+     "lib/abingo_view_helper.rb",
+     "lib/generators/abingo_migration/USAGE",
+     "lib/generators/abingo_migration/abingo_migration_generator.rb",
+     "lib/generators/abingo_migration/templates/create_abingo_tables.rb",
+     "lib/generators/abingo_views/USAGE",
+     "lib/generators/abingo_views/abingo_views_generator.rb",
+     "lib/generators/abingo_views/templates/views/dashboard/_experiment.html.erb",
+     "lib/generators/abingo_views/templates/views/dashboard/index.html.erb",
+     "strip.rb",
+     "tasks/abingo_tasks.rake",
+     "test/abingo_test.rb",
+     "test/test_helper.rb",
+     "uninstall.rb"
+  ]
+  s.homepage = %q{http://github.com/wildfalcon/abingo}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{A/B Testing for Rails}
+  s.test_files = [
+    "test/abingo_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/init.rb

@@ -0,0 +1,5 @@
+require File.dirname(__FILE__) + '/lib/abingo'
+
+ActionController::Base.send :include, AbingoSugar
+
+ActionView::Base.send :include, AbingoViewHelper

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/abingo.rb

@@ -0,0 +1,235 @@
+#This class is outside code's main interface into the ABingo A/B testing framework.
+#Unless you're fiddling with implementation details, it is the only one you need worry about.
+
+#Usage of ABingo, including practical hints, is covered at http://www.bingocardcreator.com/abingo
+require 'abingo/railtie'
+require 'abingo_sugar'
+require 'abingo_view_helper'
+
+class Abingo
+  
+   @@VERSION = "1.0.0"
+   @@MAJOR_VERSION = "1.0"
+   cattr_reader :VERSION
+   cattr_reader :MAJOR_VERSION
+   
+   #Not strictly necessary, but eh, as long as I'm here.
+   cattr_accessor :salt
+   @@salt = "Not really necessary."
+   
+   @@options ||= {}
+   cattr_accessor :options
+   
+   #Defined options:
+   # :enable_specification  => if true, allow params[test_name] to override the calculated value for a test.
+   
+   #ABingo stores whether a particular user has participated in a particular
+   #experiment yet, and if so whether they converted, in the cache.
+   #
+   #It is STRONGLY recommended that you use a MemcacheStore for this.
+   #If you'd like to persist this through a system restart or the like, you can
+   #look into memcachedb, which speaks the memcached protocol.  From the perspective
+   #of Rails it is just another MemcachedStore.
+   #
+   #You can overwrite Abingo's cache instance, if you would like it to not share
+   #your generic Rails cache.
+   cattr_writer :cache
+   
+   def self.cache
+     @@cache || Rails.cache
+   end
+   
+   #This method gives a unique identity to a user.  It can be absolutely anything
+   #you want, as long as it is consistent.
+   #
+   #We use the identity to determine, deterministically, which alternative a user sees.
+   #This means that if you use Abingo.identify_user on someone at login, they will
+   #always see the same alternative for a particular test which is past the login
+   #screen.  For details and usage notes, see the docs.
+   def self.identity=(new_identity)
+     @@identity = new_identity.to_s
+   end
+   
+   def self.identity
+     @@identity ||= rand(10 ** 10).to_i.to_s
+   end
+   
+   #A simple convenience method for doing an A/B test.  Returns true or false.
+   #If you pass it a block, it will bind the choice to the variable given to the block.
+   def self.flip(test_name)
+     if block_given?
+       yield(self.test(test_name, [true, false]))
+     else
+       self.test(test_name, [true, false])
+     end
+   end
+   
+   #This is the meat of A/Bingo.
+   #options accepts
+   #  :multiple_participation (true or false)
+   #  :conversion  name of conversion to listen for  (alias: conversion_name)
+   def self.test(test_name, alternatives, options = {})
+   
+     short_circuit = Abingo.cache.read("Abingo::Experiment::short_circuit(#{test_name})".gsub(" ", "_"))
+     unless short_circuit.nil?
+       return short_circuit  #Test has been stopped, pick canonical alternative.
+     end
+     
+     unless Abingo::Experiment.exists?(test_name)
+       lock_key = test_name.gsub(" ", "_")
+       if Abingo.cache.exist?(lock_key)
+         while Abingo.cache.exist?(lock_key)
+           sleep(0.1)
+         end
+         break
+       end
+       Abingo.cache.write(lock_key, 1, :expires_in => 5.seconds)
+       conversion_name = options[:conversion] || options[:conversion_name]
+       Abingo::Experiment.start_experiment!(test_name, self.parse_alternatives(alternatives), conversion_name)
+       Abingo.cache.delete(lock_key)
+     end
+   
+     choice = self.find_alternative_for_user(test_name, alternatives)
+     participating_tests = Abingo.cache.read("Abingo::participating_tests::#{Abingo.identity}") || []
+     
+     #Set this user to participate in this experiment, and increment participants count.
+     if options[:multiple_participation] || !(participating_tests.include?(test_name))
+       unless participating_tests.include?(test_name)
+         participating_tests = participating_tests + [test_name]
+         Abingo.cache.write("Abingo::participating_tests::#{Abingo.identity}", participating_tests)
+       end
+       Abingo::Alternative.score_participation(test_name)
+     end
+   
+     if block_given?
+       yield(choice)
+     else
+       choice
+     end
+   end
+   
+   
+   #Scores conversions for tests.
+   #test_name_or_array supports three types of input:
+   #
+   #A conversion name: scores a conversion for any test the user is participating in which
+   #  is listening to the specified conversion.
+   #
+   #A test name: scores a conversion for the named test if the user is participating in it.
+   #
+   #An array of either of the above: for each element of the array, process as above.
+   #
+   #nil: score a conversion for every test the u
+   def Abingo.bingo!(name = nil, options = {})
+     if name.kind_of? Array
+       name.map do |single_test|
+         self.bingo!(single_test, options)
+       end
+     else
+       if name.nil?
+         #Score all participating tests
+         participating_tests = Abingo.cache.read("Abingo::participating_tests::#{Abingo.identity}") || []
+         participating_tests.each do |participating_test|
+           self.bingo!(participating_test, options)
+         end
+       else #Could be a test name or conversion name.
+         conversion_name = name.gsub(" ", "_")
+         tests_listening_to_conversion = Abingo.cache.read("Abingo::tests_listening_to_conversion#{conversion_name}")
+         if tests_listening_to_conversion
+           if tests_listening_to_conversion.size > 1
+             tests_listening_to_conversion.map do |individual_test|
+               self.score_conversion!(individual_test.to_s)
+             end
+           elsif tests_listening_to_conversion.size == 1
+             test_name_str = tests_listening_to_conversion.first.to_s
+             self.score_conversion!(test_name_str)
+           end
+         else
+           #No tests listening for this conversion.  Assume it is just a test name.
+           test_name_str = name.to_s
+           self.score_conversion!(test_name_str)
+         end
+       end
+     end
+   end
+   
+   protected
+   
+   #For programmer convenience, we allow you to specify what the alternatives for
+   #an experiment are in a few ways.  Thus, we need to actually be able to handle
+   #all of them.  We fire this parser very infrequently (once per test, typically)
+   #so it can be as complicated as we want.
+   #   Integer => a number 1 through N
+   #   Range   => a number within the range
+   #   Array   => an element of the array.
+   #   Hash    => assumes a hash of something to int.  We pick one of the 
+   #              somethings, weighted accorded to the ints provided.  e.g.
+   #              {:a => 2, :b => 3} produces :a 40% of the time, :b 60%.
+   #
+   #Alternatives are always represented internally as an array.
+   def self.parse_alternatives(alternatives)
+     if alternatives.kind_of? Array
+       return alternatives
+     elsif alternatives.kind_of? Integer
+       return (1..alternatives).to_a
+     elsif alternatives.kind_of? Range
+       return alternatives.to_a
+     elsif alternatives.kind_of? Hash
+       alternatives_array = []
+       alternatives.each do |key, value|
+         if value.kind_of? Integer
+           alternatives_array += [key] * value
+         else
+           raise "You gave a hash with #{key} => #{value} as an element.  The value must be an integral weight."
+         end
+       end
+       return alternatives_array
+     else
+       raise "I don't know how to turn [#{alternatives}] into an array of alternatives."
+     end
+   end
+   
+   def self.retrieve_alternatives(test_name, alternatives)
+     cache_key = "Abingo::Experiment::#{test_name}::alternatives".gsub(" ","_")
+     alternative_array = self.cache.fetch(cache_key) do
+       self.parse_alternatives(alternatives)
+     end
+     alternative_array
+   end
+   
+   def self.find_alternative_for_user(test_name, alternatives)
+     alternatives_array = retrieve_alternatives(test_name, alternatives)
+     alternatives_array[self.modulo_choice(test_name, alternatives_array.size)]
+   end
+   
+   #Quickly determines what alternative to show a given user.  Given a test name
+   #and their identity, we hash them together (which, for MD5, provably introduces
+   #enough entropy that we don't care) otherwise
+   def self.modulo_choice(test_name, choices_count)
+     Digest::MD5.hexdigest(Abingo.salt.to_s + test_name + self.identity.to_s).to_i(16) % choices_count
+   end
+   
+   def self.score_conversion!(test_name)
+     test_name.gsub!(" ", "_")
+     participating_tests = Abingo.cache.read("Abingo::participating_tests::#{Abingo.identity}") || []
+     if options[:assume_participation] || participating_tests.include?(test_name)
+       cache_key = "Abingo::conversions(#{Abingo.identity},#{test_name}"
+       if options[:multiple_conversions] || !Abingo.cache.read(cache_key)
+         Abingo::Alternative.score_conversion(test_name)
+         if Abingo.cache.exist?(cache_key)
+           Abingo.cache.increment(cache_key)
+         else
+           Abingo.cache.write(cache_key, 1)
+         end
+       end
+     end
+   end
+ 
+end
+
+require 'abingo/statistics'
+require 'abingo/conversion_rate'
+require 'abingo/alternative'
+require 'abingo/experiment'
+require 'abingo/controller/dashboard'
+# require 'abingo/experiment'