eenie_meenie 0.1.0 → 0.1.1

data/README.md

@@ -8,7 +8,7 @@ Installation
 
 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'
+    gem 'eenie_meenie', '0.1.1'
 
 Usage
 -----
@@ -19,10 +19,28 @@ Attention! The usage of `EeenieMeenie::Assignment` changed with the release of v
 2. Assign a threshold of "DO NOT CARE" to any group by passing `false` instead of a `Float`
 3. Tell EeenieMeenie which groups can be assigned by the algorithm.  Any group with a threshold should be included here.
 4. Tell it how to scope the member class (tell it which study, if you're using one member class for all studies)
+5. Specify the population to be used when calculating whether a group's population threshold has been reached.
 
 Example Configurations
 ----------------------
 
+eenie_meenie users can specify the population
+using the :members option, e.g.
+
+```ruby
+EenieMeenie::Assignment.new({
+  member:  @some_member,
+  members: MemberClass.where(something).joins(another),
+  groups:  ["Experimental", "Control"],
+  group_rules: {
+    "Experimental" => { threshold: 0.51 },
+    "Control"      => { threshold: 0.51 }
+  }
+})
+```
+
+Other examples ...
+
 ```ruby
 # Control: Do not care  (chosen manually, if ever)
 # Experimental A: %50   (randomly assign)
@@ -46,12 +64,12 @@ EenieMeenie::Assignment.new({
 # Experimental B: %33.3   (randomly assign)
 
 EenieMeenie::Assignment.new({
-  groups: ["Control", "Experimental A", "Experimental B"],      # EenieMeenie's assignment options
-  member: @obj,                                      # Member of population
+  groups: ["Control", "Experimental A", "Experimental B"], # EenieMeenie's assignment options
+  member: @obj,                                            # Member of population
   group_rules: {
-    "Control"         => { threshold: (1.0 / 3.0) },    # No more than one-third
-    "Experimental A"  => { threshold: (1.0 / 3.0) },    # No more than one-third
-    "Experimental B" => { threshold:  (1.0 / 3.0) }     # No more than one-third
+    "Control"         => { threshold: (1.0 / 3.0) },       # No more than one-third
+    "Experimental A"  => { threshold: (1.0 / 3.0) },       # No more than one-third
+    "Experimental B" => { threshold:  (1.0 / 3.0) }        # No more than one-third
   },
   class_rules: { organization_id: 1} # Only consider members belonging to Organization 1
 }).execute!

data/lib/eenie_meenie/assignment.rb

@@ -9,35 +9,54 @@ module EenieMeenie
     end
 
     def execute!
-      set_group_counts
-      return random_group
+      set_group_counts and return random_group
     end
 
     private
-
-    # Total population
+    # eenie_meenie users can specify the population
+    # using the :members option, e.g.
+    #   EenieMeenie::Assignment.new({
+    #     member:  @some_member,
+    #     members: MemberClass.where(something).joins(another),
+    #     groups:  ["Experimental", "Control"],
+    #     group_rules: {
+    #       "Experimental" => { threshold: 0.51 },
+    #       "Control"      => { threshold: 0.51 }
+    #     }
+    #   }).execute!
+    #
+    # By default, eenie_meenie will consider all records
+    # in the provided `:member`s class to be the population.
+    #
+    # If the :class_rules option is given, eenie_meenie will pass
+    # its value on to #where
     def population
       @members ||= @member.class.where(@class_rules)
     end
 
-    # Current population in each group
+    # Add some data to the hash before processing
     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)
+    # Pick from options whose thresholds have not been reached
+    def candidates
+      @group_rules.select { |k,v|
+        @groups.include?(k) && !busts_threshold?(k)
+      }.keys
+    end
 
-      @group_candidates.select {|cand| @groups.include?(cand) }
+    # Does the group's representation exceed the provided threshold?
+    def busts_threshold?(group_key)
+      group = @group_rules[group_key]
+      group[:count] / @members.count.to_f >= (group[:threshold] || 1)
     end
 
+    # Fallback on provided group options
     def random_group
-      group_candidates.sample || @groups.sample
+      candidates.sample || @groups.sample
     end
   end
 end

data/lib/eenie_meenie/version.rb

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

data/test/eenie_meenie/assignment_test.rb

@@ -22,6 +22,9 @@ describe EenieMeenie::Assignment do
       @member.expect       :class, @member_class
       @member_class.expect :where, @relation, [{}]
       @relation.expect     :where, @relation, [{:experimental_group=>"Control"}]
+      @relation.expect     :where, @relation, [{:experimental_group=>"Experimental"}]
+      @relation.expect     :count, 42
+      @relation.expect     :count, 42
       @relation.expect     :count, 42
       @relation.expect     :count, 42
       @subject = EenieMeenie::Assignment
@@ -47,11 +50,45 @@ describe EenieMeenie::Assignment do
       result = @subject.new(@minimum_dependencies.merge({
         groups: ["Control"],
         group_rules: {
-          "Control"      => { threshold: 1.0 }
+          "Control"      => { threshold: 1 },
+        }
+      })).execute!
+
+      result.must_equal "Control"
+    end
+
+    it "it defaults to a threshold of 100% if no threshold is provided" do
+      result = @subject.new(@minimum_dependencies.merge({
+        groups: ["Control"],
+        group_rules: {
+          "Control"      => { }
         }
       })).execute!
 
       assert_equal result, "Control"
     end
+
+    it "it defaults to a threshold of 100% if provided threshold is false(y)" do
+      result = @subject.new(@minimum_dependencies.merge({
+        groups: ["Control"],
+        group_rules: {
+          "Control"      => { threshold: false }
+        }
+      })).execute!
+
+      assert_equal result, "Control"
+    end
+
+    it "returns a result from the groups provided" do
+      result = @subject.new(@minimum_dependencies.merge({
+        groups: @groups,
+        group_rules: {
+          "Control"      => { threshold: 0.51 },
+          "Experimental" => { threshold: 0.51 }
+        }
+      })).execute!
+
+      @groups.must_include result
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eenie_meenie
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease:
 platform: ruby
 authors: