rail_trip 0.0.9 → 0.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. data/features/support/env.rb +1 -1
  2. data/lib/rail_trip/carbon_model.rb +72 -0
  3. data/lib/rail_trip/characterization.rb +21 -0
  4. data/lib/rail_trip/data.rb +19 -3
  5. data/lib/rail_trip/summarization.rb +17 -0
  6. metadata +50 -50
data/features/support/env.rb CHANGED
@@ -5,4 +5,4 @@ require 'cucumber'
5
5
  require 'cucumber/formatter/unicode'
6
6
 
7
7
  require 'sniff'
8
- Sniff.init File.join(File.dirname(__FILE__), '..', '..'), :earth => :rail
8
+ Sniff.init File.join(File.dirname(__FILE__), '..', '..'), :earth => :rail, :cucumber => true
data/lib/rail_trip/carbon_model.rb CHANGED
@@ -1,72 +1,144 @@
1
+ # Rail trip's carbon model is implemented using a domain-specific language
2
+ # provided by [Leap](http://github.com/rossmeissl/leap).
1
3
  require 'leap'
2
4
 
3
5
  module BrighterPlanet
4
6
  module RailTrip
7
+
8
+ #### Rail trip: carbon model
9
+ # This module is used by [Brighter Planet](http://brighterplanet.com)'s
10
+ # [emission estimate service](http://carbon.brighterplanet.com) to provide
11
+ # greenhouse gas emission estimates for rail trips.
12
+ #
13
+ # For more information see:
14
+ #
15
+ # * [API documentation](http://carbon.brighterplanet.com/rail_trips/options)
16
+ # * [Source code](http://github.com/brighterplanet/rail_trip)
17
+ #
18
+ ##### Collaboration
19
+ # Contributions to this carbon model are actively encouraged and warmly welcomed.
20
+ # This library includes a comprehensive test suite to ensure that your changes
21
+ # do not cause regressions. All changes shold include test coverage for new
22
+ # functionality. Please see [sniff](http://github.com/brighterplanet/sniff#readme),
23
+ # our emitter testing framework, for more information.
5
24
  module CarbonModel
6
25
  def self.included(base)
26
+ ##### The carbon model
7
27
  base.extend ::Leap::Subject
28
+
29
+ # This `decide` block encapsulates the carbon model. The carbon model is
30
+ # executed with a set of "characteristics" as input. These characteristics are
31
+ # parsed from input received by the client request according to the
32
+ # [characterization](characterization.html).
8
33
  base.decide :emission, :with => :characteristics do
34
+
35
+ # The emission committee returns a carbon emission estimate in kilograms CO2e.
9
36
  committee :emission do # returns kg CO2
37
+
38
+ # This calculation technique transforms amounts of diesel and electricity
39
+ # consumed during the rail trip---via their current emission factors---to
40
+ # an overall emission value. This value is divided by the passenger count
41
+ # to obtain a per-passenger emission share.
10
42
  quorum 'from fuel and passengers', :needs => [:diesel_consumed, :electricity_used, :passengers] do |characteristics|
11
43
  #(( litres diesel ) * ( kilograms CO2 / litre diesel ) + ( kwH ) * ( kilograms CO2 / kWh ))
12
44
  (characteristics[:diesel_consumed] * RailTrip.rail_trip_model.research(:diesel_emission_factor) + characteristics[:electricity_used] * RailTrip.rail_trip_model.research(:electricity_emission_factor)) / characteristics[:passengers]
13
45
  end
14
46
  end
15
47
 
48
+ # Generally the client will not know the exact amount of diesel consumed
49
+ # during the rail trip, so it must be calculated.
16
50
  committee :diesel_consumed do # returns litres diesel
51
+
52
+ # This technique uses trip distance and fuel efficiency to determine diesel
53
+ # consumption.
17
54
  quorum 'from distance and diesel intensity', :needs => [:distance, :diesel_intensity] do |characteristics|
18
55
  #( kilometres ) * ( litres diesel / kilometre )
19
56
  characteristics[:distance] * characteristics[:diesel_intensity]
20
57
  end
21
58
  end
22
59
 
60
+ # Similarly, electricity consumption will typically be computed here.
23
61
  committee :electricity_used do # returns kWh
62
+
63
+ # As with diesel consumption, we calculate electricity use by multiplying
64
+ # distance by "electric intensity"--- an analogue of fuel efficiency.
24
65
  quorum 'from distance and electricity intensity', :needs => [:distance, :electricity_intensity] do |characteristics|
25
66
  #( kilometres ) * ( kWh / kilometre )
26
67
  characteristics[:distance] * characteristics[:electricity_intensity]
27
68
  end
28
69
  end
29
70
 
71
+ # The distance of the rail trip is necessary to perform each of the above
72
+ # calculations and can be calculated using several methods.
30
73
  committee :distance do # returns kilometres
74
+
75
+ # The primary distance-calculation method is directly accepting an estimate from
76
+ # the client.
31
77
  quorum 'from distance estimate', :needs => :distance_estimate do |characteristics|
32
78
  characteristics[:distance_estimate]
33
79
  end
34
80
 
81
+ # Alternatively we can calculate distance by combining an estimate of trip
82
+ # duration with the train's average speed.
35
83
  quorum 'from duration', :needs => [:duration, :speed] do |characteristics|
36
84
  #( hours ) * ( kph )
37
85
  characteristics[:duration] * characteristics[:speed]
38
86
  end
39
87
 
88
+ # Finally, we can assume the trip covered an average distance, scoped by
89
+ # its rail class (subway vs. intercity, for example).
40
90
  quorum 'from rail class', :needs => :rail_class do |characteristics|
41
91
  characteristics[:rail_class].distance
42
92
  end
43
93
  end
44
94
 
95
+ # Diesel intensity is analogous to fuel efficiency (mpg), but are expressed
96
+ # in units of fuel per unit of distance.
45
97
  committee :diesel_intensity do # returns litres diesel / vehicle kilometre
98
+
99
+ # Brighter Planet has pre-calculated intensities for popular rail classes.
46
100
  quorum 'from rail class', :needs => :rail_class do |characteristics|
47
101
  characteristics[:rail_class].diesel_intensity
48
102
  end
49
103
  end
50
104
 
105
+ # Electricity intensity describes the amount of electric power consumed per
106
+ # unit of train travel distance.
51
107
  committee :electricity_intensity do # returns kWh / vehicle kilometre
108
+
109
+ # Again, intensities have been pre-calculated for popular rail classes.
52
110
  quorum 'from rail class', :needs => :rail_class do |characteristics|
53
111
  characteristics[:rail_class].electricity_intensity
54
112
  end
55
113
  end
56
114
 
115
+ # Speed is only necessary when used in combination with trip (temporal)
116
+ # duration to determine distance.
57
117
  committee :speed do # returns kph
118
+
119
+ # Rail classes provide average speed.
58
120
  quorum 'from rail class', :needs => :rail_class do |characteristics|
59
121
  characteristics[:rail_class].speed
60
122
  end
61
123
  end
62
124
 
125
+ # Each passenger is responsible for a share of the train trip's total
126
+ # footprint.
63
127
  committee :passengers do
128
+
129
+ # A passenger count can be gleaned from popular rail classes.
64
130
  quorum 'from rail class', :needs => :rail_class do |characteristics|
65
131
  characteristics[:rail_class].passengers
66
132
  end
67
133
  end
68
134
 
135
+ # The vehicle used for a rail trip can be meaningfully assigned to one
136
+ # of a list of categories called classes, including subways, intercity
137
+ # rail, and commuter rail, for example.
69
138
  committee :rail_class do
139
+
140
+ # If the client does not provide a rail class, we use an artificial
141
+ # rail class, constructed using a weighted average approach.
70
142
  quorum 'default' do
71
143
  RailClass.fallback
72
144
  end
data/lib/rail_trip/characterization.rb CHANGED
@@ -1,15 +1,36 @@
1
+ # Rail trip's characterization is implemented using a domain-specific language
2
+ # provided by [Characterizable](http://github.com/seamusabshere/characterizable).
1
3
  require 'characterizable'
2
4
 
3
5
  module BrighterPlanet
4
6
  module RailTrip
7
+
8
+ #### Rail trip: characterization
9
+ # This module is used by [Brighter Planet](http://brighterplanet.com)'s
10
+ # [emission estimate service](http://carbon.brighterplanet.com) to provide
11
+ # curated attributes for the carbon model execution environment.
12
+ #
13
+ # For more information see:
14
+ #
15
+ # * [API documentation](http://carbon.brighterplanet.com/rail_trips/options)
16
+ # * [Source code](http://github.com/brighterplanet/rail_trip)
17
+ #
5
18
  module Characterization
6
19
  def self.included(base)
20
+ ##### The characterization
7
21
  base.send :include, Characterizable
22
+
23
+ # This `characterize` block encapsulates the characterization. Typically
24
+ # emitter models will be backed by ActiveRecord, which will provide
25
+ # these attributes accessors based on database schema. The characteristics
26
+ # listed here define the standard public API to RailTrip.
8
27
  base.characterize do
9
28
  has :rail_class
10
29
  has :duration, :measures => :time
11
30
  has :distance_estimate, :trumps => :duration, :measures => :length
12
31
  end
32
+
33
+ # Additional characteristics are gleaned from the carbon model.
13
34
  base.add_implicit_characteristics
14
35
  end
15
36
  end
data/lib/rail_trip/data.rb CHANGED
@@ -1,10 +1,25 @@
1
+ # Rail trip's persistence schema is defined using a domain-specific language
2
+ # provided by [Data Miner](http://github.com/seamusabshere/data_miner).
1
3
  require 'data_miner'
2
4
 
3
5
  module BrighterPlanet
4
6
  module RailTrip
7
+
8
+ #### Rail trip: persistence schema
9
+ # This module is used by [Brighter Planet](http://brighterplanet.com)'s
10
+ # [emission estimate service](http://carbon.brighterplanet.com) to provide
11
+ # a persistence structure, which is in turn used by the [characterization](characterization.html).
12
+ #
13
+ # For more information see:
14
+ #
15
+ # * [API documentation](http://carbon.brighterplanet.com/rail_trips/options)
16
+ # * [Source code](http://github.com/brighterplanet/rail_trip)
17
+ #
5
18
  module Data
6
19
  def self.included(base)
20
+ ##### The carbon model
7
21
  base.data_miner do
22
+ # This `schema` block encapsulates the persistence schema.
8
23
  schema do
9
24
  string 'name'
10
25
  date 'date'
@@ -13,9 +28,10 @@ module BrighterPlanet
13
28
  string 'rail_class_id'
14
29
  end
15
30
 
16
- process "pull dependencies" do
17
- run_data_miner_on_belongs_to_associations
18
- end
31
+ # This `process` block indicates that RailTrip's associated classes
32
+ # should populate themselves according to their own DataMiner
33
+ # instructions.
34
+ process :run_data_miner_on_belongs_to_associations
19
35
  end
20
36
  end
21
37
  end
data/lib/rail_trip/summarization.rb CHANGED
@@ -1,10 +1,27 @@
1
+ # Rail trip's summarization strategy is implemented using a domain-specific language
2
+ # provided by [Summary Judgement](http://github.com/rossmeissl/summary_judgement).
1
3
  require 'summary_judgement'
2
4
 
3
5
  module BrighterPlanet
4
6
  module RailTrip
7
+
8
+ #### Rail trip: summarization strategy
9
+ # This module is used by [Brighter Planet](http://brighterplanet.com)'s
10
+ # [emission estimate service](http://carbon.brighterplanet.com) to provide
11
+ # summaries for rail trips.
12
+ #
13
+ # For more information see:
14
+ #
15
+ # * [API documentation](http://carbon.brighterplanet.com/rail_trips/options)
16
+ # * [Source code](http://github.com/brighterplanet/rail_trip)
17
+ #
5
18
  module Summarization
6
19
  def self.included(base)
20
+ ##### The carbon model
7
21
  base.extend SummaryJudgement
22
+
23
+ # This `summarize` block encapsulates the summarization strategy, including
24
+ # terminology and inflection preference.
8
25
  base.summarize do |has|
9
26
  has.adjective lambda { |rail_trip| "#{rail_trip.distance_estimate_in_miles.adaptive_round(1)}-mile" }, :if => :distance_estimate
10
27
  has.adjective lambda { |rail_trip| "#{rail_trip.duration}-hour" }, :if => :duration
metadata CHANGED
@@ -1,13 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: rail_trip
3
3
  version: !ruby/object:Gem::Version
4
- hash: 13
4
+ hash: 11
5
5
  prerelease: false
6
6
  segments:
7
7
  - 0
8
8
  - 0
9
- - 9
10
- version: 0.0.9
9
+ - 10
10
+ version: 0.0.10
11
11
  platform: ruby
12
12
  authors:
13
13
  - Andy Rossmeissl
@@ -19,31 +19,30 @@ autorequire:
19
19
  bindir: bin
20
20
  cert_chain: []
21
21
 
22
- date: 2010-08-12 00:00:00 -04:00
22
+ date: 2010-09-08 00:00:00 -05:00
23
23
  default_executable:
24
24
  dependencies:
25
25
  - !ruby/object:Gem::Dependency
26
- type: :development
27
- prerelease: false
28
26
  name: activerecord
29
- version_requirements: &id001 !ruby/object:Gem::Requirement
27
+ prerelease: false
28
+ requirement: &id001 !ruby/object:Gem::Requirement
30
29
  none: false
31
30
  requirements:
32
31
  - - "="
33
32
  - !ruby/object:Gem::Version
34
- hash: -1848230024
33
+ hash: 299253624
35
34
  segments:
36
35
  - 3
37
36
  - 0
38
37
  - 0
39
38
  - beta4
40
39
  version: 3.0.0.beta4
41
- requirement: *id001
42
- - !ruby/object:Gem::Dependency
43
40
  type: :development
44
- prerelease: false
41
+ version_requirements: *id001
42
+ - !ruby/object:Gem::Dependency
45
43
  name: bundler
46
- version_requirements: &id002 !ruby/object:Gem::Requirement
44
+ prerelease: false
45
+ requirement: &id002 !ruby/object:Gem::Requirement
47
46
  none: false
48
47
  requirements:
49
48
  - - ">="
@@ -56,12 +55,12 @@ dependencies:
56
55
  - beta
57
56
  - 2
58
57
  version: 1.0.0.beta.2
59
- requirement: *id002
60
- - !ruby/object:Gem::Dependency
61
58
  type: :development
62
- prerelease: false
59
+ version_requirements: *id002
60
+ - !ruby/object:Gem::Dependency
63
61
  name: cucumber
64
- version_requirements: &id003 !ruby/object:Gem::Requirement
62
+ prerelease: false
63
+ requirement: &id003 !ruby/object:Gem::Requirement
65
64
  none: false
66
65
  requirements:
67
66
  - - "="
@@ -72,12 +71,12 @@ dependencies:
72
71
  - 8
73
72
  - 3
74
73
  version: 0.8.3
75
- requirement: *id003
76
- - !ruby/object:Gem::Dependency
77
74
  type: :development
78
- prerelease: false
75
+ version_requirements: *id003
76
+ - !ruby/object:Gem::Dependency
79
77
  name: jeweler
80
- version_requirements: &id004 !ruby/object:Gem::Requirement
78
+ prerelease: false
79
+ requirement: &id004 !ruby/object:Gem::Requirement
81
80
  none: false
82
81
  requirements:
83
82
  - - "="
@@ -88,12 +87,12 @@ dependencies:
88
87
  - 4
89
88
  - 0
90
89
  version: 1.4.0
91
- requirement: *id004
92
- - !ruby/object:Gem::Dependency
93
90
  type: :development
94
- prerelease: false
91
+ version_requirements: *id004
92
+ - !ruby/object:Gem::Dependency
95
93
  name: rake
96
- version_requirements: &id005 !ruby/object:Gem::Requirement
94
+ prerelease: false
95
+ requirement: &id005 !ruby/object:Gem::Requirement
97
96
  none: false
98
97
  requirements:
99
98
  - - ">="
@@ -102,12 +101,12 @@ dependencies:
102
101
  segments:
103
102
  - 0
104
103
  version: "0"
105
- requirement: *id005
106
- - !ruby/object:Gem::Dependency
107
104
  type: :development
108
- prerelease: false
105
+ version_requirements: *id005
106
+ - !ruby/object:Gem::Dependency
109
107
  name: rdoc
110
- version_requirements: &id006 !ruby/object:Gem::Requirement
108
+ prerelease: false
109
+ requirement: &id006 !ruby/object:Gem::Requirement
111
110
  none: false
112
111
  requirements:
113
112
  - - ">="
@@ -116,12 +115,12 @@ dependencies:
116
115
  segments:
117
116
  - 0
118
117
  version: "0"
119
- requirement: *id006
120
- - !ruby/object:Gem::Dependency
121
118
  type: :development
122
- prerelease: false
119
+ version_requirements: *id006
120
+ - !ruby/object:Gem::Dependency
123
121
  name: rspec
124
- version_requirements: &id007 !ruby/object:Gem::Requirement
122
+ prerelease: false
123
+ requirement: &id007 !ruby/object:Gem::Requirement
125
124
  none: false
126
125
  requirements:
127
126
  - - "="
@@ -134,39 +133,40 @@ dependencies:
134
133
  - beta
135
134
  - 17
136
135
  version: 2.0.0.beta.17
137
- requirement: *id007
138
- - !ruby/object:Gem::Dependency
139
136
  type: :development
140
- prerelease: false
137
+ version_requirements: *id007
138
+ - !ruby/object:Gem::Dependency
141
139
  name: sniff
142
- version_requirements: &id008 !ruby/object:Gem::Requirement
140
+ prerelease: false
141
+ requirement: &id008 !ruby/object:Gem::Requirement
143
142
  none: false
144
143
  requirements:
145
- - - "="
144
+ - - ~>
146
145
  - !ruby/object:Gem::Version
147
- hash: 3
146
+ hash: 15
148
147
  segments:
149
148
  - 0
150
- - 0
151
- - 14
152
- version: 0.0.14
153
- requirement: *id008
149
+ - 1
150
+ - 10
151
+ version: 0.1.10
152
+ type: :development
153
+ version_requirements: *id008
154
154
  - !ruby/object:Gem::Dependency
155
- type: :runtime
156
- prerelease: false
157
155
  name: emitter
158
- version_requirements: &id009 !ruby/object:Gem::Requirement
156
+ prerelease: false
157
+ requirement: &id009 !ruby/object:Gem::Requirement
159
158
  none: false
160
159
  requirements:
161
- - - ">="
160
+ - - ~>
162
161
  - !ruby/object:Gem::Version
163
- hash: 113
162
+ hash: 13
164
163
  segments:
165
164
  - 0
166
165
  - 0
167
- - l
168
- version: 0.0.l
169
- requirement: *id009
166
+ - 9
167
+ version: 0.0.9
168
+ type: :runtime
169
+ version_requirements: *id009
170
170
  description: A software model in Ruby for the greenhouse gas emissions of an rail_trip
171
171
  email: andy@rossmeissl.net
172
172
  executables: []