added block randomization algorithm and specs (#475)

* added block randomization algorithm and specs

* added BlockRandomization explanation to README

Author: hulleywood

README.md

@@ -793,6 +793,12 @@ It is possible to specify static weights to favor certain alternatives.
 This algorithm will automatically weight the alternatives based on their relative performance,
 choosing the better-performing ones more often as trials are completed.
 
+`Split::Algorithms::BlockRandomization` is an algorithm that ensures equal
+participation across all alternatives. This algorithm will choose the alternative
+with the fewest participants. In the event of multiple minimum participant alternatives
+(i.e. starting a new "Block") the algorithm will choose a random alternative from
+those minimum participant alternatives.
+
 Users may also write their own algorithms. The default algorithm may be specified globally in the configuration file, or on a per experiment basis using the experiments hash of the configuration file.
 
 To change the algorithm globally for all experiments, use the following in your initializer:

lib/split/algorithms/block_randomization.rb

@@ -0,0 +1,22 @@
+# Selects alternative with minimum count of participants
+# If all counts are even (i.e. all are minimum), samples from all possible alternatives
+
+module Split
+  module Algorithms
+    module BlockRandomization
+      class << self
+        def choose_alternative(experiment)
+          minimum_participant_alternatives(experiment.alternatives).sample
+        end
+
+        private
+
+        def minimum_participant_alternatives(alternatives)
+          alternatives_by_count = alternatives.group_by(&:participant_count)
+          min_group = alternatives_by_count.min_by { |k, v| k }
+          min_group.last
+        end
+      end
+    end
+  end
+end

spec/algorithms/block_randomization_spec.rb

@@ -0,0 +1,32 @@
+require "spec_helper"
+
+describe Split::Algorithms::BlockRandomization do
+
+  let(:experiment) { Split::Experiment.new 'experiment' }
+  let(:alternative_A) { Split::Alternative.new 'A', 'experiment' }
+  let(:alternative_B) { Split::Alternative.new 'B', 'experiment' }
+  let(:alternative_C) { Split::Alternative.new 'C', 'experiment' }
+
+  before :each do
+    allow(experiment).to receive(:alternatives) { [alternative_A, alternative_B, alternative_C] }
+  end
+
+  it "should return an alternative" do
+    expect(Split::Algorithms::BlockRandomization.choose_alternative(experiment).class).to eq(Split::Alternative)
+  end
+
+  it "should always return the minimum participation option" do
+    allow(alternative_A).to receive(:participant_count) { 1 }
+    allow(alternative_B).to receive(:participant_count) { 1 }
+    allow(alternative_C).to receive(:participant_count) { 0 }
+    expect(Split::Algorithms::BlockRandomization.choose_alternative(experiment)).to eq(alternative_C)
+  end
+
+  it "should return one of the minimum participation options when multiple" do
+    allow(alternative_A).to receive(:participant_count) { 0 }
+    allow(alternative_B).to receive(:participant_count) { 0 }
+    allow(alternative_C).to receive(:participant_count) { 0 }
+    alternative = Split::Algorithms::BlockRandomization.choose_alternative(experiment)
+    expect([alternative_A, alternative_B, alternative_C].include?(alternative)).to be(true)
+  end
+end