ab 0.0.1 → 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0a6dc32389b41a3d6dedd61190c68cab39bff8cc
+  data.tar.gz: 48dc84a73213f270443884816a6e0cdb6213a5f7
+SHA512:
+  metadata.gz: ce5b523e9213a127e8b84339f0c9672175dfb82c2e37ecea1c19289b647bba9c22d43e80023dbb82198cd14ccb8506c3e936361557eab497c389090777239f04
+  data.tar.gz: d6b4f577c2ff9aaf7c205c0f66157c37f4bb690c1e885bf1613905b602e29cd753fe7d1a08a45d167d7939a3ce337a9d16c977d8cc32ce92674aa879532e9ecc

data/README.md

@@ -1,12 +1,89 @@
-# OleryAb
+# AB
 
-TODO: Write a gem description
+This gem provides you with a way to do AB testing in a deterministic way
+without the need for Redis or any other service.
+
+** NOTICE ** 
+
+*The gem is in very early development*
+
+Since other gems need all kinds of extra services to work, and we didn't want
+any extra dependencies, we created a gem that will serve your users an A/B/C or
+whatever version based on for example a user-id
+
+You can then use e.g. a tool like Mixpanel to track which user saw what, and
+make your AB testing decisions.
+
+The gem works in a Rails and non rails environment. It's tested on ruby 1.8.7, 1.9.3, 2.1.5, 2.2.2, jruby-1.7.8 and rubinius-2.4.0.
+
+# Examples
+
+## Simple view usage
+In your view (haml):
+
+```haml
+-ab(:options=>["dude","your royal highness"], :chances=>"20/80",:name=>"greeting").for(@current_user.id) do |option|
+  ="Well hello #{option}"
+```
+
+## Defining tests in a controller
+You can also create a tester, for example in your ```app/controllers/application_controller.rb```
+
+```ruby
+class ApplicationController
+  before_filter :ab_tests
+
+  def ab_tests
+    @greeting_test = Ab::Tester.new(:options=>["Yo", "Hello"],  :chances=>"50/50", :name=>"greeter")
+  end
+end
+```
+
+Then in your view (haml style):
+
+```haml
+-@greeting_test.for(@current_user) do |option|
+  ="#{option} Bro!"
+```
+
+## Using a Tracker
+
+Let's say you have a hypothetical MixPanel Tracker you want to use for AB
+testing. You can for example implement it like this:
+
+```ruby
+class ApplicationController
+  before_filter :ab_tests
+  after_filter :track_ab_choices
+
+  def ab_tests
+    @greeting_test = Ab::Tester.new(:options=>["Yo", "Hello"],  :chances=>"50/50", :name=>"greeter")
+  end
+
+  def track_ab_choices
+    MixpanelTracker.track(@current_user, "experiment:greeting", :version=>@greeting_test.call(@current_user.id))
+  end
+end
+```
+
+## What a chance!
+
+The chances option of the ab view helper as well as in ```Ab::Tester``` takes a
+string as an argument. With a format using ```/```. It normalized the chances
+afterwards, so the following chances result in the exact same chance
+distribution:
+
+```ruby
+ Ab::Tester.new(:chances=>"10/60/30")
+ Ab::Tester.new(:chances=>"1/6/3")
+ Ab::Tester.new(:chances=>"35/210/105")
+```
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'olery_ab'
+    gem 'ab'
 
 And then execute:
 
@@ -14,11 +91,46 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install olery_ab
+    $ gem install ab
 
 ## Usage
 
-TODO: Write usage instructions here
+The main class is the ```Ab::Tester``` class which takes several options as arguments:
+
+## General Usage:
+```ruby
+tester = Ab::Tester.new(:name=>"test_name", :options=>[true, false], :chances=>"50/50")
+tester.for(user.id) # Will return true or false, depending on the user.id
+```
+
+```Ab::Tester``` options:
+
+* ```name```: Name of the tester, used as a seed to the random number generator 
+* ```options```: (required) Array of options to choose from in the test, the options can be anything
+* ```chances```: (required) String representing the chances of the options e.g. ```"10/20/70"```
+* ```indexer```: A class that responds a class level ```call(opts={})``` which contains the logic on how to get from a value, seed and chances to a choice. See the source code of the basic Indexer.
+
+### If you use rails
+
+You can also use the view helper ```ab``` with the exact same options as above
+
+option 1: using the output directy
+
+```erb
+Hello there <%=ab(:options=>["stranger", "you"], :chances=>"80/20").for(@current_user.id) %>
+```
+
+option 2: using a block:
+
+```erb
+<%=ab(:options=>[:stranger, :you], :chances=>"80/20").for(@current_user.id) do |option| %>
+  <% if option == :stranger %>
+    Hello there stranger!
+  <% elsif options == :you %>
+    Could you please introduce yourself?
+  <% end %>  
+<% end %>
+```
 
 ## Contributing
 

data/lib/ab/chance.rb

@@ -12,7 +12,21 @@ module Ab
     def self.normalize(array)
       sum = array.reduce(&:+)
       factor = 100.to_f / sum
-      array.map{|e| e * factor}.map(&:to_i)
+      normalized_chances = array.map{|e| e * factor}.map(&:to_i)
+      normalized_sum = normalized_chances.reduce(&:+)
+
+      # Check if sum of chances is 100.
+      # If it is not, add +1 to each chance (from last to first)
+      # until it reaches 100.
+      unless normalized_sum == 100
+        index = array.count - 1
+        (100 - normalized_sum).times do
+          normalized_chances[index] += 1
+          index = index < 0 ? array.count - 1 : index - 1
+        end
+      end
+      
+      return normalized_chances
     end
 
     def self.split_chance(string)

data/lib/ab/indexer.rb

@@ -7,7 +7,7 @@ module Ab
       chances = opts[:chances]
       salt = opts[:seed].to_s
 
-      seed = Digest::SHA1.hexdigest(salt + value).to_i
+      seed = Digest::SHA1.hexdigest(salt + value).to_i(16)
       random_number = Randomizer.new(seed).rand(1..100)
 
       sum = 0

data/lib/ab/version.rb

@@ -1,3 +1,3 @@
 module Ab
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/ab_test_spec.rb

@@ -15,6 +15,5 @@ describe "Helper Method" do
   it "should take multiple options" do
     expect{view.ab(:options=>[1,2,3], :chance=>"1/2/2", :input=>50)}.to_not raise_error
   end
-
 end
 

data/spec/tester_spec.rb

@@ -1,4 +1,5 @@
 require 'spec_helper'
+require 'securerandom'
 
 describe Ab::Tester do
 
@@ -37,6 +38,12 @@ describe Ab::Tester do
     Tester.new(:chances=>"0/1/0", :options=>[1,2,3]).call(1235).should eql(2)
     Tester.new(:chances=>"0/0/1", :options=>[1,2,3]).call(1235).should eql(3)
   end
+  
+  it "returns same result for same input" do
+    100.times do
+      Tester.new(:name => "Test", :options=>[1,2,3], :chances => "1/1/1").call(54321).should eql(3)
+    end
+  end
 
   it "should take a block and provide the result to the block" do
     expect do |b|
@@ -44,5 +51,26 @@ describe Ab::Tester do
         .call(1235, &b)
     end.to yield_with_args(1)
   end
-
+  
+  context 'distribution of results' do
+    it 'distributes almost equally in 1000 iterations 50/50 chance' do
+      result = []
+      1000.times do
+        random = SecureRandom.random_number(1000000000)
+        result << Tester.new(:name => "Test", :chances => "1/1").call(random)
+      end
+    
+      result.count(true).should be_within(50).of(500)
+    end
+    
+    it 'distributes almost equally in 1000 iterations 33/33/33 chance' do
+      result = []
+      1000.times do
+        random = SecureRandom.random_number(1000000000)
+        result << Tester.new(:name => "Test", :options=>[1,2,3], :chances => "1/1/1").call(random)
+      end
+      
+      result.count(1).should be_within(50).of(333)
+    end
+  end
 end

metadata

@@ -1,8 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ab
 version: !ruby/object:Gem::Version
-  version: 0.0.1
-  prerelease: 
+  version: 0.0.2
 platform: ruby
 authors:
 - sparkboxx
@@ -10,22 +9,20 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-21 00:00:00.000000000 Z
+date: 2015-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: Basic AB testing gem
@@ -36,7 +33,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -56,27 +53,26 @@ files:
 - spec/tester_spec.rb
 homepage: http://github.com/olery/ab
 licenses: []
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 2.4.5
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: The gem provides a basic class Tester or view helper function ab that allows
   you to deterministically show a certain option (a/b/c/etc) to a user based on a
   certain chance (e.g. 1/5)