eenie_meenie 0.0.5 → 0.1.0

data/README.md

@@ -1,21 +1,19 @@
 EenieMeenie
 ========
 
-This tool was written in order to play with some simple methods for assigning members of a population to one of two groups. The goal was initially to provide an algorithm that would limit the user's ability to predict to which group a member will be assigned.
+Decides to which experimental group a member of a population should be assigned.
 
 Installation
 ------------
 
-EenieMeenie is a Ruby gem, and can be installed using `gem install eenie_meenie`
+EenieMeenie is a Ruby gem, and can be installed using `gem install eenie_meenie` or by adding the following to your application's Gemfile:
+
+    gem 'eenie_meenie', '0.1.0'
 
 Usage
 -----
 
-EenieMeenie currently provides two algorithms for assigning members to experimental groups.
-
-`EenieMeenie::Assignment` was the first algorithm, and was intended to handle situations where members of a population are to be assigned to ONE of TWO groups.  As I started working with a greater variety of research studies, I found the algorithm to be both overcomplicated and inadequate.
-
-`EeenieMeenie::PolyAssignment` is a new algorithm.  With this algorithm you'll be able to:
+Attention! The usage of `EeenieMeenie::Assignment` changed with the release of version 0.1.0.  With the new algorithm you'll be able to:
 
 1. Assign a threshold (a `Float` to represent percentage) to each experimental group.
 2. Assign a threshold of "DO NOT CARE" to any group by passing `false` instead of a `Float`
@@ -30,13 +28,13 @@ Example Configurations
 # Experimental A: %50   (randomly assign)
 # Experimental B: %50   (randomly assign)
 
-EenieMeenie::PolyAssignment.new({
+EenieMeenie::Assignment.new({
   groups: ["Experimental A", "Experimental B"],  # EenieMeenie's assignment options
   member: @obj,                                  # Member of population
   group_rules: {
     "Control"        => { threshold: false },    # Don't care
     "Experimental A" => { threshold: 0.5 },      # No more than 50%
-    "Experimental B" =>  { threshold: 0.5 }      # No more than 50%
+    "Experimental B" => { threshold: 0.5 }       # No more than 50%
   },
   class_rules: { organization_id: 1}             # Only consider members belonging to Organization 1
 }).execute!
@@ -47,7 +45,7 @@ EenieMeenie::PolyAssignment.new({
 # Experimental A: %33.3   (randomly assign)
 # Experimental B: %33.3   (randomly assign)
 
-EenieMeenie::PolyAssignment.new({
+EenieMeenie::Assignment.new({
   groups: ["Control", "Experimental A", "Experimental B"],      # EenieMeenie's assignment options
   member: @obj,                                      # Member of population
   group_rules: {
@@ -61,7 +59,7 @@ EenieMeenie::PolyAssignment.new({
 
 ```ruby
 # Control:        %50         (randomly assign)
-# Experimental:   Do not care (randomly assign)
+# Experimental:   %50         (randomly assign)
 # Experimental A: Do not care (manually assign)
 # Experimental B: Do not care (manually assign)
 
@@ -69,12 +67,12 @@ EenieMeenie::PolyAssignment.new({
 # Later someone will choose whether they're in "Experimental A" ...
 # or in "Experimental B"
 
-EenieMeenie::PolyAssignment.new({
+EenieMeenie::Assignment.new({
   groups: ["Control", "Experimental"],       # EenieMeenie's assignment options
   member: @obj,                              # Member of population
   group_rules: {
-    "Control"        => { threshold: 0.5 },   # No more than one-third
-    "Experimental"   => { threshold: false }, # Don't care
+    "Control"        => { threshold: 0.5 },   # No more than one half
+    "Experimental"   => { threshold: 0.5 },   # No more than one half
     "Experimental A" => { threshold: false }  # Don't care
     "Experimental B" => { threshold: false }  # Don't care
   }
@@ -83,4 +81,4 @@ EenieMeenie::PolyAssignment.new({
 
 ### Pull requests/issues
 
-Please submit any useful pull requests through GitHub. Please report any bugs using Github's issue tracker
+Please submit any useful pull requests through GitHub. Please report any bugs using Github's issue tracker.

data/eenie_meenie.gemspec

@@ -19,6 +19,8 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
+  s.add_runtime_dependency     "pay_dirt",     "~> 0.0.5"
+
   s.add_development_dependency "minitest"
 
   s.add_development_dependency "rake"

data/lib/eenie_meenie/assignment.rb

@@ -1,62 +1,43 @@
 module EenieMeenie
-  class Assignment < ::EenieMeenie::Base
+  class Assignment < PayDirt::Base
     def initialize(options)
-      load_options(:groups, :member_class, options)
-      #raise ArgumentError unless @member_class.respond_to?(:experimental_group)
+      options = {
+        class_rules: {}
+      }.merge(options)
+
+      load_options(:member, :class_rules, :groups, :group_rules, options)
     end
 
     def execute!
-      group = assign
+      set_group_counts
+      return random_group
     end
 
     private
 
-    def assign
-      group = coercion_threshold_reached? ? assign_with_coercion : assign_without_coercion
-
-      group
-    end
-
-    def count_for_group(group)
-      @member_class.where(experimental_group: group).count
+    # Total population
+    def population
+      @members ||= @member.class.where(@class_rules)
     end
 
-    def assign_without_coercion
-      selected_group = @groups.sample
-      if rand(expected_population) >= (expected_population / 2)
-        group = selected_group
-      else
-        group = the_other_group(selected_group)
+    # Current population in each group
+    def set_group_counts
+      @group_rules.each do |k,v|
+        v[:count] = population.where(experimental_group: k.to_s).count
       end
     end
 
-    def assign_with_coercion
-      group = @groups.sample
-      group_tally = count_for_group(group)
-      other_group = (@groups - [group]).first
-      group = other_group if group_tally > count_for_group(other_group) + rand(leeway)
-
-      group
-    end
-
-    def expected_population
-      60000.to_f
-    end
-
-    def current_population
-      @member_class.count.to_f
-    end
-
-    def leeway
-      ((current_population / 2 ) * 0.01).round
-    end
+    # Groups not over threshold
+    def group_candidates
+      @group_candidates ||= @group_rules.reject { |k,v|
+        v[:threshold] && (v[:count] / @members.count.to_f) >= v[:threshold]
+      }.keys.map(&:to_s)
 
-    def the_other_group group
-      (@groups - [group]).first
+      @group_candidates.select {|cand| @groups.include?(cand) }
     end
 
-    def coercion_threshold_reached?
-      (current_population / expected_population) >= 0.9
+    def random_group
+      group_candidates.sample || @groups.sample
     end
   end
 end

data/lib/eenie_meenie/version.rb

@@ -1,3 +1,3 @@
 module EenieMeenie
-  VERSION = "0.0.5"
+  VERSION = "0.1.0"
 end

data/lib/eenie_meenie.rb

@@ -1,11 +1,2 @@
-require "eenie_meenie/base"
-#require "eenie_meenie/miny_moe"
-#require "eenie_meenie/sorters/round_robin"
-#require "eenie_meenie/sorters/pure_random"
-#require "eenie_meenie/sorters/pick_a_group"
-#require "eenie_meenie/version"
-#require "eenie_meenie/result"
-
-Dir.glob(File.join(File.dirname(__FILE__), '/**/*.rb')) do |c|
-  require(c)
-end
+require "pay_dirt"
+require "eenie_meenie/assignment"

data/test/eenie_meenie/assignment_test.rb

@@ -0,0 +1,57 @@
+require "minitest_helper"
+
+describe EenieMeenie::Assignment do
+  describe ".execute!" do
+    before do
+      # Mock dependencies
+      @member       = MiniTest::Mock.new
+      @member_class = MiniTest::Mock.new
+      @relation     = MiniTest::Mock.new
+      @groups       = ["Experimental", "Control"]
+      @group_rules  = {
+        "Experimental" => { threshold: 0.5 },
+        "Control"      => { threshold: 0.5 }
+      }
+
+      @minimum_dependencies = {
+        member: @member,
+        groups: @groups,
+        group_rules: @group_rules
+      }
+
+      @member.expect       :class, @member_class
+      @member_class.expect :where, @relation, [{}]
+      @relation.expect     :where, @relation, [{:experimental_group=>"Control"}]
+      @relation.expect     :count, 42
+      @relation.expect     :count, 42
+      @subject = EenieMeenie::Assignment
+    end
+
+    it "initializes when minimum dependencies are provided" do
+      proc {
+        @subject.new(@minimum_dependencies)
+      }.must_be_silent
+    end
+
+    it "fails to initialize without required options" do
+      @minimum_dependencies.each_key do |key|
+        begin
+          @subject.new(@minimum_dependencies.reject {|k| k == key })
+        rescue => e
+          e.must_be_kind_of RuntimeError
+        end
+      end
+    end
+
+    it "produces an expected result" do
+      result = @subject.new(@minimum_dependencies.merge({
+        groups: ["Control"],
+        group_rules: {
+          "Control"      => { threshold: 1.0 }
+        }
+      })).execute!
+
+      assert_equal result, "Control"
+    end
+  end
+end

metadata

@@ -1,16 +1,32 @@
 --- !ruby/object:Gem::Specification
 name: eenie_meenie
 version: !ruby/object:Gem::Version
+  version: 0.1.0
   prerelease:
-  version: 0.0.5
 platform: ruby
 authors:
 - Tad Hosford
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-05-23 00:00:00.000000000 Z
+date: 2013-05-27 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: pay_dirt
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.0.5
+    none: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.0.5
+    none: false
+  prerelease: false
+  type: :runtime
 - !ruby/object:Gem::Dependency
   name: minitest
   version_requirements: !ruby/object:Gem::Requirement
@@ -81,17 +97,8 @@ files:
 - eenie_meenie.gemspec
 - lib/eenie_meenie.rb
 - lib/eenie_meenie/assignment.rb
-- lib/eenie_meenie/base.rb
-- lib/eenie_meenie/miny_moe.rb
-- lib/eenie_meenie/poly_assignment.rb
-- lib/eenie_meenie/result.rb
-- lib/eenie_meenie/sorters/bucket_shuffle.rb
-- lib/eenie_meenie/sorters/late_coercion.rb
-- lib/eenie_meenie/sorters/pick_a_group.rb
-- lib/eenie_meenie/sorters/pure_random.rb
-- lib/eenie_meenie/sorters/round_robin.rb
 - lib/eenie_meenie/version.rb
-- test/eenie_meenie/miny_moe_test.rb
+- test/eenie_meenie/assignment_test.rb
 - test/minitest_helper.rb
 homepage: http://github.com/rthbound/eenie_meenie
 licenses: []
@@ -105,9 +112,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       segments:
       - 0
-      hash: 2
       version: !binary |-
         MA==
+      hash: 2
   none: false
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
@@ -115,9 +122,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       segments:
       - 0
-      hash: 2
       version: !binary |-
         MA==
+      hash: 2
   none: false
 requirements: []
 rubyforge_project:

data/lib/eenie_meenie/base.rb

@@ -1,13 +0,0 @@
-module EenieMeenie
-  class Base
-    def load_option(option, options)
-      instance_variable_set("@#{option}", options.fetch(option.to_sym) { raise "Missing required option: #{option}" } )
-    end
-
-    def load_options(*option_names, options)
-      option_names.each{|o| load_option(o, options) }
-
-      option_names << instance_variable_set("@tracked", options[:tracked]) if options[:tracked]
-    end
-  end
-end

data/lib/eenie_meenie/miny_moe.rb

@@ -1,14 +0,0 @@
-module EenieMeenie
-  class MinyMoe < ::EenieMeenie::Base
-    def initialize(options)
-      load_options(:groups, :population, :sorter, options)
-    end
-
-    def execute!
-      groups = @sorter.new(groups: @groups, population: @population).sort
-      return EenieMeenie::Result.new(groups: groups, population: @population)
-    end
-
-    private
-  end
-end

data/lib/eenie_meenie/poly_assignment.rb

@@ -1,43 +0,0 @@
-module EenieMeenie
-  class PolyAssignment < ::EenieMeenie::Base
-    def initialize(options)
-      options = {
-        class_rules: {}
-      }.merge(options)
-
-      load_options(:group_rules, :class_rules, :groups, :member, options)
-    end
-
-    def execute!
-      set_group_counts
-      return random_group
-    end
-
-    private
-
-    # Total population
-    def population
-      @members ||= @member.class.where(@class_rules)
-    end
-
-    # Current population in each group
-    def set_group_counts
-      @group_rules.each do |k,v|
-        v[:count] = population.where(experimental_group: k.to_s).count
-      end
-    end
-
-    # Groups not over threshold
-    def group_candidates
-      @group_candidates ||= @group_rules.reject { |k,v|
-        v[:threshold] && (v[:count] / @members.count.to_f) >= v[:threshold]
-      }.keys.map(&:to_s)
-
-      @group_candidates.select {|cand| @groups.include?(cand) }
-    end
-
-    def random_group
-      group_candidates.sample || @groups.sample
-    end
-  end
-end

data/lib/eenie_meenie/result.rb

@@ -1,22 +0,0 @@
-module EenieMeenie
-  class Result
-    def initialize(options)
-      @groups = options[:groups]
-      @population = options[:population]
-      @imbalance = @groups.values.inject(:-).abs
-      @relative_imbalance = (@imbalance / @population).to_f
-    end
-
-    def groups
-      @groups
-    end
-
-    def imbalance
-      @imbalance
-    end
-
-    def relative_imbalance
-      @relative_imbalance
-    end
-  end
-end

data/lib/eenie_meenie/sorters/bucket_shuffle.rb

@@ -1,20 +0,0 @@
-module EenieMeenie
-  module Sorters
-    class PureRandom < EenieMeenie::Base
-      def initialize(*args, options)
-        load_options(:groups, :population, options)
-      end
-
-      def sort
-        results = {}
-        @groups.each { |group| results.merge!(group => 0) }
-
-        @population.times do |i|
-          results[(rand(@population) >= (@population / 2) ? @groups.first : @groups.last)] += 1
-        end
-        groups = results
-      end
-    end
-  end
-end
-

data/lib/eenie_meenie/sorters/late_coercion.rb

@@ -1,61 +0,0 @@
-module EenieMeenie
-  module Sorters
-    class LateCoercion < EenieMeenie::Base
-      def initialize(*args, options)
-        load_options(:groups, :population, options)
-      end
-
-      def sort
-        @results = {}
-        @groups.each { |group| @results.merge!(group => 0) }
-
-        @population.times do |i|
-          @results[assign] += 1
-        end
-        groups = @results
-      end
-
-      def assign
-        coercion_threshold_reached? ? assign_with_coercion : assign_without_coercion
-      end
-
-      def assign_without_coercion
-        selected_group = @groups.sample
-        if rand(@population) >= (@population / 2)
-          group = selected_group
-        else
-          group = the_other_group(selected_group)
-        end
-      end
-
-      def the_other_group group
-        (@groups - [group]).first
-      end
-
-      def assign_with_coercion
-        group = @groups.sample
-        group_tally = count_for_group(group)
-        other_group = (@groups - [group]).first
-        group = other_group if group_tally > count_for_group(other_group) + rand(leeway)
-
-        group
-      end
-
-      def count_for_group(group)
-        @results[group].to_f
-      end
-
-      def leeway
-        ((current_population / 2 ) * 0.01).round
-      end
-
-      def current_population
-        @results.values.inject(&:+).to_f
-      end
-
-      def coercion_threshold_reached?
-        (current_population / @population) >= 0.9
-      end
-    end
-  end
-end

data/lib/eenie_meenie/sorters/pick_a_group.rb

@@ -1,23 +0,0 @@
-module EenieMeenie
-  module Sorters
-    class PickAGroup < EenieMeenie::Base
-      def initialize(*args, options)
-        load_options(:groups, :population, options)
-      end
-
-      def sort
-        results = {}
-        @groups.each { |group| results.merge!(group => 0) }
-
-        @population.times do |i|
-          group = @groups.sample
-          other_group = (@groups - [group]).first
-          group = other_group if results.values.any? {|v| results[group] > v + rand(10) }
-          results[group] += 1
-        end
-        groups = results
-      end
-    end
-  end
-end
-

data/lib/eenie_meenie/sorters/pure_random.rb

@@ -1,20 +0,0 @@
-module EenieMeenie
-  module Sorters
-    class PureRandom < EenieMeenie::Base
-      def initialize(*args, options)
-        load_options(:groups, :population, options)
-      end
-
-      def sort
-        results = {}
-        @groups.each { |group| results.merge!(group => 0) }
-
-        @population.times do |i|
-          results[(rand(@population) > (@population / 2) ? @groups.first : @groups.last)] += 1
-        end
-        groups = results
-      end
-    end
-  end
-end
-

data/lib/eenie_meenie/sorters/round_robin.rb

@@ -1,20 +0,0 @@
-module EenieMeenie
-  module Sorters
-    class RoundRobin < EenieMeenie::Base
-      def initialize(*args, options)
-        load_options(:groups, :population, options)
-      end
-
-      def sort
-        results = {}
-        @groups.each { |group| results.merge!(group => 0) }
-        @population.times do |i|
-          results[@groups[i % @groups.length]] += 1
-        end
-
-        groups = results
-      end
-    end
-  end
-end
-

data/test/eenie_meenie/miny_moe_test.rb

@@ -1,13 +0,0 @@
-require "minitest_helper"
-
-describe EenieMeenie::MinyMoe do
-  describe ".execute!" do
-    before do
-      @options = { population: 100, groups: ["Experimental", "Control"] }
-      @subject = EenieMeenie::MinyMoe
-    end
-    it "returns a result" do
-      @subject.new(@options.merge(sorter: EenieMeenie::Sorters::RoundRobin)).execute!.must_be_kind_of(EenieMeenie::Result)
-    end
-  end
-end