cohort_analysis 0.4.0 → 1.0.0

data/.yardopts

@@ -0,0 +1,2 @@
+--no-private
+--readme README.markdown

data/CHANGELOG

@@ -1,13 +1,25 @@
+1.0.0 / 2012-05-30
+
+* Breaking changes
+
+  * Cohorts with initially (originally) empty characteristics return everything. Before they returned nothing.
+  * Removed #cohort_constraint. There was really no correct way to use it. Now it's recommended you union together cohorts.
+  * ActiveRecord::{Base.,Relation#}cohort returns an Arel::SelectManager, NOT another ActiveRecord::Relation. That means you can't call, for example, #count on it - you have to treat it like an ARel object.
+
+* Enhancements
+
+  * You can use #cohort when composing with ARel. Just be safe about how you use it - it's not an automagic ActiveRecord::Relation.
+  * True unit tests, including explicit tests for UNIONing together cohorts.
+  * Tested on MRI 1.8, MRI 1.9, and JRuby 1.6.7
+
 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

data/Gemfile

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

data/README.markdown

@@ -18,70 +18,6 @@ Replaces [`cohort_scope`](https://github.com/seamusabshere/cohort_scope).
   <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/cohort_analysis.gemspec

@@ -16,6 +16,24 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = CohortAnalysis::VERSION
 
-  gem.add_runtime_dependency "activesupport", '>=3'
-  gem.add_runtime_dependency "activerecord", '>=3'
+  gem.add_runtime_dependency 'activesupport', '>=3'
+  gem.add_runtime_dependency 'arel', '>=3'
+  
+  gem.add_development_dependency 'activerecord', '>=3'
+  gem.add_development_dependency 'active_record_inline_schema'
+  gem.add_development_dependency 'minitest'
+  gem.add_development_dependency 'minitest-reporters'
+  gem.add_development_dependency 'yard'
+  if RUBY_VERSION >= '1.9'
+    gem.add_development_dependency 'factory_girl'
+  else
+    gem.add_development_dependency 'factory_girl', '~>2'
+  end
+  if RUBY_PLATFORM == 'java'
+    gem.add_development_dependency 'activerecord-jdbcsqlite3-adapter'
+  else
+    gem.add_development_dependency 'sqlite3'
+  end
+
+  # gem.add_development_dependency 'debugger'
 end

data/lib/cohort_analysis/active_record_base_class_methods.rb

@@ -3,9 +3,5 @@ module CohortAnalysis
     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

@@ -1,13 +1,42 @@
 module CohortAnalysis
   module ActiveRecordRelationInstanceMethods
+    # @note This doesn't return a <code>ActiveRecord::Relation</code>, so you can't just call count.
+    #
+    # @example Count a Flight cohort
+    #   cohort = Flight.cohort(:origin => 'MSN', :dest => 'ORD')
+    #   cohort.count #=> BAD! just plain Arel::SelectManager doesn't provide #count, that's an ActiveRecord::Relation thing
+    #   Flight.connection.select_value(cohort.project('COUNT(*)').to_sql) #=> what you wanted
+    #
+    # @return [Arel::SelectManager] A select manager without any projections.
     def cohort(characteristics, options = {})
-      where cohort_constraint(characteristics, options)
+      select_manager = arel.clone
+      select_manager.projections = []
+      select_manager.where Strategy.create(select_manager, characteristics, options)
+      select_manager
     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)
+    # @note Won't work properly unless it's the last constraint in your chain.
+    #
+    # @example Making sure it's the last thing you call
+    #   Flight.cohort_relation(:origin => 'MSN', :dest => 'ORD').where(:year => 2009) #=> BAD! the cohort calculation CANNOT see :year => 2009
+    #   Flight.where(:year => 2009).cohort_relation(:origin => 'MSN', :dest => 'ORD') #=> OK!
+    #
+    # @return [ActiveRecord::Relation]
+    def cohort_relation(characteristics, options = {})
+      where Strategy.create(arel, characteristics, options)
     end
   end
 end
+
+=begin
+if i return ActiveRecord::Relation#where(strategy), and somebody calls #where on it, a new relation is returned that includes the strategy, but the strategy can't see the new where values
+
+  relation = clone                                  # which keeps where_values but clears @arel
+  relation.where_values += build_where(opts, rest)  # which just adds the expr
+  relation
+
+if i return Arel::SelectManager#where(strategy), it keeps the context, so the strategy can use that
+
+  @ctx.wheres << expr
+  self
+=end

data/lib/cohort_analysis/arel_select_manager_instance_methods.rb

@@ -0,0 +1,8 @@
+module CohortAnalysis
+  module ArelSelectManagerInstanceMethods
+    # @return [Arel::SelectManager]
+    def cohort(characteristics, options = {})
+      where Strategy.create(self, characteristics, options)
+    end
+  end
+end

data/lib/cohort_analysis/arel_table_instance_methods.rb

@@ -0,0 +1,7 @@
+module CohortAnalysis
+  module ArelTableInstanceMethods
+    def cohort(*args)
+      from(self).cohort *args
+    end
+  end
+end

data/lib/cohort_analysis/strategy/big.rb

@@ -5,14 +5,13 @@ module CohortAnalysis
       #
       # 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
+        @current = if current.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
+          most_restrictive = current.keys.max_by do |k|
+            count current.except(k)
           end
-          @reduced_characteristics.except most_restrictive_characteristic
+          current.except most_restrictive
         end
       end
     end

data/lib/cohort_analysis/strategy/strict.rb

@@ -1,7 +1,9 @@
 module CohortAnalysis
   class Strategy
     class Strict < Strategy
-      def initialize(active_record_relation, characteristics, options = {})
+      attr_reader :reverse_priority
+      
+      def initialize(select_manager, characteristics, options = {})
         super
         if priority = options[:priority]
           @reverse_priority = priority.reverse
@@ -12,15 +14,15 @@ module CohortAnalysis
 
       # 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
+        least_important_key = if reverse_priority
+          reverse_priority.detect do |k|
+            current.has_key? k
           end
         else
-          @reduced_characteristics.keys.last
+          current.keys.last
         end
         if least_important_key
-          @reduced_characteristics.delete least_important_key
+          current.delete least_important_key
         else
           raise ::RuntimeError, "[cohort_analysis] Priority improperly specified"
         end

data/lib/cohort_analysis/strategy.rb

@@ -1,31 +1,118 @@
 module CohortAnalysis
   class Strategy < ::Arel::Nodes::Node
-    IMPOSSIBLE = '1 = 2'
+    class << self
+      def create(select_manager, characteristics, options = {})
+        options = options.symbolize_keys
+        strategy = if options.has_key? :strategy
+          options[:strategy]
+        elsif options.has_key? :priority
+          :strict
+        else
+          DEFAULT_STRATEGY
+        end
+        const_get(strategy.to_s.camelcase).new(select_manager, characteristics, options)
+      end
+    end
+
+    module AlwaysTrue
+      def self.to_sql; '1 = 1' end
+    end
+    module Impossible
+      def self.to_sql; '1 = 2' end
+    end
+
+    DEFAULT_STRATEGY = :big
 
-    def initialize(active_record_relation, characteristics, options = {})
-      @active_record_relation = active_record_relation
-      @characteristics = characteristics
-      @reduced_characteristics = characteristics.dup
+    attr_reader :select_manager
+    attr_reader :original
+    attr_reader :current
+    attr_reader :minimum_size
+    attr_reader :table_name
+    attr_reader :table
+
+    def initialize(select_manager, characteristics, options = {})
+      @select_manager = select_manager
+      @table_name = select_manager.source.left.name
+      @table = Arel::Table.new table_name
+      @original = characteristics.dup
+      @current = characteristics.dup
       @minimum_size = options.fetch(:minimum_size, 1)
+      @final_mutex = ::Mutex.new
+    end
+
+    def final
+      @final || if @final_mutex.try_lock
+        begin
+          @final ||= resolve!
+        ensure
+          @final_mutex.unlock
+        end
+      else
+        Impossible
+      end
     end
 
     def expr
-      @expr ||= resolve!
+      final.to_sql
+    end
+
+    def ==(other)
+      other.is_a?(Strategy) and
+        table_name == other.table_name and
+        minimum_size = other.minimum_size and
+        original == other.original
     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
+      if original.empty?
+        AlwaysTrue
+      elsif current.empty?
+        Impossible
+      elsif count(current) >= minimum_size
+        Arel::Nodes::Grouping.new grasp(current).inject(:and)
       else
         reduce!
         resolve!
       end
     end
+
+    def grasp(subset)
+      subset.map do |k, v|
+        case v
+        when Array
+          table[k].in v
+        else
+          table[k].eq v
+        end
+      end
+    end
+
+    def count(subset)
+      constraints = grasp subset
+
+      select_manager.constraints.each do |constraint|
+        if self == constraint
+          next
+        end
+        if constraint.is_a? String
+          constraint = Arel::Nodes::Grouping.new constraint
+        end
+        constraints << constraint
+      end
+
+      relation = constraints.inject(nil) do |memo, constraint|
+        if memo
+          memo.and(constraint)
+        else
+          constraint
+        end
+      end
+
+      sql = table.dup.project('COUNT(*)').where(relation).to_sql
+      select_manager.engine.connection.select_value(sql).to_i
+    end
   end
 end

data/lib/cohort_analysis/version.rb

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

data/lib/cohort_analysis.rb

@@ -1,26 +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
+require 'cohort_analysis/arel_select_manager_instance_methods'
+Arel::SelectManager.send :include, CohortAnalysis::ArelSelectManagerInstanceMethods
+
+require 'cohort_analysis/arel_table_instance_methods'
+Arel::Table.send :include, CohortAnalysis::ArelTableInstanceMethods
+
+require 'cohort_analysis/arel_visitors_visitor_instance_methods'
 Arel::Visitors::Visitor.send :include, CohortAnalysis::ArelVisitorsVisitorInstanceMethods
+
+if defined?(ActiveRecord)
+  require 'cohort_analysis/active_record_base_class_methods'
+  ActiveRecord::Base.extend CohortAnalysis::ActiveRecordBaseClassMethods
+
+  require 'cohort_analysis/active_record_relation_instance_methods'
+  ActiveRecord::Relation.send :include, CohortAnalysis::ActiveRecordRelationInstanceMethods
+end

data/test/helper.rb

@@ -9,20 +9,65 @@ 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 'active_record'
+require 'active_record_inline_schema'
+
 require 'cohort_analysis'
 
-if ::Bundler.definition.specs['ruby-debug19'].first or ::Bundler.definition.specs['ruby-debug'].first
+if ::Bundler.definition.specs['debugger'].first
+  require 'debugger'
+elsif ::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'
-)
+ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => ":memory:")
+
+Arel::Table.engine = ActiveRecord::Base
+
+# https://gist.github.com/1560208 - shared examples in minispec
+
+MiniTest::Spec.class_eval do
+  # start transaction
+  before do
+    # activerecord-3.2.3/lib/active_record/fixtures.rb
+    @fixture_connections = ActiveRecord::Base.connection_handler.connection_pools.values.map(&:connection)
+    @fixture_connections.each do |connection|
+      connection.increment_open_transactions
+      connection.transaction_joinable = false
+      connection.begin_db_transaction
+    end
+  end
+
+  # rollback
+  after do
+    @fixture_connections.each do |connection|
+      if connection.open_transactions != 0
+        connection.rollback_db_transaction
+        connection.decrement_open_transactions
+      end
+    end
+    @fixture_connections.clear
+    ActiveRecord::Base.clear_active_connections!
+  end
+
+  def self.shared_examples
+    @shared_examples ||= {}
+  end
+end
+
+module MiniTest::Spec::SharedExamples
+  def shared_examples_for(desc, &block)
+    MiniTest::Spec.shared_examples[desc] = block
+  end
+
+  def it_behaves_like(desc)
+    self.instance_eval do
+      MiniTest::Spec.shared_examples[desc].call
+    end
+  end
+end
+
+Object.class_eval { include(MiniTest::Spec::SharedExamples) }