cohort_scope 0.0.1

data/.document

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

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

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.rdoc

@@ -0,0 +1,47 @@
+= cohort_scope
+
+Provides cohorts (in the form of ActiveRecord scopes) that dynamically widen until they contain a certain number of records.
+
+* <tt>big_cohort</tt> widens by finding the constraint that eliminates the most records and removing it.
+* <tt>strict_cohort</tt> widens by eliminating constraints in order.
+
+= Real-world use
+
+This has been at use at http://carbon.brighterplanet.com since April 2010, where it helps sift through climate data to come up with meaningful emissions calculations.
+
+= Quick start
+
+Let's pretend the U.S. Census provided information about birthday and favorite color:
+
+  class Citizen < ActiveRecord::Base
+    extend CohortScope
+    self.minimum_cohort_size = 1_000
+  end
+
+Now I need to run a calculation that ideally uses birthday and favorite color, but most importantly looks at a large cohort:
+
+  Citizen.big_cohort :birthdate => (Date.parse('1980-01-01')..Date.parse('1990-01-01')), :favorite_color => 'heliotrope'
+  # => [... a cohort of at least 1,000 records (otherwise it's empty),
+            where everybody's favorite color MAY be heliotrope
+            and everybody's birthday MAY be between 1980 and 1990
+            (at least one of those constraints will hold) ...]
+
+What if my calculation privileges favorite color? In other words, if you can't give me a cohort of minimum size within the birthday constraint, at least give me one where everybody loves heliotrope:
+
+  ordered_constraints = ActiveSupport::OrderedHash.new
+  ordered_constraints[:favorite_color] = 'heliotrope'
+  ordered_constraints[:birthdate] = (Date.parse('1980-01-01')..Date.parse('1990-01-01'))
+
+  Citizen.strict_cohort favorite_color_matters_most
+  # => [... a cohort of at least 1,000 records (otherwise it's empty),
+            where everybody's favorite color IS heliotrope
+            and everybody's birthday MAY be between 1980 and 1990 ...]
+
+= Wishlist
+
+* support for ruby 1.9's implicitly ordered hashes
+* support for constraining on <tt>IS NULL</tt> or <tt>IS NOT NULL</tt>
+
+== Copyright
+
+Copyright (c) 2010 Seamus Abshere and Andy Rossmeissl. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "cohort_scope"
+    gem.summary = %Q{Provides cohorts (in the form of ActiveRecord scopes) that dynamically widen until they contain a certain number of records.}
+    gem.description = %Q{Provides big_cohort, which widens by finding the constraint that eliminates the most records and removing it. Also provides strict_cohort, which widens by eliminating constraints in order.}
+    gem.email = "seamus@abshere.net"
+    gem.homepage = "http://github.com/seamusabshere/cohort_scope"
+    gem.authors = ["Seamus Abshere", "Andy Rossmeissl"]
+    gem.add_dependency "activesupport", ">=3.0.0.beta2"
+    gem.add_dependency "activerecord", ">=3.0.0.beta2"
+    gem.add_development_dependency "shoulda", ">= 2.10.3"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "cohort_scope #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/cohort_scope.rb

@@ -0,0 +1,159 @@
+require 'active_support'
+require 'active_record'
+require 'active_support/core_ext/module/delegation'
+
+module ActiveRecord
+  module NamedScope
+    module ClassMethods
+      # Initialize a MassiveScope, which, when inspected, does not generate a huge string.
+      def massive_scoped(options = {}, &block)
+        if options.present?
+          MassiveScope.init(self, options, &block)
+        else
+          raise "MassiveScopes should be created with options"
+        end
+      end
+    end
+    class MassiveScope < Scope
+      # Don't try to output a massive string.
+      def inspect
+        "<Massive scope: #{count} members>"
+      end
+      # Don't try to put everything into json.
+      def to_json(*args)
+        { :members => count }.to_json
+      end
+    end
+  end
+end
+
+module CohortScope
+  def self.extended(base)
+    base.class_eval do
+      cattr_accessor :minimum_cohort_size, :instance_writer => false
+    end
+  end
+
+  # Find the biggest scope possible by removing constraints <b>in any order</b>.
+  # Returns an empty scope if it can't meet the minimum scope size.
+  def big_cohort(constraints)
+    raise ArgumentError, "You can't give a big_cohort an OrderedHash; do you want strict_cohort?" if constraints.is_a?(ActiveSupport::OrderedHash)
+    _cohort_massive_scope constraints
+  end
+
+  # Find the first acceptable scope by removing constraints <b>in strict order</b>, starting with the last constraint.
+  # Returns an empty scope if it can't meet the minimum scope size.
+  #
+  # <tt>constraints</tt> must be an <tt>ActiveSupport::OrderedHash</tt> (no support for ruby 1.9's natively ordered hashes yet).
+  #
+  # Note that the first constraint is implicitly required.
+  #
+  # Take this example, where favorite color is considered to be "more important" than birthdate:
+  #
+  #   ordered_constraints = ActiveSupport::OrderedHash.new
+  #   ordered_constraints[:favorite_color] = 'heliotrope'
+  #   ordered_constraints[:birthdate] = '1999-01-01'
+  #   Citizen.strict_cohort(ordered_constraints) #=> [...]
+  #
+  # If the original constraints don't meet the minimum scope size, then the only constraint that can be removed is birthdate.
+  # In other words, this would never return a scope that was constrained on birthdate but not on favorite_color.
+  def strict_cohort(constraints)
+    raise ArgumentError, "You need to give strict_cohort an OrderedHash" unless constraints.is_a?(ActiveSupport::OrderedHash)
+    _cohort_massive_scope constraints
+  end
+
+  protected
+
+  # Recursively look for a scope that meets the constraints and is at least <tt>minimum_cohort_size</tt>.
+  def _cohort_massive_scope(constraints)
+    raise RuntimeError, "You need to set #{name}.minimum_cohort_size = X" unless minimum_cohort_size.present?
+    
+    if constraints.values.none? # failing base case
+      return massive_scoped(:conditions => 'false')
+    end
+    
+    this_hash = _cohort_constraints constraints
+    this_count = scoped(this_hash).count
+    
+    if this_count >= minimum_cohort_size # successful base case
+      massive_scoped this_hash
+    else
+      _cohort_massive_scope _cohort_reduce_constraints(constraints)
+    end
+  end
+  
+  # Sanitize constraints by
+  # * removing nil constraints (so constraints like "X IS NULL" are impossible, sorry)
+  # * converting ActiveRecord::Base objects into integer foreign key constraints
+  def _cohort_constraints(constraints)
+    new_hash = constraints.is_a?(ActiveSupport::OrderedHash) ? ActiveSupport::OrderedHash.new : Hash.new
+    conditions = constraints.inject(new_hash) do |memo, tuple|
+      k, v = tuple
+      if v.kind_of?(ActiveRecord::Base)
+        condition = { _cohort_association_primary_key(k) => v.to_param }
+      elsif !v.nil?
+        condition = { k => v }
+      end
+      memo.merge! condition if condition.is_a? Hash
+      memo
+    end
+    { :conditions => conditions }
+  end
+  
+  # Convert constraints that are provided as ActiveRecord::Base objects into their corresponding integer primary keys.
+  #
+  # Only works for <tt>belongs_to</tt> relationships.
+  #
+  # For example, :car => <#Car> might get translated into :car_id => 44.
+  def _cohort_association_primary_key(name)
+    @_cohort_association_primary_keys ||= {}
+    return @_cohort_association_primary_keys[name] if @_cohort_association_primary_keys.has_key? name
+    a = reflect_on_association name
+    raise "can't use cohort scope on :through associations (#{self.name} #{name})" if a.options.has_key? :through
+    if !a.primary_key_name.blank?
+      @_cohort_association_primary_keys[name] = a.primary_key_name
+    else
+      raise "we need some other way to find primary key"
+    end
+  end
+  
+  # Choose how to reduce constraints based on whether we're looking for a big cohort or a strict cohort.
+  def _cohort_reduce_constraints(constraints)
+    case constraints
+    when ActiveSupport::OrderedHash
+      _cohort_reduce_constraints_in_order constraints
+    when Hash
+      _cohort_reduce_constraints_seeking_maximum_count constraints
+    else
+      raise "what did you pass me? #{constraints}"
+    end
+  end
+  
+  # (Used by <tt>big_cohort</tt>)
+  #
+  # Reduce constraints by removing them one by one and counting the results.
+  #
+  # The constraint whose removal leads to the highest record count is removed from the overall constraint set.
+  def _cohort_reduce_constraints_seeking_maximum_count(constraints)
+    highest_count_after_removal = nil
+    losing_key = nil
+    constraints.keys.each do |key|
+      test_constraints = constraints.except(key)
+      count_after_removal = scoped(_cohort_constraints(test_constraints)).count
+      if highest_count_after_removal.nil? or count_after_removal > highest_count_after_removal
+        highest_count_after_removal = count_after_removal
+        losing_key = key
+      end
+    end
+    constraints.except losing_key
+  end
+
+  # (Used by <tt>strict_cohort</tt>)
+  #
+  # Reduce constraints by removing the least important one.
+  def _cohort_reduce_constraints_in_order(constraints)
+    reduced_constraints = constraints.dup
+    reduced_constraints.delete constraints.keys.last
+    reduced_constraints
+  end
+end

data/test/helper.rb

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'ruby-debug'
+require 'logger'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'cohort_scope'
+
+class Test::Unit::TestCase
+end
+
+$logger = Logger.new STDOUT #'test/test.log'
+ActiveSupport::Notifications.subscribe do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  $logger.debug "#{event.payload[:name]} (#{event.duration}) #{event.payload[:sql]}"
+end
+
+ActiveRecord::Base.establish_connection(
+  'adapter' => 'mysql',
+  'database' => 'cohort_scope_test',
+  'username' => 'root',
+  'password' => ''
+)
+
+ActiveRecord::Schema.define(:version => 20090819143429) do
+  create_table 'citizens', :force => true do |t|
+    t.date 'birthdate'
+    t.string 'favorite_color'
+    t.integer 'teeth'
+  end
+end
+
+class Citizen < ActiveRecord::Base
+  extend CohortScope
+  self.minimum_cohort_size = 3
+  validates_presence_of :birthdate
+end
+
+[
+  [ '1982-09-29', 'blue', 31 ],
+  [ '1954-12-20', 'heliotrope', 32 ],
+  [ '1983-10-28', 'green', 24 ],
+  [ '1984-02-14', 'firetruck red', 27 ],
+  [ '1955-07-21', 'blue', 27 ],
+  [ '1983-06-08', 'purple', 42 ],
+  [ '1982-04-27', 'black', 24 ],
+  [ '1984-07-16', 'blue', 29 ],
+  [ '1975-02-18', 'green', 18 ],
+  [ '1988-02-01', nil, 31 ],
+  [ '1985-03-02', nil, 27 ],
+  [ '1982-05-01', nil, 28 ]
+].each do |birthdate, favorite_color, teeth|
+  Citizen.create! :birthdate => birthdate, :favorite_color => favorite_color, :teeth => teeth
+end

data/test/test_cohort_scope.rb

@@ -0,0 +1,70 @@
+require 'helper'
+
+class TestCohortScope < Test::Unit::TestCase
+  def setup
+    Citizen.minimum_cohort_size = 3
+    @date_range = (Date.parse('1980-01-01')..Date.parse('1990-01-01'))
+  end
+
+  should "raise if no minimum_cohort_size is specified" do
+    Citizen.minimum_cohort_size = nil
+    assert_raises(RuntimeError) {
+      cohort = Citizen.big_cohort Hash.new
+    }
+    assert_raises(RuntimeError) {
+      cohort = Citizen.strict_cohort ActiveSupport::OrderedHash.new
+    }
+  end
+
+  context "big_cohort" do
+    should "return an empty cohort if it can't find one that meets size requirements" do
+      cohort = Citizen.big_cohort :favorite_color => 'heliotrope'
+      assert_equal 0, cohort.count
+    end
+  
+    should "seek a cohort of maximum size" do
+      cohort = Citizen.big_cohort :birthdate => @date_range, :favorite_color => 'heliotrope'
+      assert_equal 9, cohort.count
+      assert cohort.any? { |m| m.favorite_color != 'heliotrope' }
+      assert cohort.all? { |m| @date_range.include? m.birthdate }
+    end
+    
+    should "raise if an OrderedHash is given to big_cohort" do
+      assert_raises(ArgumentError) {
+        cohort = Citizen.big_cohort ActiveSupport::OrderedHash.new
+      }
+    end
+  end
+  
+  context "strict_cohort" do
+    should "raise if a non-OrderedHash is given to strict_cohort" do
+      assert_raises(ArgumentError) {
+        cohort = Citizen.strict_cohort Hash.new
+      }
+    end
+  
+    should "return an empty (strict) cohort if it can't find one that meets size requirements" do
+      ordered_attributes = ActiveSupport::OrderedHash.new
+      ordered_attributes[:favorite_color] = 'heliotrope'
+    
+      cohort = Citizen.strict_cohort ordered_attributes
+      assert_equal 0, cohort.count
+    end
+  
+    should "seek a cohort by discarding attributes in order" do
+      favorite_color_matters_most = ActiveSupport::OrderedHash.new
+      favorite_color_matters_most[:favorite_color] = 'heliotrope'
+      favorite_color_matters_most[:birthdate] = @date_range
+    
+      birthdate_matters_most = ActiveSupport::OrderedHash.new
+      birthdate_matters_most[:birthdate] = @date_range
+      birthdate_matters_most[:favorite_color] = 'heliotrope'
+    
+      cohort = Citizen.strict_cohort favorite_color_matters_most
+      assert_equal 0, cohort.count
+    
+      cohort = Citizen.strict_cohort birthdate_matters_most
+      assert_equal 9, cohort.count
+    end
+  end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification 
+name: cohort_scope
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Seamus Abshere
+- Andy Rossmeissl
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-07 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        - 0
+        - beta2
+        version: 3.0.0.beta2
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        - 0
+        - beta2
+        version: 3.0.0.beta2
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 10
+        - 3
+        version: 2.10.3
+  type: :development
+  version_requirements: *id003
+description: Provides big_cohort, which widens by finding the constraint that eliminates the most records and removing it. Also provides strict_cohort, which widens by eliminating constraints in order.
+email: seamus@abshere.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/cohort_scope.rb
+- test/helper.rb
+- test/test_cohort_scope.rb
+has_rdoc: true
+homepage: http://github.com/seamusabshere/cohort_scope
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Provides cohorts (in the form of ActiveRecord scopes) that dynamically widen until they contain a certain number of records.
+test_files: 
+- test/helper.rb
+- test/test_cohort_scope.rb