automobile_trip 0.0.9 → 0.1.0

data/features/automobile_trip_emissions.feature

@@ -1,23 +1,153 @@
 Feature: Automobile Trip Emissions Calculations
   The automobile trip model should generate correct emission calculations
 
-  Scenario: Calculations starting from nothing
+  Scenario: Calculations from nothing
     Given an automobile_trip has nothing
     When emissions are calculated
-    Then the emission value should be within "0.1" kgs of "140.4"
+    Then the emission value should be within "0.01" kgs of "4.62"
 
-  Scenario: Calculations starting from fuel use
-    Given an automobile_trip has "fuel_use" of "100"
+  Scenario Outline: Calculations from date
+    Given an automobile_trip has "date" of "<date>"
+    And it is the year "2010"
     When emissions are calculated
-    Then the emission value should be within "0.1" kgs of "246.3"
+    Then the emission value should be within "0.01" kgs of "<emission>"
+    Examples:
+      | date       | emission |
+      | 2009-06-25 | 0.0      |
+      | 2010-06-25 | 4.62     |
+      | 2011-06-25 | 0.0      |
 
-  Scenario: Calculations starting from fuel type
-    Given an automobile_trip has "fuel_type.name" of "Gasoline"
+  Scenario Outline: Calculations from date and timeframe
+    Given an automobile_trip has "date" of "<date>"
+    And it has "timeframe" of "<timeframe>"
     When emissions are calculated
-    Then the emission value should be within "0.1" kgs of "570.0"
+    Then the emission value should be within "0.01" kgs of "<emission>"
+    Examples:
+      | date       | timeframe             | emission |
+      | 2009-06-25 | 2009-01-01/2009-01-31 | 0.0      |
+      | 2009-06-25 | 2009-01-01/2009-12-31 | 4.62     |
+      | 2009-06-25 | 2009-12-01/2009-12-31 | 0.0      |
 
-  Scenario: Calculations starting from fuel use and fuel type
-    Given an automobile_trip has "fuel_type.name" of "Gasoline"
-    And it has "fuel_use" of "100"
+  Scenario: Calculations from urbanity estimate
+    Given an automobile_trip has "urbanity_estimate" of "0.5"
     When emissions are calculated
-    Then the emission value should be within "0.1" kgs of "1000.0"
+    Then the emission value should be within "0.01" kgs of "4.62"
+
+  Scenario Outline: Calculations from hybridity and urbanity estimate
+    Given an automobile_trip has "hybridity" of "<hybridity>"
+    And it has "urbanity_estimate" of "0.5"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "<emission>"
+    Examples:
+      | hybridity | emission |
+      | true      | 3.30     |
+      | false     | 4.66     |
+
+  Scenario: Calculations from make and urbanity estimate
+    Given an automobile_trip has "urbanity_estimate" of "0.5"
+    And it has "make.name" of "Toyota"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "3.96"
+
+  Scenario Outline: Calculations from make, hybridity and urbanity estimate
+    Given an automobile_trip has "hybridity" of "<hybridity>"
+    And it has "urbanity_estimate" of "0.5"
+    And it has "make.name" of "Toyota"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "<emission>"
+    Examples:
+      | hybridity | emission |
+      | true      | 2.83     |
+      | false     | 4.00     |
+
+  Scenario: Calculations from make year and urbanity estimate
+    Given an automobile_trip has "urbanity_estimate" of "0.5"
+    And it has "make_year.name" of "Toyota 2003"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "2.64"
+
+  Scenario Outline: Calculations from make year, hybridity and urbanity estimate
+    Given an automobile_trip has "hybridity" of "<hybridity>"
+    And it has "urbanity_estimate" of "0.5"
+    And it has "make_year.name" of "Toyota 2003"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "<emission>"
+    Examples:
+      | hybridity | emission |
+      | true      | 1.89     |
+      | false     | 2.66     |
+
+  Scenario: Calculations from size class and urbanity estimate
+    Given an automobile_trip has "urbanity_estimate" of "0.5"
+    And it has "size_class.name" of "Midsize Car"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "2.97"
+
+  Scenario Outline: Calculations from size class, hybridity, and urbanity estimate
+    Given an automobile_trip has "hybridity" of "<hybridity>"
+    And it has "urbanity_estimate" of "0.5"
+    And it has "size_class.name" of "Midsize Car"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "<emission>"
+    Examples:
+      | hybridity | emission |
+      | true      | 1.73     |
+      | false     | 3.47     |
+
+  Scenario: Calculations from make model and urbanity estimate
+    Given an automobile_trip has "urbanity_estimate" of "0.5"
+    And it has "make_model.name" of "Toyota Prius"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "1.65"
+
+  Scenario: Calculations from make model year and urbanity estimate
+    Given an automobile_trip has "urbanity_estimate" of "0.5"
+    And it has "make_model_year.name" of "Toyota Prius 2003"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "1.16"
+
+  Scenario: Calculations from make model year variant and urbanity estimate
+    Given an automobile_trip has "urbanity_estimate" of "0.5"
+    And it has "make_model_year_variant.row_hash" of "xxx1"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "0.89"
+
+  Scenario: Calculations from speed and duration
+    Given an automobile_trip has "speed" of "5.0"
+    And it has "duration" of "120.0"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "2.83"
+
+  Scenario: Calculations from driveable locations
+    Given an automobile_trip has "origin" of "43,-73"
+    And the geocoder will encode the origin as "43,-73"
+    And it has "destination" of "43.1,-73"
+    And the geocoder will encode the destination as "43.1,-73"
+    And mapquest will return a distance of "57.93638" kilometres
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "16.38"
+
+  Scenario: Calculations from non-driveable locations
+    Given an automobile_trip has "origin" of "Lansing, MI"
+    And the geocoder will encode the origin as "42.732535,-84.5555347"
+    And it has "destination" of "Canterbury, Kent, UK"
+    And the geocoder will encode the destination as "51.2772689,1.0805173"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "4.62"
+
+  Scenario: Calculations from fuel efficiency and distance
+    Given an automobile_trip has "fuel_efficiency" of "10.0"
+    And it has "distance" of "100.0"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "24.25"
+
+  Scenario Outline: Calculations from fuel use and fuel
+    Given an automobile_trip has "fuel_use" of "20.0"
+    And it has "automobile_fuel.name" of "<fuel>"
+    When emissions are calculated
+    Then the emission value should be within "0.01" kgs of "<emission>"
+    Examples:
+      | fuel             | emission |
+      | regular gasoline | 48.31    |
+      | diesel           | 56.52    |
+      | B20              | 45.72    |

data/features/step_definitions/automobile_trip_steps.rb

@@ -0,0 +1,15 @@
+Given /^mapquest determines the distance to be "([^\"]*)"$/ do |distance|
+  mockquest = mock MapQuestDirections, :distance_in_kilometres => distance
+  MapQuestDirections.stub!(:new).and_return mockquest
+end
+
+Given /^the geocoder will encode the (.*) as "(.*)"$/ do |component, location|
+  @expectations << lambda do
+    components = @characteristics ? @characteristics : @activity_hash
+    component_value = components[component.to_sym].to_s
+    code = mock Object, :ll => location
+    Geokit::Geocoders::MultiGeocoder.should_receive(:geocode).
+      with(component_value).
+      and_return code
+  end
+end

data/features/step_definitions/mapquest_steps.rb

@@ -0,0 +1,5 @@
+Given /^mapquest will return a distance of "(.*)" kilometres$/ do |kms|
+  @activity_hash[:mapquest_api_key] = 'ABC123'
+  mock_map = mock MapQuestDirections, :distance_in_kilometres => kms.to_f
+  MapQuestDirections.stub!(:new).and_return mock_map
+end

data/features/support/env.rb

@@ -3,6 +3,12 @@ Bundler.setup
 
 require 'cucumber'
 require 'cucumber/formatter/unicode'
+require 'rspec'
+require 'rspec/expectations'
+require 'cucumber/rspec/doubles'
+
+require 'data_miner'
+DataMiner.logger = Logger.new(nil)
 
 require 'sniff'
-Sniff.init File.join(File.dirname(__FILE__), '..', '..'), :earth => :fuel, :cucumber => true
+Sniff.init File.join(File.dirname(__FILE__), '..', '..'), :cucumber => true, :earth => [:automobile, :fuel]

data/lib/automobile_trip.rb

@@ -3,5 +3,6 @@ require 'emitter'
 module BrighterPlanet
   module AutomobileTrip
     extend BrighterPlanet::Emitter
+    scope 'The automobile trip emission estimate includes CO2 emissions from non-biogenic fuel use, CH4 and N2O emissions from all fuel use, and fugitive HFC emissions from air conditioning.'
   end
 end

data/lib/automobile_trip/carbon_model.rb

@@ -2,39 +2,596 @@
 # See LICENSE for details.
 # Contact Brighter Planet for dual-license arrangements.
 
+require File.expand_path('../../vendor/plugin/mapquest/lib/mapquest_directions', File.dirname(__FILE__))
+require 'geokit'
 
+## Automobile trip 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 an automobile trip**.
+#
+##### Timeframe and activity period
+# The model estimates the emissions that occur during a particular `timeframe`. To do this it needs to know the `date` on which the trip occurred. For example, if the `timeframe` is January 2010, a trip that occurred on January 5, 2010 will have emissions but a trip that occurred on February 1, 2010 will not.
+#
+##### 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 AutomobileTrip
     module CarbonModel
       def self.included(base)
         base.decide :emission, :with => :characteristics do
-          committee :emission do # returns kg CO2e
-            quorum 'from fuel use and emission factor', :needs => [:fuel_use, :emission_factor] do |characteristics|
-              characteristics[:fuel_use] * characteristics[:emission_factor]
+          ### Emission calculation
+          # Returns the `emission` estimate (*kg CO<sub>2</sub>e*).
+          committee :emission do
+            #### Emission from co2 emission, ch4 emission, n2o emission, and hfc emission
+            quorum 'from co2 emission, ch4 emission, n2o emission, and hfc emission',
+              :needs => [:co2_emission, :ch4_emission, :n2o_emission, :hfc_emission],
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # Sums the non-biogenic emissions
+                characteristics[:co2_emission] + characteristics[:ch4_emission] + characteristics[:n2o_emission] + characteristics[:hfc_emission]
+            end
+          end
+          
+          ### CO<sub>2</sub> emission calculation
+          # Returns the `co2 emission` (*kg CO<sub>2</sub>e*)
+          committee :co2_emission do
+            #### CO<sub>2</sub> emission from fuel use, co2 emission factor, date, and timeframe
+            quorum 'from fuel use, co2 emission factor, date, and timeframe',
+              :needs => [:fuel_use, :co2_emission_factor, :date],
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics, timeframe|
+                # - Checks whether the trip `date` falls within the `timeframe`
+                date = characteristics[:date].is_a?(Date) ? characteristics[:date] : Date.parse(characteristics[:date].to_s)
+                if timeframe.include? date
+                  # - Multiplies `fuel use` (*l*) by the `co2 emission factor` (*kg CO<sub>2</sub>e / l*) to give *kg CO<sub>2</sub>e*
+                  characteristics[:fuel_use] * characteristics[:co2_emission_factor]
+                else
+                  # - If the `date` does not fall within the `timeframe`, `co2 emission` is zero
+                  0
+                end
+            end
+          end
+          
+          ### CO<sub>2</sub> biogenic emission calculation
+          # Returns the `co2 biogenic emission` (*kg CO<sub>2</sub>e*)
+          committee :co2_biogenic_emission do
+            #### CO<sub>2</sub> biogenic emission from fuel use, co2 biogenic emission factor, date, and timeframe
+            quorum 'from fuel use, co2 biogenic emission factor, date, and timeframe',
+              :needs => [:fuel_use, :co2_biogenic_emission_factor, :date],
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics, timeframe|
+                # - Checks whether the trip `date` falls within the `timeframe`
+                date = characteristics[:date].is_a?(Date) ? characteristics[:date] : Date.parse(characteristics[:date].to_s)
+                if timeframe.include? date
+                  # - Multiplies `fuel use` (*l*) by the `co2 biogenic emission factor` (*kg CO<sub>2</sub>e / l*) to give *kg CO<sub>2</sub>e*
+                  characteristics[:fuel_use] * characteristics[:co2_biogenic_emission_factor]
+                else
+                  # - If the `date` does not fall within the `timeframe`, `co2 biogenic emission` is zero
+                  0
+                end
+            end
+          end
+          
+          ### CH<sub>4</sub> emission calculation
+          # Returns the `ch4 emission` (*kg CO<sub>2</sub>e*)
+          committee :ch4_emission do
+            #### CH<sub>4</sub> emission from fuel use, ch4 emission factor, date, and timeframe
+            quorum 'from fuel use, ch4 emission factor, date, and timeframe',
+              :needs => [:fuel_use, :ch4_emission_factor, :date],
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics, timeframe|
+                # - Checks whether the trip `date` falls within the `timeframe`
+                date = characteristics[:date].is_a?(Date) ? characteristics[:date] : Date.parse(characteristics[:date].to_s)
+                if timeframe.include? date
+                  # - Multiplies `fuel use` (*l*) by the `ch4 emission factor` (*kg CO<sub>2</sub>e / l*) to give *kg CO<sub>2</sub>e*
+                  characteristics[:fuel_use] * characteristics[:ch4_emission_factor]
+                else
+                  # - If the `date` does not fall within the `timeframe`, `ch4 emission` is zero
+                  0
+                end
+            end
+          end
+          
+          ### N<sub>2</sub>O emission calculation
+          # Returns the `n2o emission` (*kg CO<sub>2</sub>e*)
+          committee :n2o_emission do
+            #### N<sub>2</sub>O emission from fuel use, n2o emission factor, date, and timeframe
+            quorum 'from fuel use, n2o emission factor, date, and timeframe',
+              :needs => [:fuel_use, :n2o_emission_factor, :date],
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics, timeframe|
+                # - Checks whether the trip `date` falls within the `timeframe`
+                date = characteristics[:date].is_a?(Date) ? characteristics[:date] : Date.parse(characteristics[:date].to_s)
+                if timeframe.include? date
+                  # - Multiplies `fuel use` (*l*) by the `n2o emission factor` (*kg CO<sub>2</sub>e / l*) to give *kg CO<sub>2</sub>e*
+                  characteristics[:fuel_use] * characteristics[:n2o_emission_factor]
+                else
+                  # - If the `date` does not fall within the `timeframe`, `n2o emission` is zero
+                  0
+                end
+            end
+          end
+          
+          ### HFC emission calculation
+          # Returns the `hfc emission` (*kg CO<sub>2</sub>e*)
+          committee :hfc_emission do
+            #### HFC emission from fuel use, hfc emission factor, date, and timeframe
+            quorum 'from fuel use, hfc emission factor, date, and timeframe',
+              :needs => [:fuel_use, :hfc_emission_factor, :date],
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics, timeframe|
+                # - Checks whether the trip `date` falls within the `timeframe`
+                date = characteristics[:date].is_a?(Date) ? characteristics[:date] : Date.parse(characteristics[:date].to_s)
+                if timeframe.include? date
+                  # - Multiplies `fuel use` (*l*) by the `hfc emission factor` (*kg CO<sub>2</sub>e / l*) to give *kg CO<sub>2</sub>e*
+                  characteristics[:fuel_use] * characteristics[:hfc_emission_factor]
+                else
+                  # - If the `date` does not fall within the `timeframe`, `hfc emission` is zero
+                  0
+                end
+            end
+          end
+          
+          ### CO<sub>2</sub> emission factor calculation
+          # Returns the `co2 emission factor` (*kg CO<sub>2</sub>e / l*)
+          committee :co2_emission_factor do
+            #### CO<sub>2</sub> emission factor from automobile fuel
+            quorum 'from automobile fuel',
+              :needs => :automobile_fuel,
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # Looks up the [fuel](http://data.brighterplanet.com/fuels) `co2 emission factor` (*kg CO</sub>2</sub>e / l*)
+                characteristics[:automobile_fuel].co2_emission_factor
+            end
+          end
+          
+          ### CO<sub>2</sub> biogenic emission factor calculation
+          # Returns the `co2 biogenic emission factor` (*kg CO<sub>2</sub>e / l*)
+          committee :co2_biogenic_emission_factor do
+            #### CO<sub>2</sub> biogenic emission factor from automobile fuel
+            quorum 'from automobile fuel',
+              :needs => :automobile_fuel,
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # Looks up the [fuel](http://data.brighterplanet.com/fuels) `co2 biogenic emission factor` (*kg CO</sub>2</sub>e / l*)
+                characteristics[:automobile_fuel].co2_biogenic_emission_factor
+            end
+          end
+          
+          ### CH<sub>4</sub> emission factor calculation
+          # Returns the `ch4 emission factor` (*kg CO<sub>2</sub>e / l*)
+          committee :ch4_emission_factor do
+            #### CH<sub>4</sub> emission factor from automobile fuel
+            quorum 'from automobile fuel',
+              :needs => :automobile_fuel,
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # Looks up the [fuel](http://data.brighterplanet.com/fuels) `ch4 emission factor` (*kg CO</sub>2</sub>e / l*)
+                characteristics[:automobile_fuel].ch4_emission_factor
+            end
+          end
+          
+          ### N<sub>2</sub>O emission factor calculation
+          # Returns the `n2o emission factor` (*kg CO<sub>2</sub>e / l*)
+          committee :n2o_emission_factor do
+            #### N<sub>2</sub>O emission factor from automobile fuel
+            quorum 'from automobile fuel',
+              :needs => :automobile_fuel,
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # Looks up the [fuel](http://data.brighterplanet.com/fuels) `n2o emission factor` (*kg CO</sub>2</sub>e / l*)
+                characteristics[:automobile_fuel].n2o_emission_factor
+            end
+          end
+          
+          ### HFC emission factor calculation
+          # Returns the `hfc emission factor` (*kg CO<sub>2</sub>e / l*)
+          committee :hfc_emission_factor do
+            #### HFC emission factor from automobile fuel
+            quorum 'from automobile fuel',
+              :needs => :automobile_fuel,
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # Looks up the [fuel](http://data.brighterplanet.com/fuels) `hfc emission factor` (*kg CO</sub>2</sub>e / l*)
+                characteristics[:automobile_fuel].hfc_emission_factor
+            end
+          end
+          
+          ### Fuel calculation
+          # Returns the `fuel` used by the automobile.
+          committee :automobile_fuel do
+            #### Fuel from client input
+            # **Complies:** All
+            #
+            # Uses the client-input [automobile fuel](http://data.brighterplanet.com/automobile_fuels).
+            
+            #### Fuel from make model year variant
+            quorum 'from make model year variant',
+              :needs => :make_model_year_variant,
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # Looks up the [variant](http://data.brighterplanet.com/automobile_make_model_year_variants) `automobile fuel`.
+                characteristics[:make_model_year_variant].fuel
             end
             
-            quorum 'default' do
-              raise "The emission committee's default quorum should never be called"
+            #### Default fuel
+            quorum 'default',
+              # **Complies:** GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_3, :iso] do |characteristics|
+                # Looks up the default [automobile fuel](http://data.brighterplanet.com/automobile_fuels).
+                AutomobileFuel.fallback
+            end
+          end
+          
+          ### Fuel use calculation
+          # Returns the trip `fuel use` (*l*).
+          committee :fuel_use do
+            #### Fuel use from fuel efficiency and distance
+            quorum 'from fuel efficiency and distance',
+              :needs => [:fuel_efficiency, :distance],
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # Divides the `distance` (*km*) by the `fuel efficiency` (*km / l*) to give *l*.
+                characteristics[:distance] / characteristics[:fuel_efficiency]
             end
           end
           
-          committee :emission_factor do # returns lbs CO2e / l
-            quorum 'from fuel type', :needs => :fuel_type do |characteristics|
-              characteristics[:fuel_type].emission_factor
+          ### Distance calculation
+          # Returns the trip `distance` (*km*).
+          committee :distance do
+            #### Distance from client input
+            # **Complies:** All
+            #
+            # Uses the client-input `distance` (*km*).
+            
+            #### Distance from origin and destination locations
+            quorum 'from origin and destination locations',
+              :needs => [:origin_location, :destination_location, :mapquest_api_key],
+              # **Complies:** GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_3, :iso] do |characteristics|
+                # Uses the [Mapquest directions API](http://developer.mapquest.com/web/products/dev-services/directions-ws) to calculate distance by road between the origin and destination locations.
+                mapquest = MapQuestDirections.new characteristics[:origin_location],
+                                                  characteristics[:destination_location],
+                                                  characteristics[:mapquest_api_key]
+                begin
+                  mapquest.distance_in_kilometres
+                rescue
+                  nil
+                end
+            end
+            
+            #### Distance from duration and speed
+            quorum 'from duration and speed',
+              :needs => [:duration, :speed],
+              # **Complies:** GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_3, :iso] do |characteristics|
+                # Divides the `duration` (*minutes*) by 60 and multiplies by the `speed` (*km / hour*) to give *km*.
+                (characteristics[:duration] / 60.0) * characteristics[:speed]
             end
             
-            quorum 'default' do
-              base.fallback.emission_factor
+            #### Default distance
+            quorum 'default',
+              # **Complies:** GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_3, :iso] do
+                # Uses a default `distance` of 16.33 *km*, [calculated from NHTS 2009 data](https://spreadsheets.google.com/pub?key=0AoQJbWqPrREqdFhib1FaNVp5VDkxejh4N3FWQmp2VUE&hl=en&output=html).
+                base.fallback.distance
+            end
+          end
+          
+          ### Destination location calculation
+          # Returns the `destination location` (*lat / lng*).
+          committee :destination_location do
+            #### Destination location from destination
+            quorum 'from destination',
+              :needs => :destination,
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # Uses the [Geokit](http://geokit.rubyforge.org/) geocoder to determine the destination location (*lat / lng*).
+                code = Geokit::Geocoders::MultiGeocoder.geocode characteristics[:destination].to_s
+                code.ll == ',' ? nil : code.ll
             end
           end
           
-          committee :fuel_use do # returns l
-            quorum 'default' do
-              base.fallback.fuel_use
+          ### Origin location committee
+          # Returns the `origin location` (*lat / lng*).
+          committee :origin_location do
+            #### Destination location from destination
+            quorum 'from origin',
+              :needs => :origin,
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # Uses the [Geokit](http://geokit.rubyforge.org/) geocoder to determine the origin location (*lat / lng*).
+                code = Geokit::Geocoders::MultiGeocoder.geocode characteristics[:origin].to_s
+                code.ll == ',' ? nil : code.ll
+            end
+          end
+          
+          ### Destination calculation
+          # Returns the client-input `destination`.
+          
+          ### Origin calculation
+          # Returns the client-input `origin`.
+          
+          ### Duration calculation
+          # Returns the client-input `duration` (*minutes*).
+          
+          ### Speed calculation
+          # Returns the average `speed` at which the automobile travels (*km / hour*)
+          committee :speed do
+            #### Speed from client input
+            # **Complies:** All
+            #
+            # Uses the client-input `speed` (*km / hour*)
+            
+            #### Speed from urbanity
+            quorum 'from urbanity',
+              :needs => :urbanity,
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # * Takes average city and highway driving speeds from [EPA (2006)](http://www.epa.gov/fueleconomy/420r06017.pdf) and converts from *miles / hour* to *km / hour*
+                # * Calculates the harmonic mean of those speeds, weighted by `urbanity`
+                1 / (characteristics[:urbanity] / base.fallback.city_speed + (1 - characteristics[:urbanity]) / base.fallback.highway_speed)
+            end
+          end
+          
+          ### Fuel efficiency calculation
+          # Returns the `fuel efficiency` (*km / l*)
+          committee :fuel_efficiency do
+            #### Fuel efficiency from client input
+            # **Complies:** All
+            #
+            # Uses the client-input `fuel efficiency` (*km / l*).
+            
+            #### Fuel efficiency from make model year variant and urbanity
+            quorum 'from make model year variant and urbanity',
+              :needs => [:make_model_year_variant, :urbanity],
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # * Looks up the city and highway fuel efficiencies of the automobile [make model year variant](http://data.brighterplanet.com/automobile_make_model_year_variants) (*km / l*)
+                fuel_efficiency_city = characteristics[:make_model_year_variant].fuel_efficiency_city
+                fuel_efficiency_highway = characteristics[:make_model_year_variant].fuel_efficiency_highway
+                urbanity = characteristics[:urbanity]
+                if fuel_efficiency_city.present? and fuel_efficiency_highway.present?
+                  # * Calculates the harmonic mean of those fuel efficiencies, weighted by `urbanity`
+                  1.0 / ((urbanity / fuel_efficiency_city) + ((1.0 - urbanity) / fuel_efficiency_highway))
+                end
+            end
+            
+            #### Fuel efficiency from make model year and urbanity
+            quorum 'from make model year and urbanity',
+              :needs => [:make_model_year, :urbanity],
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # * Looks up the city and highway fuel efficiencies of the automobile [make model year](http://data.brighterplanet.com/automobile_make_model_years) (*km / l*)
+                fuel_efficiency_city = characteristics[:make_model_year].fuel_efficiency_city
+                fuel_efficiency_highway = characteristics[:make_model_year].fuel_efficiency_highway
+                urbanity = characteristics[:urbanity]
+                if fuel_efficiency_city.present? and fuel_efficiency_highway.present?
+                  # * Calculates the harmonic mean of those fuel efficiencies, weighted by `urbanity`
+                  1.0 / ((urbanity / fuel_efficiency_city) + ((1.0 - urbanity) / fuel_efficiency_highway))
+                end
+            end
+            
+            #### Fuel efficiency from make model and urbanity
+            quorum 'from make model and urbanity',
+              :needs => [:make_model, :urbanity],
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # * Looks up the city and highway fuel efficiencies of the automobile [make model](http://data.brighterplanet.com/automobile_make_models) (*km / l*)
+                fuel_efficiency_city = characteristics[:make_model].fuel_efficiency_city
+                fuel_efficiency_highway = characteristics[:make_model].fuel_efficiency_highway
+                urbanity = characteristics[:urbanity]
+                if fuel_efficiency_city.present? and fuel_efficiency_highway.present?
+                  # * Calculates the harmonic mean of those fuel efficiencies, weighted by `urbanity`
+                  1.0 / ((urbanity / fuel_efficiency_city) + ((1.0 - urbanity) / fuel_efficiency_highway))
+                end
+            end
+            
+            #### Fuel efficiency from size class, hybridity multiplier, and urbanity
+            quorum 'from size class, hybridity multiplier, and urbanity',
+              :needs => [:size_class, :hybridity_multiplier, :urbanity],
+              # **Complies:** GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_3, :iso] do |characteristics|
+                # * Looks up the automobile [size class](http://data.brighterplanet.com/automobile_makes) city and highway fuel efficiency (*km / l*)
+                fuel_efficiency_city = characteristics[:size_class].fuel_efficiency_city
+                fuel_efficiency_highway = characteristics[:size_class].fuel_efficiency_highway
+                urbanity = characteristics[:urbanity]
+                if fuel_efficiency_city.present? and fuel_efficiency_highway.present?
+                  # * Calculates the harmonic mean of those fuel efficiencies, weighted by `urbanity`
+                  # * Multiplies the result by the `hybridity multiplier`
+                  (1.0 / ((urbanity / fuel_efficiency_city) + ((1.0 - urbanity) / fuel_efficiency_highway))) * characteristics[:hybridity_multiplier]
+                end
+            end
+            
+            #### Fuel efficiency from make year and hybridity multiplier
+            quorum 'from make year and hybridity multiplier',
+              :needs => [:make_year, :hybridity_multiplier],
+              # **Complies:** GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_3, :iso] do |characteristics|
+                # * Looks up the automobile [make year](http://data.brighterplanet.com/automobile_make_years) combined fuel efficiency (*km / l*)
+                # * Multiplies the combined fuel efficiency by the `hybridity multiplier`
+                characteristics[:make_year].fuel_efficiency * characteristics[:hybridity_multiplier]
+            end
+            
+            #### Fuel efficiency from make and hybridity multiplier
+            quorum 'from make and hybridity multiplier',
+              :needs => [:make, :hybridity_multiplier],
+              # **Complies:** GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_3, :iso] do |characteristics|
+                # * Looks up the automobile [make](http://data.brighterplanet.com/automobile_makes) combined fuel efficiency (*km / l*)
+                # * Multiplies the combined fuel efficiency by the `hybridity multiplier`
+                if characteristics[:make].fuel_efficiency.present?
+                  characteristics[:make].fuel_efficiency * characteristics[:hybridity_multiplier]
+                else
+                  nil
+                end
+            end
+            
+            #### Fuel efficiency from hybridity multiplier
+            quorum 'from hybridity multiplier',
+              :needs => :hybridity_multiplier,
+              # **Complies:** GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_3, :iso] do |characteristics|
+                # * Takes a default `fuel efficiency` of 8.58 *km / l*, calculated from total US automobile vehicle miles travelled and gasoline and diesel consumption.
+                # * Multiplies the `fuel efficiency` by the `hybridity multiplier`
+                base.fallback.fuel_efficiency * characteristics[:hybridity_multiplier]
+            end
+          end
+          
+          ### Hybridity multiplier calculation
+          # Returns the `hybridity multiplier`.
+          # This value may be used to adjust the fuel efficiency based on whether the automobile is a hybrid or conventional vehicle.
+          committee :hybridity_multiplier do
+            #### Hybridity multiplier from size class, hybridity, and urbanity
+            quorum 'from size class, hybridity, and urbanity', 
+              :needs => [:size_class, :hybridity, :urbanity],
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # * Looks up the appropriate city and highway hybridity multipliers for the automobile [size class](http://data.brighterplanet.com/automobile_size_classes)
+                drivetrain = characteristics[:hybridity] ? :hybrid : :conventional
+                urbanity = characteristics[:urbanity]
+                size_class = characteristics[:size_class]
+                fuel_efficiency_multipliers = {
+                  :city => size_class.send(:"#{drivetrain}_fuel_efficiency_city_multiplier"),
+                  :highway => size_class.send(:"#{drivetrain}_fuel_efficiency_highway_multiplier")
+                }
+                if fuel_efficiency_multipliers.values.any?(&:present?)
+                  # * Calculates the harmonic mean of those multipliers, weighted by `urbanity`
+                  1.0 / ((urbanity / fuel_efficiency_multipliers[:city]) + ((1.0 - urbanity) / fuel_efficiency_multipliers[:highway]))
+                else
+                  nil
+                end
+            end
+            
+            #### Hybridity multiplier from hybridity and urbanity
+            quorum 'from hybridity and urbanity',
+              :needs => [:hybridity, :urbanity],
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # * Looks up the appropriate default city and highway hybridity multipliers
+                drivetrain = characteristics[:hybridity] ? :hybrid : :conventional
+                urbanity = characteristics[:urbanity]
+                fuel_efficiency_multipliers = {
+                  :city => AutomobileSizeClass.fallback.send(:"#{drivetrain}_fuel_efficiency_city_multiplier"),
+                  :highway => AutomobileSizeClass.fallback.send(:"#{drivetrain}_fuel_efficiency_highway_multiplier")
+                }
+                # * Calculates the harmonic mean of those multipliers, weighted by `urbanity`
+                1.0 / ((urbanity / fuel_efficiency_multipliers[:city]) + ((1.0 - urbanity) / fuel_efficiency_multipliers[:highway]))
+            end
+            
+            #### Default hybridity multiplier
+            quorum 'default',
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do
+                # Uses a default `hybridity multiplier` of 1.
+                base.fallback.hybridity_multiplier
+            end
+          end
+          
+          ### Urbanity calculation
+          # Returns the `urbanity`.
+          # This is the fraction of the total distance driven that occurs on towns and city streets as opposed to highways (defined using a 45 miles per hour "speed cutpoint").
+          committee :urbanity do
+            #### Urbanity from urbanity estimate
+            quorum 'from urbanity estimate',
+              :needs => :urbanity_estimate,
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do |characteristics|
+                # Uses the `urbanity estimate` if it is from zero to one
+                if characteristics[:urbanity_estimate] >= 0 and characteristics[:urbanity_estimate] <= 1
+                  characteristics[:urbanity_estimate]
+                end
+            end
+            
+            #### Default urbanity
+            quorum 'default',
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do
+                # Uses an `urbanity` of 0.43 after [EPA (2009) Appendix A](http://www.epa.gov/otaq/cert/mpg/fetrends/420r09014-appx-a.pdf)
+                base.fallback.urbanity_estimate
+            end
+          end
+          
+          ### Urbanity estimate calculation
+          # Returns the client-input `urbanity estimate`. This is the fraction of the total distance driven that occurs on towns and city streets as opposed to highways (defined using a 45 miles per hour "speed cutpoint").
+          
+          ### Hybridity calculation
+          # Returns the client-input `hybridity`. This indicates whether the automobile is a hybrid electric vehicle or a conventional vehicle.
+          
+          ### Size class calculation
+          # Returns the client-input automobile [size class](http://data.brighterplanet.com/automobile_size_classes).
+          
+          ### Make model year variant calculation
+          # Returns the client-input automobile [make model year variant](http://data.brighterplanet.com/automobile_make_model_year_variants).
+          
+          ### Make model year calculation
+          # Returns the client-input automobile [make model year](http://data.brighterplanet.com/automobile_make_model_years).
+          
+          ### Make model calculation
+          # Returns the client-input automobile [make model](http://data.brighterplanet.com/automobile_make_models).
+          
+          ### Make year calculation
+          # Returns the client-input automobile [make year](http://data.brighterplanet.com/automobile_make_years).
+          
+          ### Make calculation
+          # Returns the client-input automobile [make](http://data.brighterplanet.com/automobile_makes).
+          
+          ### Date calculation
+          # Returns the `date` on which the trip occurred.
+          committee :date do
+            #### Date from client input
+            # **Complies:** All
+            #
+            # Uses the client-input `date`.
+            
+            #### Date from timeframe
+            quorum 'from timeframe',
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO-14064-1, Climate Registry Protocol
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso, :tcr] do |characteristics, timeframe|
+                # Assumes the trip occurred on the first day of the `timeframe`.
+                timeframe.from
+            end
+          end
+          
+          ### Timeframe calculation
+          # Returns the `timeframe`.
+          # This is the period during which to calculate emissions.
+            
+            #### Timeframe from client input
+            # **Complies:** All
+            #
+            # Uses the client-input `timeframe`.
+            
+            #### Default timeframe
+            # **Complies:** All
+            #
+            # Uses the current calendar year.
+          
+          ### Mapquest API key lookup
+          # Returns Brighter Planet's Mapquest API key
+          committee :mapquest_api_key do
+            #### Default Mapquest API key
+            quorum 'default',
+              # **Complies:** GHG Protocol Scope 1, GHG Protocol Scope 3, ISO 14064-1
+              :complies => [:ghg_protocol_scope_1, :ghg_protocol_scope_3, :iso] do
+                # Uses Brighter Planet's Mapquest API key.
+                ENV['MAPQUEST_API_KEY']
             end
           end
         end
       end
+      
+      class Mapper
+        include Geokit::Mappable
+      end
     end
   end
 end