cohort_analysis 0.4.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,26 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+Gemfile.lock
+test/test.log
+*.gem
+.yardoc
+doc/

data/CHANGELOG

@@ -0,0 +1,19 @@
+0.4.0 / 2012-02-28
+
+* renamed to cohort_analysis
+
+* new, simplified syntax - see README.markdown
+
+0.3.0 / 2012-02-27
+
+* Now my_strategy = Person.strategy({:favorite_color => 'heliotrope', :birthdate => @date_range}, :importance => [:birthdate, :favorite_color]) will return a Arel::Nodes::Node which can be combined like Person.where(my_strategy.and("gender = 'male")) - it does NOT return a "scope" like before.
+
+* Refactor to take advantage of ARel.
+
+0.2.0
+
+* No longer "flattens" or "sanitizes" characteristics by turning records into integer IDs, etc. You should pass in exactly what you would pass into a normal ActiveRecord relation/scope.
+
+0.1.0
+
+* First version!

data/Gemfile

@@ -0,0 +1,12 @@
+source :rubygems
+
+gemspec
+
+# development dependencies
+gem 'minitest'
+gem 'minitest-reporters'
+gem 'factory_girl'
+gem 'mysql2'
+gem 'rake'
+gem 'yard'
+# gem 'ruby-debug19'

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Seamus Abshere
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,87 @@
+# cohort_analysis
+
+Lets you do cohort analysis based on two strategies: "big", which discards characteristics for the maximum cohort result, and "strict", which discards characteristics in order until a minimum cohort size is reached.
+
+Replaces [`cohort_scope`](https://github.com/seamusabshere/cohort_scope).
+
+## Where it's used
+
+* [Brighter Planet CM1 Impact Estimate web service](http://impact.brighterplanet.com) 
+* [Flight environmental impact model](https://github.com/brighterplanet/flight)
+
+## Strategies
+
+<dl>
+  <dt><code>:big</code></dt>
+  <dd>Default. Iteratively discards the characteristic that is most "restrictive," yielding the largest possible cohort. Note that it stops discarding after the minimum cohort size is reached.</dd>
+  <dt><code>:strict</code></dt>
+  <dd>Discards characteristics according to <code>:priority</code>.</dd>
+</dl>
+
+### `:big` example
+
+This is straight from the tests:
+
+    # make some fixtures
+    1_000.times { FactoryGirl.create(:lax) }
+    100.times { FactoryGirl.create(:lax_sfo) }
+    10.times { FactoryGirl.create(:lax_sfo_co) }
+    3.times { FactoryGirl.create(:lax_sfo_a320) }
+    1.times { FactoryGirl.create(:lax_sfo_aa_a320) }
+
+    lax_sfo_aa_a320 = {:origin => 'LAX', :dest => 'SFO', :airline => 'American', :plane => 'A320'}
+    # don't discard anything
+    Flight.cohort(lax_sfo_aa_a320).count.must_equal 1
+    # discard airline
+    Flight.cohort(lax_sfo_aa_a320, :minimum_size => 2).count.must_equal 4
+    # discard plane and airline
+    Flight.cohort(lax_sfo_aa_a320, :minimum_size => 5).count.must_equal 114
+    # discard plane and airline and dest
+    Flight.cohort(lax_sfo_aa_a320, :minimum_size => 115).count.must_equal 1_114
+
+    lax_sfo_a320 = {:origin => 'LAX', :dest => 'SFO', :plane => 'A320'}
+    # don't discard anything
+    Flight.cohort(lax_sfo_a320).count.must_equal 4
+    # discard plane
+    Flight.cohort(lax_sfo_a320, :minimum_size => 5).count.must_equal 114
+    # discard plane and dest
+    Flight.cohort(lax_sfo_a320, :minimum_size => 115).count.must_equal 1_114
+
+    # off the rails here a bit
+    woah_lax_co_a320 = {:origin => 'LAX', :airline => 'Continental', :plane => 'A320'}
+    # discard plane
+    Flight.cohort(woah_lax_co_a320).count.must_equal 10
+    # discard plane and airline
+    Flight.cohort(woah_lax_co_a320, :minimum_size => 11).count.must_equal 1_114
+
+### `:strict` example
+
+Also from the tests...
+
+    # make some fixtures
+    1_000.times { FactoryGirl.create(:lax) }
+    100.times { FactoryGirl.create(:lax_sfo) }
+    10.times { FactoryGirl.create(:lax_sfo_co) }
+    3.times { FactoryGirl.create(:lax_sfo_a320) }
+    1.times { FactoryGirl.create(:lax_sfo_aa_a320) }
+
+    lax_sfo_aa_a320 = {:origin => 'LAX', :dest => 'SFO', :airline => 'American', :plane => 'A320'}
+    priority = [:origin, :dest, :airline, :plane]
+    # discard nothing
+    Flight.cohort(lax_sfo_aa_a320, :strategy => :strict, :priority => priority).count.must_equal 1
+    # (force) discard plane, then (force) discard airline
+    Flight.cohort(lax_sfo_aa_a320, :strategy => :strict, :priority => priority, :minimum_size => 2).count.must_equal 114
+    # (force) discard plane, then (force) discard airline, then (force) discard dest
+    Flight.cohort(lax_sfo_aa_a320, :strategy => :strict, :priority => priority, :minimum_size => 115).count.must_equal 1_114
+
+    priority = [:plane, :airline, :dest, :origin]
+    # discard nothing
+    Flight.cohort(lax_sfo_aa_a320, :strategy => :strict, :priority => priority).count.must_equal 1
+    # (force) discard origin, then (force) discard dest, then (force) discard airline
+    Flight.cohort(lax_sfo_aa_a320, :strategy => :strict, :priority => priority, :minimum_size => 2).count.must_equal 4
+    # gives up!
+    Flight.cohort(lax_sfo_aa_a320, :strategy => :strict, :priority => priority, :minimum_size => 5).count.must_equal 0
+
+## Copyright
+
+Copyright (c) 2012 Brighter Planet, Inc.

data/Rakefile

@@ -0,0 +1,15 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rake'
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/cohort_analysis.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/cohort_analysis/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Seamus Abshere", "Andy Rossmeissl", "Derek Kastner", "Ian Hough"]
+  gem.email         = ["seamus@abshere.net", 'andy@rossmeissl.net', 'dkastner@gmail.com', 'ijhough@gmail.com']
+  desc = %q{Lets you do cohort analysis based on two strategies: "big", which discards characteristics for the maximum cohort result, and "strict", which discards characteristics in order until a minimum cohort size is reached.}
+  gem.description   = desc
+  gem.summary       = desc
+  gem.homepage      = "https://github.com/seamusabshere/cohort_analysis"
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "cohort_analysis"
+  gem.require_paths = ["lib"]
+  gem.version       = CohortAnalysis::VERSION
+
+  gem.add_runtime_dependency "activesupport", '>=3'
+  gem.add_runtime_dependency "activerecord", '>=3'
+end

data/lib/cohort_analysis.rb

@@ -0,0 +1,26 @@
+require 'arel'
+require 'active_record'
+require 'active_support/core_ext'
+
+require 'cohort_analysis/strategy'
+require 'cohort_analysis/strategy/big'
+require 'cohort_analysis/strategy/strict'
+
+require 'cohort_analysis/active_record_base_class_methods'
+require 'cohort_analysis/active_record_relation_instance_methods'
+require 'cohort_analysis/arel_visitors_visitor_instance_methods'
+
+module CohortAnalysis
+  def self.conditions_for(characteristics)
+    case characteristics
+    when ::Array
+      characteristics.inject({}) { |memo, (k, v)| memo[k] = v; memo }
+    else
+      characteristics
+    end
+  end
+end
+
+ActiveRecord::Base.extend CohortAnalysis::ActiveRecordBaseClassMethods
+ActiveRecord::Relation.send :include, CohortAnalysis::ActiveRecordRelationInstanceMethods
+Arel::Visitors::Visitor.send :include, CohortAnalysis::ArelVisitorsVisitorInstanceMethods

data/lib/cohort_analysis/active_record_base_class_methods.rb

@@ -0,0 +1,11 @@
+module CohortAnalysis
+  module ActiveRecordBaseClassMethods
+    def cohort(*args)
+      scoped.cohort *args
+    end
+
+    def cohort_constraint(*args)
+      scoped.cohort_constraint *args
+    end
+  end
+end

data/lib/cohort_analysis/active_record_relation_instance_methods.rb

@@ -0,0 +1,13 @@
+module CohortAnalysis
+  module ActiveRecordRelationInstanceMethods
+    def cohort(characteristics, options = {})
+      where cohort_constraint(characteristics, options)
+    end
+
+    def cohort_constraint(characteristics, options = {})
+      options = options.symbolize_keys
+      strategy = (options.delete(:strategy) || :big).to_s.camelcase
+      Strategy.const_get(strategy).new(self, characteristics, options)
+    end
+  end
+end

data/lib/cohort_analysis/arel_visitors_visitor_instance_methods.rb

@@ -0,0 +1,7 @@
+module CohortAnalysis
+  module ArelVisitorsVisitorInstanceMethods
+    def visit_CohortAnalysis_Strategy(o)
+      o.expr
+    end
+  end
+end

data/lib/cohort_analysis/strategy.rb

@@ -0,0 +1,31 @@
+module CohortAnalysis
+  class Strategy < ::Arel::Nodes::Node
+    IMPOSSIBLE = '1 = 2'
+
+    def initialize(active_record_relation, characteristics, options = {})
+      @active_record_relation = active_record_relation
+      @characteristics = characteristics
+      @reduced_characteristics = characteristics.dup
+      @minimum_size = options.fetch(:minimum_size, 1)
+    end
+
+    def expr
+      @expr ||= resolve!
+    end
+    alias :to_sql :expr
+
+    private
+
+    # Recursively look for a scope that meets the characteristics and is at least <tt>minimum_size</tt>.
+    def resolve!
+      if @reduced_characteristics.empty?
+        IMPOSSIBLE
+      elsif (current = @active_record_relation.where(CohortAnalysis.conditions_for(@reduced_characteristics))).count >= @minimum_size
+        current.constraints.inject(:and).to_sql
+      else
+        reduce!
+        resolve!
+      end
+    end
+  end
+end

data/lib/cohort_analysis/strategy/big.rb

@@ -0,0 +1,20 @@
+module CohortAnalysis
+  class Strategy
+    class Big < Strategy
+      # Reduce characteristics by removing them one by one and counting the results.
+      #
+      # The characteristic whose removal leads to the highest record count is removed from the overall characteristic set.
+      def reduce!
+        @reduced_characteristics = if @reduced_characteristics.keys.length < 2
+          {}
+        else
+          most_restrictive_characteristic = @reduced_characteristics.keys.max_by do |key|
+            conditions = CohortAnalysis.conditions_for @reduced_characteristics.except(key)
+            @active_record_relation.where(conditions).count
+          end
+          @reduced_characteristics.except most_restrictive_characteristic
+        end
+      end
+    end
+  end
+end

data/lib/cohort_analysis/strategy/strict.rb

@@ -0,0 +1,30 @@
+module CohortAnalysis
+  class Strategy
+    class Strict < Strategy
+      def initialize(active_record_relation, characteristics, options = {})
+        super
+        if priority = options[:priority]
+          @reverse_priority = priority.reverse
+        elsif ::RUBY_VERSION < '1.9' and not characteristics.is_a?(::ActiveSupport::OrderedHash)
+          raise ::ArgumentError, "[cohort_analysis] Since Ruby 1.8 hashes are not ordered, please use :priority => [...] or pass characteristics as an ActiveSupport::OrderedHash (not recommended)"
+        end
+      end
+
+      # Reduce characteristics by removing the least important one.
+      def reduce!
+        least_important_key = if @reverse_priority
+          @reverse_priority.detect do |k|
+            @reduced_characteristics.has_key? k
+          end
+        else
+          @reduced_characteristics.keys.last
+        end
+        if least_important_key
+          @reduced_characteristics.delete least_important_key
+        else
+          raise ::RuntimeError, "[cohort_analysis] Priority improperly specified"
+        end
+      end
+    end
+  end
+end

data/lib/cohort_analysis/version.rb

@@ -0,0 +1,3 @@
+module CohortAnalysis
+  VERSION = '0.4.0'
+end

data/test/helper.rb

@@ -0,0 +1,28 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'minitest/spec'
+require 'minitest/autorun'
+require 'minitest/reporters'
+MiniTest::Unit.runner = MiniTest::SuiteRunner.new
+MiniTest::Unit.runner.reporters << MiniTest::Reporters::SpecReporter.new
+
+require 'factory_girl'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'cohort_analysis'
+
+if ::Bundler.definition.specs['ruby-debug19'].first or ::Bundler.definition.specs['ruby-debug'].first
+  require 'ruby-debug'
+end
+
+# require 'logger'
+# ActiveRecord::Base.logger = Logger.new($stdout)
+
+ActiveRecord::Base.establish_connection(
+  'adapter' => 'mysql2',
+  'database' => 'test_cohort_analysis',
+  'username' => 'root',
+  'password' => 'password'
+)

data/test/test_cohort_analysis.rb

@@ -0,0 +1,222 @@
+require 'helper'
+
+c = ActiveRecord::Base.connection
+c.create_table 'flights', :force => true do |t|
+  t.string 'origin'
+  t.string 'dest'
+  t.string 'airline'
+  t.string 'plane'
+end
+
+class Flight < ActiveRecord::Base
+end
+
+FactoryGirl.define do
+  factory :lax, :class => Flight do
+    origin 'LAX'
+  end
+  factory :lax_sfo, :class => Flight do
+    origin 'LAX'
+    dest 'SFO'
+  end
+  factory :lax_sfo_co, :class => Flight do
+    origin 'LAX'
+    dest 'SFO'
+    airline 'Continental'
+  end
+  factory :lax_sfo_a320, :class => Flight do
+    origin 'LAX'
+    dest 'SFO'
+    plane 'A320'
+  end
+  factory :lax_sfo_aa_a320, :class => Flight do
+    origin 'LAX'
+    dest 'SFO'
+    airline 'American'
+    plane 'A320'
+  end
+end
+
+describe CohortAnalysis do
+  before do
+    Flight.delete_all
+  end
+
+  describe 'ActiveRecordBaseClassMethods' do
+    describe :cohort do
+      it "defaults to :minimum_size => 1" do
+        FactoryGirl.create(:lax)
+        Flight.cohort({:origin => 'LAX'}).count.must_equal 1
+        Flight.cohort({:origin => 'LAX'}, :minimum_size => 2).count.must_equal 0
+      end
+
+      it "doesn't discard characteristics if it doesn't need to" do
+        FactoryGirl.create(:lax)
+        FactoryGirl.create(:lax_sfo)
+        Flight.cohort(:origin => 'LAX', :dest => 'SFO').count.must_equal 1
+      end
+
+      it "discards characteristics until it can fulfil the minimum size" do
+        FactoryGirl.create(:lax)
+        FactoryGirl.create(:lax_sfo)
+        drops_dest = Flight.cohort({:origin => 'LAX', :dest => 'SFO'}, :minimum_size => 2)
+        drops_dest.count.must_equal 2
+        drops_dest.one? { |flight| flight.dest != 'SFO' }.must_equal true
+      end
+
+      it "defaults to :strategy => :big" do
+        FactoryGirl.create(:lax)
+        Flight.cohort({:origin => 'LAX', :dest => 'SFO'}, :strategy => :big).count.must_equal Flight.cohort(:origin => 'LAX', :dest => 'SFO').count
+        Flight.cohort({:dest => 'SFO', :origin => 'LAX'}, :strategy => :big).count.must_equal Flight.cohort(:dest => 'SFO', :origin => 'LAX').count
+      end
+
+      it "offers :strategy => :strict" do
+        FactoryGirl.create(:lax)
+        if RUBY_VERSION >= '1.9'
+          # native ordered hashes
+          Flight.cohort({:origin => 'LAX', :dest => 'SFO'}, :strategy => :strict).count.must_equal 1
+          Flight.cohort({:dest => 'SFO', :origin => 'LAX'}, :strategy => :strict).count.must_equal 0
+        else
+          # activesupport provides ActiveSupport::OrderedHash
+          origin_important = ActiveSupport::OrderedHash.new
+          origin_important[:origin] = 'LAX'
+          origin_important[:dest] = 'SFO'
+          dest_important = ActiveSupport::OrderedHash.new
+          dest_important[:dest] = 'SFO'
+          dest_important[:origin] = 'LAX'
+          Flight.cohort(origin_important, :strategy => :strict).count.must_equal 1
+          Flight.cohort(dest_important, :strategy => :strict).count.must_equal 0
+
+          lambda {
+            Flight.cohort({:origin => 'LAX', :dest => 'SFO'}, :strategy => :strict).count
+          }.must_raise(ArgumentError, 'hash')
+        end
+      end
+
+      it "lets you pick :priority of keys when using :strict strategy" do
+        FactoryGirl.create(:lax)
+        Flight.cohort({:origin => 'LAX', :dest => 'SFO'}, :strategy => :strict, :priority => [:origin, :dest]).count.must_equal 1
+        Flight.cohort({:origin => 'LAX', :dest => 'SFO'}, :strategy => :strict, :priority => [:dest, :origin]).count.must_equal 0
+        Flight.cohort({:dest => 'SFO', :origin => 'LAX'}, :strategy => :strict, :priority => [:origin, :dest]).count.must_equal 1
+        Flight.cohort({:dest => 'SFO', :origin => 'LAX'}, :strategy => :strict, :priority => [:dest, :origin]).count.must_equal 0
+      end
+
+      it "lets you play with more than 1 or 2 characteristics" do
+        ActiveRecord::Base.silence do
+          # make some fixtures
+          1_000.times { FactoryGirl.create(:lax) }
+          100.times { FactoryGirl.create(:lax_sfo) }
+          10.times { FactoryGirl.create(:lax_sfo_co) }
+          3.times { FactoryGirl.create(:lax_sfo_a320) }
+          1.times { FactoryGirl.create(:lax_sfo_aa_a320) }
+        end
+        Flight.count.must_equal 1_114 # sanity check
+
+        lax_sfo_aa_a320 = {:origin => 'LAX', :dest => 'SFO', :airline => 'American', :plane => 'A320'}
+        # don't discard anything
+        Flight.cohort(lax_sfo_aa_a320).count.must_equal 1
+        # discard airline
+        Flight.cohort(lax_sfo_aa_a320, :minimum_size => 2).count.must_equal 4
+        # discard plane and airline
+        Flight.cohort(lax_sfo_aa_a320, :minimum_size => 5).count.must_equal 114
+        # discard plane and airline and dest
+        Flight.cohort(lax_sfo_aa_a320, :minimum_size => 115).count.must_equal 1_114
+
+        lax_sfo_a320 = {:origin => 'LAX', :dest => 'SFO', :plane => 'A320'}
+        # don't discard anything
+        Flight.cohort(lax_sfo_a320).count.must_equal 4
+        # discard plane
+        Flight.cohort(lax_sfo_a320, :minimum_size => 5).count.must_equal 114
+        # discard plane and dest
+        Flight.cohort(lax_sfo_a320, :minimum_size => 115).count.must_equal 1_114
+
+        # off the rails here a bit
+        woah_lax_co_a320 = {:origin => 'LAX', :airline => 'Continental', :plane => 'A320'}
+        # discard plane
+        Flight.cohort(woah_lax_co_a320).count.must_equal 10
+        # discard plane and airline
+        Flight.cohort(woah_lax_co_a320, :minimum_size => 11).count.must_equal 1_114
+      end
+
+      it "lets you play with multiple characteristics in :strategy => :strict" do
+        ActiveRecord::Base.silence do
+          # make some fixtures
+          1_000.times { FactoryGirl.create(:lax) }
+          100.times { FactoryGirl.create(:lax_sfo) }
+          10.times { FactoryGirl.create(:lax_sfo_co) }
+          3.times { FactoryGirl.create(:lax_sfo_a320) }
+          1.times { FactoryGirl.create(:lax_sfo_aa_a320) }
+        end
+
+        lax_sfo_aa_a320 = {:origin => 'LAX', :dest => 'SFO', :airline => 'American', :plane => 'A320'}
+        priority = [:origin, :dest, :airline, :plane]
+        # discard nothing
+        Flight.cohort(lax_sfo_aa_a320, :strategy => :strict, :priority => priority).count.must_equal 1
+        # (force) discard plane, then (force) discard airline
+        Flight.cohort(lax_sfo_aa_a320, :strategy => :strict, :priority => priority, :minimum_size => 2).count.must_equal 114
+        # (force) discard plane, then (force) discard airline, then (force) discard dest
+        Flight.cohort(lax_sfo_aa_a320, :strategy => :strict, :priority => priority, :minimum_size => 115).count.must_equal 1_114
+
+        priority = [:plane, :airline, :dest, :origin]
+        # discard nothing
+        Flight.cohort(lax_sfo_aa_a320, :strategy => :strict, :priority => priority).count.must_equal 1
+        # (force) discard origin, then (force) discard dest, then (force) discard airline
+        Flight.cohort(lax_sfo_aa_a320, :strategy => :strict, :priority => priority, :minimum_size => 2).count.must_equal 4
+        # gives up!
+        Flight.cohort(lax_sfo_aa_a320, :strategy => :strict, :priority => priority, :minimum_size => 5).count.must_equal 0
+      end
+    end
+
+    describe :cohort_constraint do
+      it "can be used like other ARel constraints" do
+        FactoryGirl.create(:lax)
+        Flight.where(Flight.cohort_constraint(:origin => 'LAX')).count.must_equal 1
+        Flight.where(Flight.cohort_constraint({:origin => 'LAX'}, :minimum_size => 2)).count.must_equal 0
+      end
+
+      it "can be combined with other ARel constraints" do
+        FactoryGirl.create(:lax)
+        FactoryGirl.create(:lax_sfo)
+        origin_lax_constraint = Flight.cohort_constraint(:origin => 'LAX')
+        dest_sfo_constraint = Flight.arel_table[:dest].eq('SFO')
+        Flight.where(dest_sfo_constraint.and(origin_lax_constraint)).count.must_equal 1
+        Flight.where(dest_sfo_constraint.or(origin_lax_constraint)).count.must_equal 2
+        Flight.where(origin_lax_constraint.and(dest_sfo_constraint)).count.must_equal 1
+        Flight.where(origin_lax_constraint.or(dest_sfo_constraint)).count.must_equal 2
+      end
+
+      # Caution!
+      it "is NOT smart enough to enforce minimum size when composed" do
+        FactoryGirl.create(:lax)
+        FactoryGirl.create(:lax_sfo)
+        origin_lax_constraint = Flight.cohort_constraint({:origin => 'LAX'}, :minimum_size => 2)
+        dest_sfo_constraint = Flight.arel_table[:dest].eq('SFO')
+        Flight.where(dest_sfo_constraint.and(origin_lax_constraint)).count.must_equal 1 # see how minimum_size is ignored?
+        Flight.where(origin_lax_constraint.and(dest_sfo_constraint)).count.must_equal 1 # it's because the cohort constraint resolves itself before allowing the ARel visitor to continue
+      end
+    end
+  end
+
+  describe 'ActiveRecordRelationInstanceMethods' do
+    describe :cohort do
+      it "is the proper way to compose when other ARel constraints are present" do
+        FactoryGirl.create(:lax)
+        FactoryGirl.create(:lax_sfo)
+        Flight.where(:dest => 'SFO').cohort(:origin => 'LAX').count.must_equal 1
+        Flight.where(:dest => 'SFO').cohort({:origin => 'LAX'}, :minimum_size => 2).count.must_equal 0
+      end
+    end
+    describe :cohort_constraint do
+      it "can also be used (carefully) to compose with other ARel constraints" do
+        FactoryGirl.create(:lax)
+        FactoryGirl.create(:lax_sfo)
+        dest_sfo_relation = Flight.where(:dest => 'SFO')
+        origin_lax_constraint_from_dest_sfo_relation = dest_sfo_relation.cohort_constraint(:origin => 'LAX')
+        Flight.where(origin_lax_constraint_from_dest_sfo_relation).count.must_equal 1
+        dest_sfo_relation = Flight.where(:dest => 'SFO')
+        origin_lax_constraint_from_dest_sfo_relation = dest_sfo_relation.cohort_constraint({:origin => 'LAX'}, :minimum_size => 2)
+        Flight.where(origin_lax_constraint_from_dest_sfo_relation).count.must_equal 0
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification 
+name: cohort_analysis
+version: !ruby/object:Gem::Version 
+  hash: 15
+  prerelease: 
+  segments: 
+  - 0
+  - 4
+  - 0
+  version: 0.4.0
+platform: ruby
+authors: 
+- Seamus Abshere
+- Andy Rossmeissl
+- Derek Kastner
+- Ian Hough
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-02-29 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 3
+        version: "3"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 3
+        version: "3"
+  type: :runtime
+  version_requirements: *id002
+description: "Lets you do cohort analysis based on two strategies: \"big\", which discards characteristics for the maximum cohort result, and \"strict\", which discards characteristics in order until a minimum cohort size is reached."
+email: 
+- seamus@abshere.net
+- andy@rossmeissl.net
+- dkastner@gmail.com
+- ijhough@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .document
+- .gitignore
+- CHANGELOG
+- Gemfile
+- LICENSE
+- README.markdown
+- Rakefile
+- cohort_analysis.gemspec
+- lib/cohort_analysis.rb
+- lib/cohort_analysis/active_record_base_class_methods.rb
+- lib/cohort_analysis/active_record_relation_instance_methods.rb
+- lib/cohort_analysis/arel_visitors_visitor_instance_methods.rb
+- lib/cohort_analysis/strategy.rb
+- lib/cohort_analysis/strategy/big.rb
+- lib/cohort_analysis/strategy/strict.rb
+- lib/cohort_analysis/version.rb
+- test/helper.rb
+- test/test_cohort_analysis.rb
+homepage: https://github.com/seamusabshere/cohort_analysis
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: "Lets you do cohort analysis based on two strategies: \"big\", which discards characteristics for the maximum cohort result, and \"strict\", which discards characteristics in order until a minimum cohort size is reached."
+test_files: 
+- test/helper.rb
+- test/test_cohort_analysis.rb
+has_rdoc: