Class: AMEE::DataAbstraction::PrototypeCalculation

Inherits:
Calculation
  • Object
show all
Defined in:
lib/amee-data-abstraction/prototype_calculation.rb

Overview

The PrototypeCalculation class represents a template for a potential calculation within the AMEE platfom.

The class inherits from the Calculation class and is therefore primarly characterised by the label, name, and path attributes, as well as an associated instance of the TermsList class which represents each of the values (input, outputs, metdata) involved in the calculation. Unlike the OngoingCalculation, the terms associated with an instance of PrototypeCalculation will typically contains blank (nil) values.

Objects of the class <i>PrototypeCalculation</tt> are typically instantiated using block (‘DSL’) syntax, within which each of the attributes and associated terms are defined. Thus,

calculation = PrototypeCalculation.new {

  label :electricity
  name "Domestic electricity consumption"
  path "some/path/in/amee"
  drill { ... }
  profile { ... }
  ...

}

Instance Attribute Summary

Attributes inherited from Calculation

#contents

Instance Method Summary collapse

Methods inherited from Calculation

#[], #amee_ivds, #amee_usages, #current_usage, #discover_url, #explorer_url, #initialize_copy, #inspect, #terms

Constructor Details

#initialize(options = {}, &block) ⇒ PrototypeCalculation

Initialize a new instance of PrototypeCalculation.

The calculation can be configured in place by passing a block (evaluated in the context of the new instance) which defines the calculation properties using the macro-style instance helper methods.

calculation = PrototypeCalculation.new {

  label :transport
  path "some/other/path/in/amee"
  terms_from_amee
  metadatum { ... }
  start_and_end_dates
  ...

}



55
56
57
58
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 55

def initialize(options={},&block)
  super()
  instance_eval(&block) if block
end

Instance Method Details

#all_drills ⇒ Object

Helper method for automatically instantiating Drill class term objects representing all drill down choices based on those associated with the AMEE platform category with which self corresponds.



129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 129

def all_drills
  # Need to use #drill_downs rather than simply finding drills
  # directly from #amee_ivds in order to establish drill order
  amee_item_definition.drill_downs.each do |apath|
    amee_ivds.each do |ivd|
      next unless ivd.path == apath
      drill {
        path ivd.path
        name ivd.name
      }
    end
  end
end

#all_outputs ⇒ Object

Helper method for automatically instantiating Output class term objects representing all return values based on those associated with the AMEE platform category with which self corresponds.

Each term is instantiated with path, default_unit and default_per_unit attributes corresponding to those defined in the AMEE platform.



165
166
167
168
169
170
171
172
173
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 165

def all_outputs
  amee_return_values.each do |rvd|
    output {
      path rvd.name
      default_unit rvd.unit
      default_per_unit rvd.perunit
    }
  end
end

#all_profiles ⇒ Object

Helper method for automatically instantiating Profile class term objects representing all profile item values based on those associated with the AMEE platform category with which self corresponds.

Each term is instantiated with path, name, choices, default_unit and default_per_unit attributes corresponding to those defined in the AMEE platform.



151
152
153
154
155
156
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 151

def all_profiles
  amee_ivds.each do |ivd|
    next unless ivd.profile?
    construct_from_ivd(Profile,ivd)
  end
end

#begin_calculation ⇒ Object

Instantiate an OngoingCalculation based on this prototype, ready for communication with AMEE.



298
299
300
301
302
303
304
305
306
307
308
309
310
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 298

def begin_calculation
  result=OngoingCalculation.new
  contents.each do |k,v|
    result.contents[k]=v.clone
    result.contents[k].parent=result
  end
  result.path path
  result.name name
  result.label label
  result.fixed_usage fixed_usage
  result.save_amee saved_amee
  result
end

#correcting(label, &block) ⇒ Object

Helper method for reopening and modifying the definition of the term with the label attribute matching label. Modification is specified in the passed block, which is evaluated in the context of the respective term instance.

This is typically used to override (customize) the attributes and behaviour of term autoloaded from the AMEE platform using one of the instance helper methods of self.



291
292
293
294
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 291

def correcting(label,&block)
  return unless contents[label]
  contents[label].instance_eval(&block)
end

#drill(options = {}, &block) ⇒ Object

Associate a new instance of the Drill class (subclass of the Term class) with self, for representing an AMEE drill down choice

The newly instantiated Term object is configured according to the (‘DSL’) block passed in.

my_protptype.drill {
  label :fuel_type
  path 'fuelType'
  fixed 'diesel'
}



88
89
90
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 88

def drill(options={},&block)
  construct(Drill,options,&block)
end

#metadatum(options = {}, &block) ⇒ Object

Associate a new instance of the Metadatum class (subclass of the Term class) with self, for representing arbitrary metadata which is to be associated with each calculation. These may represent unique references to location, equipment (vehicles, furnaces), reporting periods, for example.

The newly instantiated Term object is configured according to the (‘DSL’) block passed in.

my_protptype.metadatum {
  label :reporting_period
  value "July 2010"
}



121
122
123
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 121

def metadatum(options={},&block)
  construct(Metadatum,options,&block)
end

#output(options = {}, &block) ⇒ Object

Associate a new instance of the Output class (subclass of the Term class) with self, for representing an AMEE return value

The newly instantiated Term object is configured according to the (‘DSL’) block passed in.

my_protptype.output {
  label :co2
  path 'CO2'
}



103
104
105
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 103

def output(options={},&block)
  construct(Output,options,&block)
end

#profile(options = {}, &block) ⇒ Object

Associate a new instance of the Profile class (subclass of the Term class) with self, for representing an AMEE profile item input

The newly instantiated Term object is configured according to the (‘DSL’) block passed in.

my_protptype.profile {
  label :energy_used
  path 'energyUsed'
  default_unit :kWh
}



72
73
74
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 72

def profile(options={},&block)
  construct(Profile,options,&block)
end

#profiles_from_usage(usage) ⇒ Object

Helper method for automatically instantiating Profile class term objects representing only the profile item values associated with a particular usage (specified by usage) for the AMEE platform category with which self corresponds.

This method does not permit dynamic usage switching during run-time.

Each term is instantiated with path, name, choices, default_unit and default_per_unit attributes corresponding to those defined in the AMEE platform.



186
187
188
189
190
191
192
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 186

def profiles_from_usage(usage)
  self.fixed_usage usage
  amee_ivds.each do |ivd|
    next unless ivd.profile?
    construct_from_ivd(Profile,ivd) if ivd.compulsory?(usage) || ivd.optional?(usage)
  end
end

#start_and_end_dates ⇒ Object

Helper method for automatically instantiating Metadatum class term objects explicitly configured for storing start and end dates for an AMEE platform profile item.



265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 265

def start_and_end_dates
  metadatum {
    path 'start_date'
    name 'Start date'
    interface :date
    type :datetime
    validation lambda{|v| v.is_a?(Time) || v.is_a?(DateTime) || (v.is_a?(String) && Date.parse(v) rescue false)}
  }
  metadatum {
    path 'end_date'
    name 'End date'
    interface :date
    type :datetime
    validation lambda{|v| v.is_a?(Time) || v.is_a?(DateTime) || (v.is_a?(String) && Date.parse(v) rescue false)}
  }
end

#terms_from_amee(usage = nil) ⇒ Object

Helper method for automatically instantiating Profile, Drill and Output class term objects representing all profile item values, drill choices and return values associated with the AMEE platform category with which self corresponds.

Optionally, instantiate only those profile terms corresponding to a particular usage by passing the path of the required usage as an argument. The latter case does not allow dynamic usage switching at run-time.

Each term is instantiated with path, name, choices, default_unit and default_per_unit attributes corresponding to those defined in the AMEE platform.



207
208
209
210
211
212
213
214
215
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 207

def terms_from_amee(usage=nil)
  all_drills
  if usage
    profiles_from_usage(usage)
  else
    all_profiles
  end
  all_outputs
end

#terms_from_amee_dynamic_usage(ausage) ⇒ Object

Helper method for automatically instantiating Profile, Drill and Output class term objects representing all profile item values, drill choices and return values associated with the AMEE platform category with which self corresponds.

Also automatically defines a usage term for the usage represented by ausage to enable dynamic usage switching. The profile terms associated with the specified usage are automatically activated and deactivated as appropriate, but this can be switched at run-time by changing the value of the instantiated usage term.

Each term is instantiated with path, name, choices, default_unit and default_per_unit attributes (where appropriate) corresponding to those defined in the AMEE platform.



232
233
234
235
236
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 232

def terms_from_amee_dynamic_usage(ausage)
  all_drills
  usage{ value ausage}
  all_outputs
end

#usage(options = {}, &block) ⇒ Object

Helper method for automatically instantiating Profile class term objects representing all profile item values associated with the AMEE platform category represented by self, and instantiating a new instance of the Usage term class which can be used for dynamically switching usages at run-time.

Each term is instantiated with path, name, choices, default_unit and default_per_unit attributes corresponding to those defined in the AMEE platform.

The newly instantiated Usage object can be configured in place according to the (‘DSL’) block passed in, e.g.,

my_protptype.usage {
  inactive :disabled
  value nil
}



256
257
258
259
 
# File 'lib/amee-data-abstraction/prototype_calculation.rb', line 256

def usage(options={},&block)
  all_profiles
  construct(Usage,options.merge(:first=>true),&block)
end