lodging 0.0.8 → 0.0.9

data/features/lodging_committees.feature

@@ -7,9 +7,9 @@ Feature: Lodging Committee Calculations
     Then the committee should have used quorum "default"
     And the conclusion of the committee should be "1"
 
-  Scenario: Nights committee from default
+  Scenario: Duration committee from default
     Given a lodging emitter
-    When the "nights" committee is calculated
+    When the "duration" committee is calculated
     Then the committee should have used quorum "default"
     And the conclusion of the committee should be "1"
 

data/features/lodging_emissions.feature

@@ -11,8 +11,8 @@ Feature: Lodging Emissions Calculations
     When emissions are calculated
     Then the emission value should be within "0.1" kgs of "68.7"
 
-  Scenario: Calculations starting from nights
-    Given a lodging has "nights" of "5"
+  Scenario: Calculations starting from duration
+    Given a lodging has "duration" of "5"
     When emissions are calculated
     Then the emission value should be within "0.1" kgs of "68.7"
 
@@ -31,23 +31,23 @@ Feature: Lodging Emissions Calculations
     When emissions are calculated
     Then the emission value should be within "0.1" kgs of "5.8"
 
-  Scenario: Calculations starting from rooms, nights, and lodging class
+  Scenario: Calculations starting from rooms, duration, and lodging class
     Given a lodging has "rooms" of "2"
-    And it has "nights" of "2"
+    And it has "duration" of "2"
     And it has "lodging_class.name" of "Luxury Hotel"
     When emissions are calculated
     Then the emission value should be within "0.1" kgs of "110.0"
 
-  Scenario: Calculations starting from rooms, nights, and state
+  Scenario: Calculations starting from rooms, duration, and state
     Given a lodging has "rooms" of "2"
-    And it has "nights" of "2"
+    And it has "duration" of "2"
     And it has "state.postal_abbreviation" of "CA"
     When emissions are calculated
     Then the emission value should be within "0.1" kgs of "40.0"
 
-  Scenario: Calculations starting from rooms, nights, and zip code
+  Scenario: Calculations starting from rooms, duration, and zip code
     Given a lodging has "rooms" of "2"
-    And it has "nights" of "2"
+    And it has "duration" of "2"
     And it has "zip_code.name" of "94122"
     When emissions are calculated
     Then the emission value should be within "0.1" kgs of "23.3"

data/lib/lodging/carbon_model.rb

@@ -2,39 +2,66 @@
 # See LICENSE for details.
 # Contact Brighter Planet for dual-license arrangements.
 
-
+## Lodging carbon model
+# This model is used by [Brighter Planet](http://brighterplanet.com)'s carbon emission [web service](http://carbon.brighterplanet.com) to estimate the **greenhouse gas emissions of a lodging** (e.g. a hotel stay).
+#
+##### Calculations
+# The final estimate is the result of the **calculations** detailed below. These calculations are performed in reverse order, starting with the last calculation listed and finishing with the `emission` calculation. Each calculation is named according to the value it returns.
+#
+##### Methods
+# To accomodate varying client input, each calculation may have one or more **methods**. These are listed under each calculation in order from most to least preferred. Each method is named according to the values it requires. If any of these values is not available the method will be ignored. If all the methods for a calculation are ignored, the calculation will not return a value. "Default" methods do not require any values, and so a calculation with a default method will always return a value.
+#
+##### Standard compliance
+# Each method lists any established calculation standards with which it **complies**. When compliance with a standard is requested, all methods that do not comply with that standard are ignored. This means that any values a particular method requires will have been calculated using a compliant method, because those are the only methods available. If any value did not have a compliant method in its calculation then it would be undefined, and the current method would have been ignored.
+#
+##### Collaboration
+# Contributions to this carbon model are actively encouraged and warmly welcomed. This library includes a comprehensive test suite to ensure that your changes do not cause regressions. All changes should include test coverage for new functionality. Please see [sniff](http://github.com/brighterplanet/sniff#readme), our emitter testing framework, for more information.
 module BrighterPlanet
   module Lodging
     module CarbonModel
       def self.included(base)
         base.decide :emission, :with => :characteristics do
-          committee :emission do # returns kg CO2e
-            quorum 'from rooms, nights, and emission factor', :needs => [:rooms, :nights, :emission_factor] do |characteristics|
-              characteristics[:rooms] * characteristics[:nights] * characteristics[:emission_factor]
+          ### Emission calculation
+          # Returns the `emission` estimate (*kg CO<sub>2</sub>e*).
+          committee :emission do
+            #### Emission from rooms, duration, and emission factor
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Multiplies `rooms` by `duration` and the `emission factor` (*kg CO<sub>2</sub>e / room-night*) to give (*kg CO<sub>2</sub>e).
+            quorum 'from rooms, duration, and emission factor', :needs => [:rooms, :duration, :emission_factor] do |characteristics|
+              characteristics[:rooms] * characteristics[:duration] * characteristics[:emission_factor]
             end
             
+            #### Default emission
+            # **Complies:**
+            #
+            # Displays an error message if the previous method fails.
             quorum 'default' do
               raise "The emission committee's default quorum should never be called."
             end
           end
           
-          committee :emission_factor do # returns kg CO2e per room night
+          ### Emission factor calculation
+          # Returns the `emission factor` (*kg CO<sub>2</sub>e / room-night*)
+          committee :emission_factor do
+            #### Emission factor from fuel intensities and eGRID
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # - Looks up the [natural gas](http://data.brighterplanet.com/fuels) emission factor (*kg CO<sub>2</sub>e / cubic m*)
+            # - Looks up the [fuel oil](http://data.brighterplanet.com/fuels) emission factor (*kg CO<sub>2</sub>e / l*)
+            # - Looks up the [eGRID subregion](http://data.brighterplanet.com/egrid_subregions) electricity emission factor
+            # - Looks up the [eGRID region](http://data.brighterplanet.com/egrid_regions) electricity loss factor
+            # - Adjusts the electricity emission factor upwards by dividing by 1 - the electricity loss factor
+            # - Divides the natural gas emission factor (*kg CO<sub>2</sub>e / cubic m*) by the natural gas energy content (38,339,000 *J / cubic m*) to give an energy-based natural gas emission factor (*kg CO<sub>2</sub>e / J*)
+            # - Divides the fuel oil emission factor (*kg CO<sub>2</sub>e / l*) by the fuel oil energy content (38,655,000 *J / l*) to give an energy-based fuel oil emission factor (*kg CO<sub>2</sub>e / J*)
+            # - Divides the energy-based natural gas emission factor by 0.817 and the energy-based fuel oil emission factor by 0.846, adds these together and divides by 2, and divides by 0.95. This gives a district heat emission factor (*kg CO<sub>2</sub>e / J*) based on the assumption that district heat is produced by 50% natural gas and 50% fuel oil, natural gas boilers are 81.7% efficient, fuel oil boilers are 84.6% efficient, and transmission losses are 5%.
+            # - Multiplies `natural gas intensity` by the natural gas emission factor, `fuel oil intensity` by the fuel oil emission factor, `electricity intensity` by the electricity emission factor, and `district heat intensity` by the district heat emission factor
+            # - Adds these together
             quorum 'from fuel intensities and eGRID', :needs => [:natural_gas_intensity, :fuel_oil_intensity, :electricity_intensity, :district_heat_intensity, :egrid_subregion, :egrid_region] do |characteristics|
               natural_gas = FuelType.find_by_name "Commercial Natural Gas"
               fuel_oil = FuelType.find_by_name "Distillate Fuel Oil 2"
-              
-              # FIXME TODO won't need this once we convert emission factors to co2 / unit energy
-              #   kg / J                           kg / cubic m     J / cubic m
               natural_gas_energy_ef = natural_gas.emission_factor / 38_339_000
-              
-              # FIXME TODO won't need this once we convert emission factors to co2 / unit energy
-              #   kg / J                        kg / l           J / l
               fuel_oil_energy_ef = fuel_oil.emission_factor / 38_655_000
-              
-              # based on CA-CP calculator
-              # assume district heat is 50% natural gas 50% distillate fuel
-              # assume natural gas boilers 81.7% efficient; fuel oil boilers 84.6% efficient
-              # assume 5% transmission loss
               district_heat_emission_factor = (((natural_gas_energy_ef / 0.817) / 2) + ((fuel_oil_energy_ef / 0.846) / 2)) / 0.95
               
               (characteristics[:natural_gas_intensity] * natural_gas.emission_factor) +
@@ -44,89 +71,191 @@ module BrighterPlanet
             end
           end
           
-          committee :natural_gas_intensity do # returns cubic metres per room-night
+          ### Natural gas intensity calculation
+          # Returns the `natural gas intensity` (*cubic m / room-night*).
+          committee :natural_gas_intensity do
+            #### Natural gas intensity from census division
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Looks up the [census division](http://data.brighterplanet.com/census_divisions) `natural gas intensity` (*cubic m / room-night*).
             quorum 'from census division', :needs => :census_division do |characteristics|
               characteristics[:census_division].lodging_building_natural_gas_intensity
             end
             
+            #### Natural gas intensity from lodging class
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Looks up the [lodging class](http://data.brighterplanet.com/lodging_class) `natural gas intensity` (*cubic m / room-night*).
             quorum 'from lodging class', :needs => :lodging_class do |characteristics|
               characteristics[:lodging_class].natural_gas_intensity
             end
           end
           
-          committee :fuel_oil_intensity do # returns litres per room-night
+          ### Fuel oil intensity calculation
+          # Returns the `fuel oil intensity` (*l / room-night*).
+          committee :fuel_oil_intensity do
+            #### Fuel oil intensity from census division
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Looks up the [census division](http://data.brighterplanet.com/census_divisions) `fuel oil intensity` (*l / room-night*).
             quorum 'from census division', :needs => :census_division do |characteristics|
               characteristics[:census_division].lodging_building_fuel_oil_intensity
             end
             
+            #### Fuel oil intensity from lodging class
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Looks up the [lodging class](http://data.brighterplanet.com/lodging_class) `fuel oil intensity` (*l / room-night*).
             quorum 'from lodging class', :needs => :lodging_class do |characteristics|
               characteristics[:lodging_class].fuel_oil_intensity
             end
           end
           
-          committee :electricity_intensity do # returns kilowatt hours per room-night
+          ### Electricity intensity calculation
+          # Returns the `electricity intensity` (*kWh / room-night*).
+          committee :electricity_intensity do
+            #### Electricity intensity from census division
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Looks up the [census division](http://data.brighterplanet.com/census_divisions) `electricity intensity` (*kWh / room-night*).
             quorum 'from census division', :needs => :census_division do |characteristics|
               characteristics[:census_division].lodging_building_electricity_intensity
             end
             
+            #### Electricity intensity from lodging class
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Looks up the [lodging class](http://data.brighterplanet.com/lodging classes) `electricity intensity` (*kWh / room-night*).
             quorum 'from lodging class', :needs => :lodging_class do |characteristics|
               characteristics[:lodging_class].electricity_intensity
             end
           end
           
-          committee :district_heat_intensity do # returns joules per room-night
+          ### District heat intensity calculation
+          # Returns the `district heat intensity` (*J / room-night*).
+          committee :district_heat_intensity do
+            #### District heat intensity from census division
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Looks up the [census division](http://data.brighterplanet.com/census_divisions) `district heat intensity` (*J / room-night*).
             quorum 'from census division', :needs => :census_division do |characteristics|
               characteristics[:census_division].lodging_building_district_heat_intensity
             end
             
+            #### District heat intensity from lodging class
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Looks up the [lodging class](http://data.brighterplanet.com/lodging_classes) `district heat intensity` (*J / room-night*).
             quorum 'from lodging class', :needs => :lodging_class do |characteristics|
               characteristics[:lodging_class].district_heat_intensity
             end
           end
           
-          committee :lodging_class do # returns the type of lodging
+          ### Lodging class calculation
+          # Returns the [lodging class](http://data.brighterplanet.com/lodging_classes).
+          committee :lodging_class do
+            #### Lodging class from client input
+            # **Complies:** All
+            #
+            # Uses the client-input [loding class](http://data.brighterplanet.com/lodging_classes).
+            
+            #### Default lodging class
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Uses an artificial [lodging class](http://data.brighterplanet.com/lodging_classes) that represents the U.S. average.
             quorum 'default' do
               LodgingClass.find_by_name 'Average'
             end
           end
           
-          committee :egrid_region do # returns eGRID region
+          ### eGRID region calculation
+          # Returns the lodging's [eGRID region](http://data.brighterplanet.com/egrid_regions).
+          committee :egrid_region do
+            #### eGRID region from eGRID subregion
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Looks up the [eGRID subregion](http://data.brighterplanet.com/egrid_subregions) `eGRID region`.
             quorum 'from eGRID subregion', :needs => :egrid_subregion do |characteristics|
               characteristics[:egrid_subregion].egrid_region
             end
           end
           
-          committee :egrid_subregion do # returns eGRID subregion
+          ### eGRID subregion calculation
+          # Returns the lodging's [eGRID subregion](http://data.brighterplanet.com/egrid_subregions).
+          committee :egrid_subregion do
+            #### eGRID subregion from zip code
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Looks up the [zip code](http://data.brighterplanet.com/zip_codes) `eGRID subregion`.
             quorum 'from zip code', :needs => :zip_code do |characteristics|
               characteristics[:zip_code].egrid_subregion
             end
             
+            #### Default eGRID subregion
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Uses an artificial [eGRID subregion](http://data.brighterplanet.com/egrid_subregions) that represents the U.S. average.
             quorum 'default' do
               EgridSubregion.find_by_abbreviation 'US'
             end
           end
           
-          committee :census_division do # returns census division
+          ### Census division calculation
+          # Returns the lodging's [census division](http://data.brighterplanet.com/census_divisions).
+          committee :census_division do
+            #### Census division from state
+            # Looks up the [state](http://data.brighterplanet.com/states) `census division`.
             quorum 'from state', :needs => :state do |characteristics|
               characteristics[:state].census_division
             end
           end
           
-          committee :state do # returns state
+          ### State calculation
+          # Returns the lodging's [state](http://data.brighterplanet.com/states).
+          committee :state do
+            #### State from zip code
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Looks up the [zip code](http://data.brighterplanet.com/zip_codes) `state`.
             quorum 'from zip code', :needs => :zip_code do |characteristics|
               characteristics[:zip_code].state
             end
           end
           
-          committee :nights do # returns nights
+          ### Zip code calculation
+          # Returns the client-input [zip code](http://data.brighterplanet.com/zip_codes).
+          
+          ### Duration calculation
+          # Returns the stay's `duration` (*nights*).
+          committee :duration do
+            #### Duration from client input
+            # **Complies:** All
+            #
+            # Uses the client-input `duration` (*nights*).
+            
+            #### Default duration
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Uses 1 *night*.
             quorum 'default' do
-              base.fallback.nights
+              1
             end
           end
           
-          committee :rooms do # return rooms
+          ### Rooms calculation
+          # Returns the number of `rooms` used.
+          committee :rooms do
+            #### Rooms from client input
+            # **Complies:** All
+            #
+            # Uses the client-input number of `rooms`.
+            
+            #### Default rooms
+            # **Complies:** GHG Protocol, ISO 14064-1, Climate Registry Protocol
+            #
+            # Uses 1 room.
             quorum 'default' do
-              base.fallback.rooms
+              1
             end
           end
         end

data/lib/lodging/characterization.rb

@@ -7,7 +7,7 @@ module BrighterPlanet
           has :zip_code
           has :state
           has :rooms
-          has :nights
+          has :duration
         end
       end
     end

data/lib/lodging/data.rb

@@ -8,7 +8,7 @@ module BrighterPlanet
             string  'zip_code_name'
             string  'state_postal_abbreviation'
             integer 'rooms'
-            integer 'nights'
+            integer 'duration'
           end
 
           process :run_data_miner_on_belongs_to_associations

data/lib/test_support/lodging_record.rb

@@ -10,7 +10,4 @@ class LodgingRecord < ActiveRecord::Base
   belongs_to :lodging_class, :foreign_key => 'lodging_class_name'
   belongs_to :zip_code,      :foreign_key => 'zip_code_name'
   belongs_to :state,         :foreign_key => 'state_postal_abbreviation'
-
-  falls_back_on :rooms  => 1,
-                :nights => 1
 end

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: lodging
 version: !ruby/object:Gem::Version 
+  hash: 13
   prerelease: false
   segments: 
   - 0
   - 0
-  - 8
-  version: 0.0.8
+  - 9
+  version: 0.0.9
 platform: ruby
 authors: 
 - Andy Rossmeissl
@@ -18,100 +19,108 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-19 00:00:00 -04:00
+date: 2010-11-17 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: activerecord
+  prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 7
         segments: 
         - 3
         - 0
         - 0
         version: 3.0.0
   type: :development
-  prerelease: false
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
   name: bundler
+  prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 23
         segments: 
         - 1
         - 0
         - 0
         version: 1.0.0
   type: :development
-  prerelease: false
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: cucumber
+  prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
   type: :development
-  prerelease: false
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: jeweler
+  prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 7
         segments: 
         - 1
         - 4
         - 0
         version: 1.4.0
   type: :development
-  prerelease: false
   version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: rake
+  prerelease: false
   requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
   type: :development
-  prerelease: false
   version_requirements: *id005
 - !ruby/object:Gem::Dependency 
   name: rdoc
+  prerelease: false
   requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
   type: :development
-  prerelease: false
   version_requirements: *id006
 - !ruby/object:Gem::Dependency 
   name: rspec
+  prerelease: false
   requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 62196417
         segments: 
         - 2
         - 0
@@ -120,37 +129,38 @@ dependencies:
         - 17
         version: 2.0.0.beta.17
   type: :development
-  prerelease: false
   version_requirements: *id007
 - !ruby/object:Gem::Dependency 
   name: sniff
+  prerelease: false
   requirement: &id008 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 23
         segments: 
         - 0
         - 2
         - 0
         version: 0.2.0
   type: :development
-  prerelease: false
   version_requirements: *id008
 - !ruby/object:Gem::Dependency 
   name: emitter
+  prerelease: false
   requirement: &id009 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 21
         segments: 
         - 0
         - 1
         - 7
         version: 0.1.7
   type: :runtime
-  prerelease: false
   version_requirements: *id009
 description: A software model in Ruby for the greenhouse gas emissions of a lodging
 email: andy@rossmeissl.net
@@ -187,7 +197,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3820895678693949389
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -196,6 +206,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"