rail_trip 0.0.9 → 0.0.10

Sign up to get free protection for your applications and to get access to all the features.
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: []