sniff 0.0.2

data/README.markdown

@@ -0,0 +1,73 @@
+# sniff
+Testing environment for Brighter Planet Climate Middleware emission calculation gems.
+
+This gem provides:
+ * Sample climate data, representative of data found on http://data.brighterplanet.com
+ * References to gems needed by each emitter gem  
+
+# Usage
+Within an emitter gem's test setup, you can:
+    require 'sniff'
+    
+    Sniff.init '/path/to/emitter_project'
+
+# How to contribute
+Typical contributions will include updates to test data.
+
+1. Fork the project.
+1. Make your feature addition or bug fix.
+1. Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+1. Send me a pull request. Bonus points for topic branches.
+
+# Local Gems
+Sniff depends on several gems, some of which are developed by Brighter Planet.  You can tell Sniff or any of the carbon gems to use your local repos in lieu of installed rubygems through the following steps:
+
+
+Paste the following functions into your ~/.bash_profile
+    function mod_devgem() {
+      var="LOCAL_`echo $2 | tr 'a-z' 'A-Z'`"
+      
+      if [ "$1" == "disable" ]
+      then
+        echo "unset $var"
+        unset $var
+      else
+        dir=${3:-"~/$2"}
+        echo "export $var=$dir"
+        export $var=$dir
+      fi
+    }
+    
+    function devgems () {
+      # Usage: devgems [enable|disable] [gemname]
+      cmd=${1:-"enable"}
+      if [ -z $2 ]
+      then
+        mod_devgem $cmd characterizable
+        mod_devgem $cmd cohort_scope
+        mod_devgem $cmd falls_back_on
+        mod_devgem $cmd leap
+        mod_devgem $cmd loose_tight_dictionary
+        mod_devgem $cmd sniff
+        mod_devgem $cmd data_miner
+      else
+        mod_devgem $cmd $2
+      fi
+    }
+
+To enable all local gems, run `devgems enable`
+To turn off devgems, run `devgems disable`
+To turn off a specific gem, run `devgems disable leap`
+To turn on a specific gem, run `devgems enable leap`
+
+Typical development process:
+    cd ~
+    git clone http://github.com/rossmeissl/leap.git
+    cd leap
+    <do some development on leap>
+    cd ~/sniff
+    devgems enable leap
+    rake gemspec
+    rm -f Gemfile.lock
+    bundle install
+    <run tests, e.g. `spec spec`>

data/lib/sniff/active_record_ext.rb

@@ -0,0 +1,12 @@
+require 'active_record'
+require 'common_name'
+require 'falls_back_on'
+
+ActiveRecord::Base.class_eval do
+  extend FallsBackOn
+
+  def self._common_name
+    name.underscore
+  end
+  include CommonName
+end

data/lib/sniff/conversions_ext.rb

@@ -0,0 +1,45 @@
+require 'conversions'
+Conversions.register(:miles, :nautical_miles, 0.868976242)
+Conversions.register(:kilometres, :nautical_miles, 0.539956803)
+Conversions.register(:pounds_per_gallon, :kilograms_per_litre, 0.119826427)
+Conversions.register(:inches, :meters, 0.0254)
+Conversions.register(:kilowatt_hours, :watt_hours, 1_000.0)
+Conversions.register(:kilowatt_hours, :btus, 3_412.14163) # obsolete?
+Conversions.register(:watt_hours, :btus, 3.4121414799) # obsolete?
+Conversions.register(:watt_hours, :joules, 3_600.0)
+Conversions.register(:kilowatt_hours, :joules, 3_600_000.0)
+
+# Conversions.register(:btus, :gallons_of_kerosene, 0.000007419521097)
+Conversions.register(:joules, :litres_of_kerosene, 1.0 / (135_000.0 * 3.78541178 * 1_055.05585)) # should only be used for RECS 2005
+
+# Conversions.register(:btus, :gallons_of_propane, 0.000010471204188)
+Conversions.register(:joules, :litres_of_propane, 1.0 / (91_333.0 * 3.78541178 * 1_055.05585)) # should only be used for RECS 2005
+
+# Conversions.register(:btus, :therms, 0.000010002388121)
+Conversions.register(:therms, :joules, 105_505_585.0) # should only be used for RECS 2005
+
+# Conversions.register(:btus, :gallons_of_fuel_oil, 0.0000072007637183)
+Conversions.register(:joules, :litres_of_fuel_oil, 1.0 / (138_690.0 * 3.78541178 * 1_055.05585)) # should only be used for RECS 2005
+
+# Conversions.register(:tons_of_coal, :btus, 20_169_000.0)
+Conversions.register(:joules, :kilograms_of_coal, 1.0 / (22_342_000.0 * 0.00110231131 * 1_055.05585)) # should only be used for RECS 2005
+
+Conversions.register(:kilograms, :lbs, 2.20462262)
+Conversions.register(:kbtus, :btus, 1_000.0)
+Conversions.register(:square_feet, :square_metres, 0.09290304)
+Conversions.register(:pounds_per_square_foot, :kilograms_per_square_metre, 4.88242764)
+Conversions.register(:kilograms_per_kilowatt_hour, :kilograms_per_megawatt_hour, 1_000.0)
+Conversions.register(:btus, :joules, 1_055.05585)
+Conversions.register(:kbtus, :joules, 1_000.0 * 1_055.05585)
+Conversions.register(:cords, :joules, 2.11011171e10)
+
+Conversions.register(:gallons_per_mile, :litres_per_kilometre, 2.35214583)
+Conversions.register(:pounds_per_mile, :kilograms_per_kilometre, 0.281849232)
+Conversions.register(:dollars, :cents, 100)
+Conversions.register(:cubic_feet, :cubic_metres, 0.0283168466)
+# 1 (kilocalories per pound) = 9 224.14105 joules per kilogram
+Conversions.register :kilocalories_per_pound, :joules_per_kilogram, 9_224.14105
+# 1 (grams per kilocalories) = 2.39005736 × 10-7 kilograms per joules
+Conversions.register :grams_per_kilocalorie, :kilograms_per_joule, 2.39005736e-7
+# 1 joule = 0.000239005736 kilocalories
+Conversions.register :joules, :kilocalories, 0.000239005736

data/lib/sniff/database.rb

@@ -0,0 +1,157 @@
+require 'fileutils'
+require 'logger'
+
+module Sniff
+  class Database
+    class << self
+      def init(local_root, options = {})
+        environments = []
+        environments << really_init(local_root, options)
+
+        unless local_root == Sniff.root
+          environments << really_init(Sniff.root)
+        end
+
+        db_init local_root
+        environments.each { |e| e.populate_fixtures }
+      end
+
+      def really_init(root, options = {})
+        db = new root, options
+        db.init
+        db
+      end
+
+      def db_init(local_root)
+        db_path = File.join(local_root, 'db')
+        db_file_path = File.join(db_path, 'emitter_data.sqlite3')
+        FileUtils.mkdir_p db_path
+        db_drop db_file_path
+        connect db_file_path
+        db_create
+        load_all_schemas
+      end
+
+      def connect(db_file_path)
+        ActiveRecord::Base.establish_connection :adapter => 'sqlite3',
+          :database => db_file_path,
+          :pool => 5,
+          :timeout => 5000
+      end
+
+      def db_drop(db_file_path)
+        FileUtils.rm db_file_path if File.exists?(db_file_path)
+      end
+
+      def db_create
+        ActiveRecord::Base.connection
+      end
+
+      def define_schema(&blk)
+        @schemas = [] unless defined?(@schemas)
+        @schemas << blk
+      end
+
+      def schemas
+        @schemas
+      end
+
+      def load_all_schemas
+        orig_std_out = STDOUT.clone
+        STDOUT.reopen File.open(File.join('/tmp', 'schema_output'), 'w') 
+
+        ActiveRecord::Schema.define(:version => 1) do
+          ar_schema = self
+          Sniff::Database.schemas.each do |s|
+            ar_schema.instance_eval &s
+          end
+        end
+      ensure
+        STDOUT.reopen(orig_std_out)
+      end
+    end
+
+    attr_accessor :root, :lib_path, :schema_path, :fixtures_path,
+      :load_data, :fixtures, :logger
+
+    def initialize(root, options)
+      self.root = root
+      self.lib_path = File.join(root, 'lib', 'test_support')
+      self.load_data = options[:load_data]
+      self.schema_path = options[:schema_path]
+      self.fixtures_path = options[:fixtures_path]
+      self.logger = Logger.new options[:logdev]
+    end
+
+    def log(str)
+      logger.log str
+    end
+
+    def load_data?
+      @load_data = true if @load_data.nil?
+      @load_data
+    end
+
+    def schema_path
+      @schema_path ||= File.join(lib_path, 'db', 'schema.rb')
+    end
+
+    def fixtures_path
+      @fixtures_path ||= File.join(lib_path, 'db', 'fixtures')
+    end
+
+    def fixtures
+      @fixtures ||= []
+    end
+
+    def init
+      load_models
+      load_supporting_libs
+      read_schema
+      read_fixtures if load_data?
+    end
+
+    def read_schema
+      log "Reading schema #{schema_path}"
+      load(schema_path)
+    end
+
+    def read_fixtures
+      require 'active_record/fixtures'
+      log "Reading fixtures from #{fixtures_path}/**/*.{yml,csv}"
+
+      Dir["#{fixtures_path}/**/*.{yml,csv}"].each do |fixture_file|
+        fixtures << fixture_file
+      end
+    end
+
+    def populate_fixtures
+      fixtures.each do |fixture_file|
+        log "Loading fixture #{fixture_file}"
+        Fixtures.create_fixtures(fixtures_path, fixture_file[(fixtures_path.size + 1)..-5])
+      end
+    end
+
+    def load_supporting_libs
+      $:.unshift File.join(root, 'lib')
+      Dir[File.join(root, 'lib', 'test_support', '*.rb')].each do |lib|
+        log "Loading #{lib}"
+        require lib
+      end
+    end
+
+    def load_models
+      require 'falls_back_on'
+      require 'falls_back_on/active_record_ext'
+
+      require 'cohort_scope'
+      require 'leap'
+#      require 'data_miner'
+
+      Dir["#{lib_path}/data_models/**/*.rb"].each do |lib|
+        log "Loading model #{lib}"
+        require lib
+      end
+    end
+  end
+end

data/lib/sniff/emitter.rb

@@ -0,0 +1,65 @@
+require 'summary_judgement'
+require 'fast_timestamp'
+require 'common_name'
+require 'falls_back_on'
+
+module Sniff
+  module Emitter
+    def self.included(target)
+      target.send :extend, ClassMethods
+      target.send :extend, SummaryJudgement
+      target.send :extend, FastTimestamp
+      target.send :include, Characterizable
+    end
+    
+    def parent_class
+      Emitter
+    end
+          
+    def visible_effective_characteristics
+      characteristics.effective.reject { |_, c| c.hidden? }
+    end
+      
+    def retired?
+      has_attribute?(:retirement) and retirement
+    end
+    
+    def pattern?
+      self.class.pattern?
+    end
+    
+    module ClassMethods
+      def from_params_hash(params = Hash.new)
+        resolved_params = Hash.new
+        instance = new
+        associations = reflect_on_all_associations
+        params.each do |k, v|
+          next if v.blank?
+          c = characteristics[k.to_sym]
+          next if c.nil?
+          if associations.map(&:name).include?(c.name.to_sym)
+            association = associations.find { |a| a.name == c.name.to_sym }
+            klass = association.options[:class_name] || association.name.to_s.pluralize.classify
+            klass = klass.constantize
+            if v.is_a?(Hash)
+              # h[:origin_airport][:iata_code] => 'MIA'
+              attr_name, attr_value = v.to_a.flatten[0, 2]
+              resolved_params[k] = klass.send "find_by_#{attr_name}", attr_value
+            else
+              # h[:origin_airport] => 'MIA'
+              resolved_params[k] = klass.send "find_by_#{k}", v
+            end
+          else
+            resolved_params[k] = v
+          end
+        end
+        new resolved_params
+      end
+      
+      def pattern?
+        common_name.ends_with? 'pattern'
+      end
+    end
+  end
+end
+

data/lib/sniff/tasks.rb

@@ -0,0 +1,14 @@
+task :environment do
+  ENV['SCHEMA'] = File.join Sniff.root, 'db', 'schema.rb'
+  ENV['FIXTURES_PATH'] = File.join Sniff.root, 'test', 'fixtures'
+end
+
+task :console do
+  require 'sniff'
+  cwd = Dir.pwd
+  Sniff.init cwd
+
+  require 'irb'
+  ARGV.clear
+  IRB.start
+end

data/lib/sniff/timeframe.rb

@@ -0,0 +1,251 @@
+# Encapsulates a timeframe between two dates. The dates provided to the class are always until the last date. That means
+# that the last date is excluded.
+#
+#   # from 2007-10-01 00:00:00.000 to 2007-10-31 23:59:59.999
+#   Timeframe.new(Date(2007,10,1), Date(2007,11,1))
+#   # and holds 31 days
+#   Timeframe.new(Date(2007,10,1), Date(2007,11,1)).days #=> 31
+
+module Sniff
+  class Timeframe
+    attr_accessor :from, :to
+
+    # Creates a new instance of Timeframe. You can either pass a start and end Date or a Hash with named arguments,
+    # with the following options:
+    #
+    #   <tt>:month</tt>: Start date becomes the first day of this month, and the end date becomes the first day of
+    #   the next month. If no <tt>:year</tt> is specified, the current year is used.
+    #   <tt>:year</tt>: Start date becomes the first day of this year, and the end date becomes the first day of the
+    #   next year.
+    #
+    # Examples:
+    #
+    #   Timeframe.new Date.new(2007, 2, 1), Date.new(2007, 4, 1) # February and March
+    #   Timeframe.new :year => 2004 # The year 2004
+    #   Timeframe.new :month => 4 # April
+    #   Timeframe.new :year => 2004, :month => 2 # Feburary 2004
+    def initialize(*args)
+      options = args.extract_options!
+
+      if month = options[:month]
+        month = Date.parse(month).month if month.is_a? String
+        year = options[:year] || Time.zone.today.year
+        from = Date.new(year, month, 1)
+        to   = from.next_month
+      elsif year = options[:year]
+        from = Date.new(year, 1, 1)
+        to   = Date.new(year+1, 1, 1)
+      end
+
+      from ||= args.shift.andand.to_date
+      to ||= args.shift.andand.to_date
+
+      raise ArgumentError, "Please supply a start and end date, `#{args.map(&:inspect).to_sentence}' is not enough" if from.nil? or to.nil?
+      raise ArgumentError, "Start date #{from} should be earlier than end date #{to}" if from > to
+      raise ArgumentError, 'Timeframes that cross year boundaries are dangerous' unless options[:skip_year_boundary_crossing_check] or from.year == to.yesterday.year or from == to
+
+      @from, @to = from, to
+    end
+    
+    def inspect
+      "<Timeframe(#{object_id}) #{days} days starting #{from} ending #{to}>"
+    end
+
+    # The number of days in the timeframe
+    #
+    #   Timeframe.new(Date.new(2007, 11, 1), Date.new(2007, 12, 1)).days #=> 30
+    #   Timeframe.new(:month => 1).days #=> 31
+    #   Timeframe.new(:year => 2004).days #=> 366
+    def days
+      (to - from).to_i
+    end
+    
+    # Returns a string representation of the timeframe
+    def to_s
+      if [from.day, from.month, to.day, to.month].uniq == [1]
+        from.year.to_s
+      elsif from.day == 1 and to.day == 1 and to.month - from.month == 1
+        "#{Date::MONTHNAMES[from.month]} #{from.year}"
+      else
+        "the period from #{from.strftime('%d %B')} to #{to.yesterday.strftime('%d %B %Y')}"
+      end
+    end
+
+    # Returns true when the date is included in this Timeframe
+    def include?(obj)
+      # puts "checking to see if #{date} is between #{from} and #{to}" if Emitter::DEBUG
+      case obj
+      when Date
+        (from...to).include?(obj)
+      when Time
+        # (from...to).include?(obj.to_date)
+        raise "this wasn't previously supported, but it could be"
+      when Timeframe
+        from <= obj.from and to >= obj.to
+      end
+    end
+    
+    def proper_include?(other_timeframe)
+      raise ArgumentError, 'Proper inclusion only makes sense when testing other Timeframes' unless other_timeframe.is_a? Timeframe
+      (from < other_timeframe.from) and (to > other_timeframe.to)
+    end
+    
+    # Returns true when this timeframe is equal to the other timeframe
+    def ==(other)
+      # puts "checking to see if #{self} is equal to #{other}" if Emitter::DEBUG
+      return false unless other.is_a?(Timeframe)
+      from == other.from and to == other.to
+    end
+    alias :eql? :==
+      
+    # Calculates a hash value for the Timeframe, used for equality checking and Hash lookups.
+    # This needs to be an integer or else it won't use #eql?
+    def hash
+      from.hash + to.hash
+    end
+    alias :to_param :hash
+    
+    # Returns an array of month-long subtimeframes
+    # TODO: rename to month_subtimeframes
+    def months
+      raise ArgumentError, "Please only provide whole-month timeframes to Timeframe#months" unless from.day == 1 and to.day == 1
+      raise ArgumentError, 'Timeframes that cross year boundaries are dangerous during Timeframe#months' unless from.year == to.yesterday.year
+      year = from.year # therefore this only works in the from year
+      (from.month..to.yesterday.month).map { |m| Timeframe.new :month => m, :year => year }
+    end
+    
+    # Returns the relevant year as a Timeframe
+    def year
+      raise ArgumentError, 'Timeframes that cross year boundaries are dangerous during Timeframe#year' unless from.year == to.yesterday.year
+      Timeframe.new :year => from.year
+    end
+    
+    # multiyear safe
+    def month_subtimeframes
+      (from.year..to.yesterday.year).map do |year|
+        (1..12).map do |month|
+          Timeframe.new(:year => year, :month => month) & self
+        end
+      end.flatten.compact
+    end
+    
+    # multiyear safe
+    def full_month_subtimeframes
+      month_subtimeframes.map { |st| Timeframe.new(:year => st.from.year, :month => st.from.month) }
+    end
+    
+    # multiyear safe
+    def year_subtimeframes
+      (from.year..to.yesterday.year).map do |year|
+        Timeframe.new(:year => year) & self
+      end
+    end
+    
+    # multiyear safe
+    def full_year_subtimeframes
+      (from.year..to.yesterday.year).map do |year|
+        Timeframe.new :year => year
+      end
+    end
+    
+    # multiyear safe  
+    def ending_no_later_than(date)
+      if to < date
+        self
+      elsif from >= date
+        nil
+      else
+        Timeframe.multiyear from, date
+      end
+    end
+      
+    # Returns a timeframe representing the intersection of the timeframes
+    def &(other_timeframe)
+      this_timeframe = self
+      if other_timeframe == this_timeframe
+        this_timeframe
+      elsif this_timeframe.from > other_timeframe.from and this_timeframe.to < other_timeframe.to
+        this_timeframe
+      elsif other_timeframe.from > this_timeframe.from and other_timeframe.to < this_timeframe.to
+        other_timeframe
+      elsif this_timeframe.from >= other_timeframe.to or this_timeframe.to <= other_timeframe.from
+        nil
+      else
+        Timeframe.new [this_timeframe.from, other_timeframe.from].max, [this_timeframe.to, other_timeframe.to].min, :skip_year_boundary_crossing_check => true
+      end
+    end
+    
+    # Returns a fraction of another Timeframe
+    def /(other_timeframe)
+      raise ArgumentError, 'You can only divide a Timeframe by another Timeframe' unless other_timeframe.is_a? Timeframe
+      self.days.to_f / other_timeframe.days.to_f
+    end
+    
+    def crop(container)
+      raise ArgumentError, 'You can only crop a timeframe by another timeframe' unless container.is_a? Timeframe
+      self.class.new [from, container.from].max, [to, container.to].min
+    end
+    
+    def gaps_left_by(*timeframes)
+      # remove extraneous timeframes
+      timeframes.reject! { |t| t.to <= from }
+      timeframes.reject! { |t| t.from >= to }
+      
+      # crop timeframes
+      timeframes.map! { |t| t.crop self }
+      
+      # remove proper subtimeframes
+      timeframes.reject! { |t| timeframes.detect { |u| u.proper_include? t } }
+      
+      # escape
+      return [self] if  timeframes.empty?
+
+      timeframes.sort! { |x, y| x.from <=> y.from }
+      
+      timeframes.collect(&:to).unshift(from).ykk(timeframes.collect(&:from).push(to)) do |gap|
+        Timeframe.new(*gap) if gap[1] > gap[0]
+      end.compact
+    end
+    
+    def covered_by?(*timeframes)
+      gaps_left_by(*timeframes).empty?
+    end
+    
+    def last_year
+      self.class.new((from - 1.year), (to - 1.year))
+    end
+    
+    class << self
+      def this_year
+        new :year => Time.now.year
+      end
+      
+      def constrained_new(from, to, constraint)
+        raise ArgumentError, 'Need Date, Date, Timeframe as args' unless from.is_a? Date and to.is_a? Date and constraint.is_a? Timeframe
+        raise ArgumentError, "Start date #{from} should be earlier than end date #{to}" if from > to
+        if to <= constraint.from or from >= constraint.to
+          new constraint.from, constraint.from
+        elsif from.year == to.yesterday.year
+          new(from, to) & constraint
+        elsif from.year < constraint.from.year and constraint.from.year < to.yesterday.year
+          constraint
+        else
+          new [constraint.from, from].max, [constraint.to, to].min
+        end
+      end
+      
+      def multiyear(from, to)
+        from = Date.parse(from) if from.is_a?(String)
+        to = Date.parse(to) if to.is_a?(String)
+        new from, to, :skip_year_boundary_crossing_check => true
+      end
+      
+      # create a multiyear timeframe +/- number of years around today
+      def mid(number)
+        from = Time.zone.today - number.years
+        to = Time.zone.today + number.years
+        multiyear from, to
+      end
+    end
+  end
+end

data/lib/sniff.rb

@@ -0,0 +1,31 @@
+module Sniff
+  extend self
+
+  def root 
+    File.join(File.dirname(__FILE__), '..')
+  end
+
+  def init(local_root, options = {})
+    require 'active_record'
+    require 'sqlite3'
+
+    load_plugins
+
+    Sniff::Database.init local_root, options
+  end
+
+  def load_plugins
+    Dir[File.join(Sniff.root, 'vendor', '**', 'init.rb')].each do |pluginit|
+      $:.unshift File.join(File.dirname(pluginit), 'lib')
+      load pluginit
+    end
+  end
+end
+
+require 'characterizable'
+$:.unshift File.dirname(__FILE__)
+require 'sniff/active_record_ext'
+require 'sniff/database'
+require 'sniff/emitter'
+require 'sniff/conversions_ext'
+require 'sniff/timeframe'

data/lib/test_support/data_models/census_division.rb

@@ -0,0 +1,9 @@
+class CensusDivision < ActiveRecord::Base
+  set_primary_key :number
+  
+  belongs_to :census_region, :foreign_key => 'census_region_number'
+  has_many :states, :foreign_key => 'census_division_number'
+  has_many :zip_codes, :through => :states
+  has_many :climate_divisions, :through => :states
+  has_many :residential_energy_consumption_survey_responses, :foreign_key => 'census_division_number'
+end

data/lib/test_support/data_models/census_region.rb

@@ -0,0 +1,9 @@
+class CensusRegion < ActiveRecord::Base
+  set_primary_key :number
+  
+  has_many :census_divisions, :foreign_key => 'census_region_number'
+  has_many :states, :through => :census_divisions
+  # has_many :climate_divisions, :through => :census_divisions
+  # has_many :zip_codes, :through => :census_divisions
+  has_many :residential_energy_consumption_survey_responses, :foreign_key => 'census_region_number'
+end

data/lib/test_support/data_models/climate_division.rb

@@ -0,0 +1,8 @@
+class ClimateDivision < ActiveRecord::Base
+  set_primary_key :name
+  
+  has_many :zip_codes, :foreign_key => 'climate_division_name'
+  belongs_to :state, :foreign_key => 'state_postal_abbreviation'
+  
+  RADIUS = 750
+end

data/lib/test_support/data_models/country.rb

@@ -0,0 +1,9 @@
+class Country < ActiveRecord::Base
+  set_primary_key :iso_3166_code
+  
+  class << self
+    def united_states
+      find_by_iso_3166_code('US')
+    end
+  end
+end