abingo 1.1.0

data/lib/abingo/alternative.rb

@@ -0,0 +1,25 @@
+require "abingo/conversion_rate"
+class Abingo::Alternative < ActiveRecord::Base
+  include Abingo::ConversionRate
+
+  belongs_to :experiment, :class_name => "Abingo::Experiment"
+  attr_accessible :content, :weight, :lookup
+  serialize :content
+
+  def self.calculate_lookup(test_name, alternative_name)
+    Digest::MD5.hexdigest(Abingo.salt + test_name + alternative_name.to_s)
+  end
+
+  def self.score_conversion(test_name)
+    viewed_alternative = Abingo.find_alternative_for_user(test_name,
+      Abingo::Experiment.alternatives_for_test(test_name))
+    self.update_all("conversions = conversions + 1", :lookup => self.calculate_lookup(test_name, viewed_alternative))
+  end
+
+  def self.score_participation(test_name)
+    viewed_alternative = Abingo.find_alternative_for_user(test_name,
+      Abingo::Experiment.alternatives_for_test(test_name))
+    self.update_all("participants = participants + 1", :lookup => self.calculate_lookup(test_name, viewed_alternative))
+  end
+
+end

data/lib/abingo/controller/dashboard.rb

@@ -0,0 +1,29 @@
+class Abingo
+  module Controller
+    module Dashboard
+
+      if Rails::VERSION::MAJOR <= 2
+        ActionController::Base.view_paths.unshift File.join(File.dirname(__FILE__), "../views")
+      else
+        ActionController::Base.prepend_view_path File.join(File.dirname(__FILE__), "../views")
+      end
+
+      def index
+        @experiments = Abingo::Experiment.all
+        render :template => 'dashboard/index'
+      end
+
+      def end_experiment
+        @alternative = Abingo::Alternative.find(params[:id])
+        @experiment = Abingo::Experiment.find(@alternative.experiment_id)
+        if (@experiment.status != "Completed")
+          @experiment.end_experiment!(@alternative.content)
+          flash[:notice] = "Experiment marked as ended.  All users will now see the chosen alternative."
+        else
+          flash[:notice] = "This experiment is already ended."
+        end
+        redirect_to :action => "index"
+      end
+    end
+  end
+end

data/lib/abingo/conversion_rate.rb

@@ -0,0 +1,9 @@
+module Abingo::ConversionRate
+  def conversion_rate
+    1.0 * conversions / participants
+  end
+
+  def pretty_conversion_rate
+    sprintf("%4.2f%%", conversion_rate * 100)
+  end
+end

data/lib/abingo/experiment.rb

@@ -0,0 +1,107 @@
+require "abingo/statistics"
+require "abingo/conversion_rate"
+class Abingo::Experiment < ActiveRecord::Base
+  include Abingo::Statistics
+  include Abingo::ConversionRate
+
+  has_many :alternatives, :dependent => :destroy, :class_name => "Abingo::Alternative"
+  validates_uniqueness_of :test_name
+  attr_accessible :test_name
+  before_destroy :cleanup_cache
+
+  def cache_keys
+  ["Abingo::Experiment::exists(#{test_name})".gsub(" ", "_"),
+    "Abingo::Experiment::#{test_name}::alternatives".gsub(" ","_"),
+    "Abingo::Experiment::short_circuit(#{test_name})".gsub(" ", "_")
+  ]
+  end
+
+  def cleanup_cache
+    cache_keys.each do |key|
+      Abingo.cache.delete key
+    end
+    true
+  end
+
+  def participants
+    alternatives.sum("participants")
+  end
+
+  def conversions
+    alternatives.sum("conversions")
+  end
+
+  def best_alternative
+    alternatives.max do |a,b|
+      a.conversion_rate <=> b.conversion_rate
+    end
+  end
+
+  def self.exists?(test_name)
+    cache_key = "Abingo::Experiment::exists(#{test_name})".gsub(" ", "_")
+    ret = Abingo.cache.fetch(cache_key) do
+      count = Abingo::Experiment.count(:conditions => {:test_name => test_name})
+      count > 0 ? count : nil
+    end
+    (!ret.nil?)
+  end
+
+  def self.alternatives_for_test(test_name)
+    cache_key = "Abingo::#{test_name}::alternatives".gsub(" ","_")
+    Abingo.cache.fetch(cache_key) do
+      experiment = Abingo::Experiment.find_by_test_name(test_name)
+      alternatives_array = Abingo.cache.fetch(cache_key) do
+        tmp_array = experiment.alternatives.map do |alt|
+          [alt.content, alt.weight]
+        end
+        tmp_hash = tmp_array.inject({}) {|hash, couplet| hash[couplet[0]] = couplet[1]; hash}
+        Abingo.parse_alternatives(tmp_hash)
+      end
+      alternatives_array
+    end
+  end
+
+  def self.start_experiment!(test_name, alternatives_array, conversion_name = nil)
+    conversion_name ||= test_name
+    conversion_name.gsub!(" ", "_")
+    cloned_alternatives_array = alternatives_array.clone
+    ActiveRecord::Base.transaction do
+      experiment = Abingo::Experiment.find_or_create_by_test_name(test_name)
+      experiment.alternatives.destroy_all  #Blows away alternatives for pre-existing experiments.
+      while (cloned_alternatives_array.size > 0)
+        alt = cloned_alternatives_array[0]
+        weight = cloned_alternatives_array.size - (cloned_alternatives_array - [alt]).size
+        experiment.alternatives.build(:content => alt, :weight => weight,
+          :lookup => Abingo::Alternative.calculate_lookup(test_name, alt))
+        cloned_alternatives_array -= [alt]
+      end
+      experiment.status = "Live"
+      if Rails::VERSION::MAJOR == 2
+        experiment.save(false)  #Calling the validation here causes problems b/c of transaction.
+      else
+        experiment.save(:validate => false)
+      end
+      Abingo.cache.write("Abingo::Experiment::exists(#{test_name})".gsub(" ", "_"), 1)
+
+      #This might have issues in very, very high concurrency environments...
+
+      tests_listening_to_conversion = Abingo.cache.read("Abingo::tests_listening_to_conversion#{conversion_name}") || []
+      tests_listening_to_conversion += [test_name] unless tests_listening_to_conversion.include? test_name
+      Abingo.cache.write("Abingo::tests_listening_to_conversion#{conversion_name}", tests_listening_to_conversion)
+      experiment
+    end
+  end
+
+  def end_experiment!(final_alternative, conversion_name = nil)
+    conversion_name ||= test_name
+    ActiveRecord::Base.transaction do
+      alternatives.each do |alternative|
+        alternative.lookup = "Experiment completed.  #{alternative.id}"
+        alternative.save!
+      end
+      update_attribute(:status, "Finished")
+      Abingo.cache.write("Abingo::Experiment::short_circuit(#{test_name})".gsub(" ", "_"), final_alternative)
+    end
+  end
+
+end

data/lib/abingo/rails/controller/dashboard.rb

@@ -0,0 +1,13 @@
+class Abingo
+  module Rails
+    module Controller
+      module Dashboard
+
+        def index
+          @experiments = Abingo::Experiment.all
+        end
+
+      end
+    end
+  end
+end

data/lib/abingo/statistics.rb

@@ -0,0 +1,90 @@
+#Designed to be included into Abingo::Experiment, but you can feel free to adapt this
+#to anything you want.
+
+module Abingo::Statistics
+
+  HANDY_Z_SCORE_CHEATSHEET = [[0.10, 1.29], [0.05, 1.65], [0.01, 2.33], [0.001, 3.08]]
+  
+  PERCENTAGES = {0.10 => '90%', 0.05 => '95%', 0.01 => '99%', 0.001 => '99.9%'}
+  
+  DESCRIPTION_IN_WORDS = {0.10 => 'fairly confident', 0.05 => 'confident',
+                         0.01 => 'very confident', 0.001 => 'extremely confident'}
+  def zscore
+    if alternatives.size != 2
+      raise "Sorry, can't currently automatically calculate statistics for A/B tests with > 2 alternatives."
+    end
+
+    if (alternatives[0].participants == 0) || (alternatives[1].participants == 0)
+      raise "Can't calculate the z score if either of the alternatives lacks participants."
+    end
+
+    cr1 = alternatives[0].conversion_rate
+    cr2 = alternatives[1].conversion_rate
+
+    n1 = alternatives[0].participants
+    n2 = alternatives[1].participants
+
+    numerator = cr1 - cr2
+    frac1 = cr1 * (1 - cr1) / n1
+    frac2 = cr2 * (1 - cr2) / n2
+
+    numerator / ((frac1 + frac2) ** 0.5)
+  end
+
+  def p_value
+    index = 0
+    z = zscore
+    z = z.abs
+    found_p = nil
+    while index < HANDY_Z_SCORE_CHEATSHEET.size do
+      if (z > HANDY_Z_SCORE_CHEATSHEET[index][1])
+        found_p = HANDY_Z_SCORE_CHEATSHEET[index][0]
+      end
+      index += 1
+    end
+    found_p
+  end
+
+  def is_statistically_significant?(p = 0.05)
+    p_value <= p
+  end
+  
+  def pretty_conversion_rate
+    sprintf("%4.2f%%", conversion_rate * 100)
+  end
+
+  def describe_result_in_words
+    begin
+      z = zscore
+    rescue
+      return "Could not execute the significance test because one or more of the alternatives has not been seen yet."
+    end
+    p = p_value
+
+    words = ""
+    if (alternatives[0].participants < 10) || (alternatives[1].participants < 10)
+      words += "Take these results with a grain of salt since your samples are so small: "
+    end
+
+    alts = alternatives - [best_alternative]
+    worst_alternative = alts.first
+
+    words += "The best alternative you have is: [#{best_alternative.content}], which had "
+    words += "#{best_alternative.conversions} conversions from #{best_alternative.participants} participants "
+    words += "(#{best_alternative.pretty_conversion_rate}).  The other alternative was [#{worst_alternative.content}], "
+    words += "which had #{worst_alternative.conversions} conversions from #{worst_alternative.participants} participants "
+    words += "(#{worst_alternative.pretty_conversion_rate}).  "
+
+    if (p.nil?)
+      words += "However, this difference is not statistically significant."
+    else
+      words += "This difference is #{PERCENTAGES[p]} likely to be statistically significant, which means you can be "
+      words += "#{DESCRIPTION_IN_WORDS[p]} that it is the result of your alternatives actually mattering, rather than "
+      words += "being due to random chance.  However, this statistical test can't measure how likely the currently "
+      words += "observed magnitude of the difference is to be accurate or not.  It only says \"better\", not \"better "
+      words += "by so much\"."
+    end
+    words
+  end
+
+end

data/lib/abingo/version.rb

@@ -0,0 +1,3 @@
+class Abingo
+  VERSION = "1.1.0"
+end

data/lib/abingo/views/dashboard/_experiment.erb

@@ -0,0 +1,43 @@
+<h3><%= experiment.test_name.titleize %> <%= %Q|<i>(Test completed)</i>| if experiment.status != "Live" %> </h3>
+<% short_circuit = Abingo.cache.read("Abingo::Experiment::short_circuit(#{experiment.test_name})".gsub(" ", "")) %>
+<table class="experiment" style="border: 1px black;">
+  <tr class="header_row">
+    <th>Name</th>
+    <th>Participants</th>
+    <th>Conversions</th>
+    <th>Notes</th>
+  </tr>
+  <tr class="experiment_row">
+    <td>Experiment Total: </td>
+    <td><%= experiment.participants %> </td>
+    <td><%= experiment.conversions %> (<%= experiment.pretty_conversion_rate %>)</td>
+    <td></td>
+  </tr>
+  <% experiment.alternatives.each do |alternative| %>
+  <tr class="alternative_row">
+    <td>
+        <%= h alternative.content %>
+    </td>
+    <td><%= alternative.participants %></td>
+    <td><%= alternative.conversions %> (<%= alternative.pretty_conversion_rate %>)</td>
+    <td>
+      <% unless experiment.status != "Live" %>
+      <%= link_to("End experiment, picking this.", url_for(:id => alternative.id,
+      :action => "end_experiment"),
+      :method => :post,
+      :confirm => "Are you sure you want to terminate this experiment?  This is not reversible."
+      ) %>
+      <% else %>
+        <% if alternative.content == short_circuit %>
+          <b>(All users seeing this.)</b>
+        <% end %>
+      <% end %>
+    </td>
+  </tr>
+  <% end %>
+  <tr>
+    <td colspan="4">
+      <b>Significance test results: </b><%= experiment.describe_result_in_words %>
+    </td>
+  </tr>
+</table>

data/lib/abingo/views/dashboard/index.erb

@@ -0,0 +1,20 @@
+<div id="abingo_dashboard">
+<p><h1>Welcome to your A/Bingo dashboard!</h1>
+
+See <a href="http://www.bingocardcreator.com/abingo">the official site</a> for documentation.
+I encourage you to customize this page to fit your needs.  See /vendor/plugins/abingo/views for
+the view templates.  Hack them to pieces -- please!
+</p>
+
+<p>
+  <% if flash[:notice] %>
+  <span style="color: green;"><%= flash[:notice] %> </span>
+  <% end %>
+  <h2>All Experiments</h2>
+  
+<% @experiments.each do |experiment| %>
+  <%= render :partial => "dashboard/experiment", :locals => {:experiment => experiment} %>
+  <br/>
+<% end %>
+</p>
+</div>

data/lib/abingo_sugar.rb

@@ -0,0 +1,49 @@
+#This module exists entirely to save finger strain for programmers.
+#It is designed to be included in your ApplicationController.
+#
+#See abingo.rb for descriptions of what these do.
+
+module AbingoSugar
+
+  def ab_test(test_name, alternatives = nil, options = {})
+    if (Abingo.options[:enable_specification] && !params[test_name].nil?)
+      choice = params[test_name]
+    elsif (Abingo.options[:enable_override_in_session] && !session[test_name].nil?)
+      choice = session[test_name]
+    elsif (alternatives.nil?)
+      choice = Abingo.flip(test_name)
+    else
+      choice = Abingo.test(test_name, alternatives, options)
+    end
+
+    if block_given?
+      yield(choice)
+    else
+      choice
+    end
+  end
+
+  def bingo!(test_name, options = {})
+    Abingo.bingo!(test_name, options)
+  end
+
+  #Mark the user as a human.
+  def abingo_mark_human
+    textual_result = "1"
+    begin
+      a = params[:a].to_i
+      b = params[:b].to_i
+      c = params[:c].to_i
+      if (request.method == :post && (a + b == c))
+        Abingo.human!
+      else
+        textual_result = "0"
+      end
+    rescue #If a bot doesn't pass a, b, or c, to_i will fail.  This scarfs up the exception, to save it from polluting our logs.
+      textual_result = "0"
+    end
+    render :text => textual_result, :layout => false #Not actually used by browser
+
+  end
+
+end

data/lib/abingo_view_helper.rb

@@ -0,0 +1,45 @@
+#Gives you easy syntax to use ABingo in your views.
+
+module AbingoViewHelper
+
+  def ab_test(test_name, alternatives = nil, options = {}, &block)
+
+    if (Abingo.options[:enable_specification] && !params[test_name].nil?)
+      choice = params[test_name]
+    elsif (Abingo.options[:enable_override_in_session] && !session[test_name].nil?)
+      choice = session[test_name]
+    elsif (alternatives.nil?)
+      choice = Abingo.flip(test_name)
+    else
+      choice = Abingo.test(test_name, alternatives, options)
+    end
+
+    if block
+      content_tag = capture(choice, &block)
+      unless Rails::VERSION::MAJOR >= 3
+        block_called_from_erb?(block) ? concat(content_tag) : content_tag
+      else
+        content_tag
+      end
+    else
+      choice
+    end
+  end
+
+  def bingo!(test_name, options = {})
+    Abingo.bingo!(test_name, options)
+  end
+
+  #This causes an AJAX post against the URL.  That URL should call Abingo.human!
+  #This guarantees that anyone calling Abingo.human! is capable of at least minimal Javascript execution, and thus is (probably) not a robot.
+  def include_humanizing_javascript(url = "/abingo_mark_human", style = :prototype)
+    script = nil
+    if (style == :prototype)
+      script = "var a=Math.floor(Math.random()*11); var b=Math.floor(Math.random()*11);var x=new Ajax.Request('#{url}', {parameters:{a: a, b: b, c: a+b}})"
+    elsif (style == :jquery)
+      script = "var a=Math.floor(Math.random()*11); var b=Math.floor(Math.random()*11);var x=jQuery.post('#{url}', {a: a, b: b, c: a+b})"
+    end
+    script.nil? ? "" : %Q|<script type="text/javascript">#{script}</script>|
+  end
+  
+end