amee-data-abstraction 1.0.0

data/examples/_calculator_form.erb

@@ -0,0 +1,27 @@
+<% form_id = "drill-form-#{rand(1e8)}" %>
+<% form_tag({:action=>nil},{:id=>form_id}) do%>
+  <%= hidden_field_tag 'form_id', form_id %>
+  <table>
+    <%@calculation.drills.each_value do |input|%>
+       <tr>
+        <td><%=label :entry,input.label,input.name%></td>
+        <td>
+          <%= select_tag "entry[#{input.label}]",
+            options_for_select(input.options_for_select,input.set? ? input.value : nil),:disabled=>input.disabled?%>
+        </td>
+      </tr>
+    <%end%>
+    <%@calculation.profiles.each_value do |input|%>
+      <tr><td><%=label :entry,input.label,input.name%></td><td><%= text_field :entry, input.label, "size" => 20, :value => input.value_if_given %></td></tr>
+    <%end%>
+    <%@calculation.chosen_outputs.each_value do |result|%>
+      <tr><td><%=label :entry,result.label,result.name%></td><td><%= result.value_if_given %></td></tr>
+    <%end%>
+  </table>
+<%end%>
+<%= observe_form form_id, :url => {:action => 'result'}%>
+<% javascript_tag do %>
+  $('#<%=form_id%>').submit(function() {
+  return false;
+  });
+<%end%>

data/examples/calculation_controller.rb

@@ -0,0 +1,16 @@
+class CalculationController < ApplicationController
+  def index
+    @calculations=Calculations.calculations.values
+  end
+
+  def enter
+    @calculation=Calculations[params[:calculation]]
+  end
+
+  def result
+    @calculation=Calculations[params[:calculation]].clone
+    @calculation.choose!(params['entry'])
+    @calculation.calculate!
+  end
+
+end

data/init.rb

@@ -0,0 +1,4 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+require File.dirname(__FILE__) + "/rails/init"

data/lib/amee-data-abstraction.rb

@@ -0,0 +1,30 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+require 'amee'
+require 'uuidtools'
+require 'quantify'
+
+require File.dirname(__FILE__) + '/core-extensions/class'
+require File.dirname(__FILE__) + '/core-extensions/ordered_hash'
+require File.dirname(__FILE__) + '/core-extensions/hash'
+require File.dirname(__FILE__) + '/core-extensions/proc'
+require File.dirname(__FILE__) + '/config/amee_units'
+require File.dirname(__FILE__) + '/amee-data-abstraction/exceptions'
+require File.dirname(__FILE__) + '/amee-data-abstraction/terms_list'
+require File.dirname(__FILE__) + '/amee-data-abstraction/calculation'
+require File.dirname(__FILE__) + '/amee-data-abstraction/ongoing_calculation'
+require File.dirname(__FILE__) + '/amee-data-abstraction/prototype_calculation'
+require File.dirname(__FILE__) + '/amee-data-abstraction/calculation_set'
+require File.dirname(__FILE__) + '/amee-data-abstraction/term'
+require File.dirname(__FILE__) + '/amee-data-abstraction/input'
+require File.dirname(__FILE__) + '/amee-data-abstraction/drill'
+require File.dirname(__FILE__) + '/amee-data-abstraction/profile'
+require File.dirname(__FILE__) + '/amee-data-abstraction/usage'
+require File.dirname(__FILE__) + '/amee-data-abstraction/output'
+require File.dirname(__FILE__) + '/amee-data-abstraction/metadatum'
+
+module AMEE::DataAbstraction
+  # Connection to AMEE server.
+  mattr_accessor :connection
+end

data/lib/amee-data-abstraction/calculation.rb

@@ -0,0 +1,236 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Class: AMEE::DataAbstraction::Calculation
+
+module AMEE
+  module DataAbstraction
+
+    # Base class providing attributes and methods for representing a calculation
+    # which can be made using the AMEE platform. An instance of <i>Calculation</i>
+    # will typically be associated with a specific AMEE category.
+    #
+    # Instances of <i>Calculation</i> are represented by several primary attributes:
+    #
+    #   label::       Symbol representing the unique, machine-readable name for the
+    #                 calculation
+    #
+    #   name::        String representing a human-readable name for the calculation
+    #
+    #   path::        String representing the AMEE platform path to the data category
+    #                 which is associated with <tt>self</tt>
+    #
+    #   fixed_usage:: String representing the AMEE platform path for the usage to
+    #                 be used by <tt>self</tt>, if defined
+    #
+    # An instance of <i>Calculation</i> also holds an arbitrary number of objects
+    # of the class <i>Term</i>. These represent values associated with the
+    # calculation, e.g. inputs, outputs, metadatum, etc. These can be accessed
+    # using the <tt>#terms</tt> methods or the term subset methods provided by
+    # the <tt>TermsList</tt> class (e.g. <tt>#profiles</tt>, <tt>#visible</tt>)
+    #
+    # Two classes inherit the <i>Calculation</i> class:
+    # * <i>PrototypeCalculation</i> : provides a templating for a specific calculation
+    #   type with defined, but blank, terms (i.e. inputs, outputs, etc.)
+    #
+    # * <i>OngoingCalculation</i> : represents a particular calculation - possibly
+    #   incomplete - which can be updated, submitted for calculation, and saved
+    #
+    class Calculation
+
+      public
+
+      # Symbol representing the unique, machine-readable name for <tt>self</tt>.
+      # Set a value by passing an argument. Retrieve a value by calling without
+      # an argument, e.g.,
+      #
+      #  my_calculation.label :fuel
+      #
+      #  my_calculation.label               #=> :fuel
+      #
+      attr_property :label
+
+      # String representing a human-readable name for <tt>self</tt>. Set a
+      # value by passing an argument. Retrieve a value by calling without an
+      # argument, e.g.,
+      #
+      #  my_calculation.name 'Domestic fuel consumption'
+      #
+      #  my_calculation.name               #=> 'Domestic fuel consumption'
+      #
+      attr_property :name
+
+      # String representing the AMEE platform path to the data category which is
+      # associated with <tt>self</tt>. Set a value by passing an argument. Retrieve
+      # a value by calling without an argument, e.g.,
+      #
+      #  my_calculation.path '/some/path/in/amee/'
+      #
+      #  my_calculation.path               #=> '/some/path/in/amee/'
+      #
+      attr_property :path
+
+      # String representing the AMEE platform path for the usage to be used by
+      # <tt>self</tt>, if defined. Set a value by passing an argument. Retrieve
+      # a value by calling without an argument, e.g.,
+      #
+      #  my_calculation.fixed_usage 'byMass'
+      #
+      #  my_calculation.fixed_usage        #=> 'byMass'
+      #
+      attr_property :fixed_usage
+
+      # Calculations contain a list of "terms" of the base class <i>Term</i>,
+      # representing inputs, outputs, metadatum, etc. which are associated with
+      # <tt>self</tt>.
+      # 
+      # Returns all associated terms as an instance of the <i>TermsList</i> class
+      #
+      def terms
+        TermsList.new(@contents.values)
+      end
+
+      # Retrieve the terms associated with <tt>self</tt> as a hash from labels to terms.
+      attr_accessor :contents
+
+      # Shorthand method for retrieving the term assocaited with <tt>self</tt> which has a
+      # label matching <tt>sym</tt>
+      #
+      def [](sym)
+        @contents[sym.to_sym]
+      end
+
+      # Syntactic sugar to enable the return of a subset of associated terms according
+      # to their type or status (e.g. drills, profiles, set, unset, visible). See
+      # <i>TermsList::Selectors</i> for valid variants
+      #
+      TermsList::Selectors.each do |sel|
+        delegate sel,:to=>:terms
+      end
+
+      # Prettyprint a string representation of <tt>self</tt>, together with associated terms
+      def inspect
+        elements = {:label => label.inspect, :terms => terms.map{|t| "<#{t.class.name.demodulize} label:#{t.label}, value:#{t.value.inspect}>"}}
+        attr_list = elements.map {|k,v| "#{k}: #{v}" } * ', '
+        "<#{self.class.name} #{attr_list}>"
+      end
+
+      def initialize_copy(source)
+        super
+        @contents=ActiveSupport::OrderedHash.new
+        source.contents.each do |k,v|
+          @contents[k]=v.clone
+          @contents[k].parent=self
+        end
+      end
+
+      # Return a string representing the AMEE Explorer URL which is assocaited
+      # with <tt>self</tt>
+      #
+      def explorer_url
+         "http://explorer.amee.com/categories#{path}"
+      end
+       
+      protected
+
+      def initialize
+        @contents=ActiveSupport::OrderedHash.new
+      end
+
+      # Methods which will be memoized at application start, as they do not
+      # change over application instance lifetime
+      #
+      AmeeMemoised=[:amee_data_category, :amee_item_definition, :amee_ivds,
+        :amee_return_values, :amee_usages]
+
+      # Return all the values of the memoized quantities
+      def saved_amee
+        AmeeMemoised.map{|x|instance_variable_get("@#{x.to_s}")}
+      end
+
+      # Save the memoized quantities
+      def save_amee(values)
+        AmeeMemoised.zip(values).each do |prop,val|
+          instance_variable_set("@#{prop.to_s}",val)
+        end
+      end
+
+      private
+
+      # Return the global <i>AMEE::Connection</i> object. This is configured in
+      # /config/amee.yml
+      #
+      def connection
+        AMEE::DataAbstraction.connection
+      end
+
+      # Return the <i>AMEE::Data::Category</i> object associated with <tt>self</tt>
+      def amee_data_category
+        @amee_data_category||=AMEE::Data::Category.get(connection, "/data#{path}")
+      end
+
+      # Return the <i>AMEE::Admin::ItemDefinition</i> object associated with <tt>self</tt>
+      def amee_item_definition
+        @amee_item_definition||=amee_data_category.item_definition
+      end
+
+      # Return the <i>AMEE::Admin::ReturnValueDefinitionList</i> object associated
+      # with <tt>self</tt>. This represents each of the return value definitions which are
+      # associated with the calculation
+      #
+      def amee_return_values
+        @amee_return_values||=AMEE::Admin::ReturnValueDefinitionList.new(connection,amee_item_definition.uid)
+      end
+
+      # Return the instance of <i>Term</i> class associated with <tt>self</tt> and contains
+      # a path attribute matching <tt>path</tt>, e.g.
+      #
+      #   my_calculation.by_path('distance') #=> <AMEE::DataAbstraction::Profile ... >
+      #
+      #   my_calculation.by_path('type')     #=> <AMEE::DataAbstraction::Drill ... >
+      #
+      def by_path(path)
+        terms.detect { |v| v.path==path }
+      end
+
+      # Return the instance of <i>Drill</i> class associated with <tt>self</tt> and contains
+      # a path attribute matching <tt>path</tt>, e.g.
+      # 
+      #   my_calculation.by_path('type')     #=> <AMEE::DataAbstraction::Drill ... >
+      #
+      def drill_by_path(path)
+        drills.detect { |v| v.path==path }
+      end
+
+      public
+
+      # Return the <i>AMEE::Admin::ItemValueDefinitionList</i> object associated
+      # with <tt>self</tt>. This represents each of the item value definitions which are
+      # associated with the calculation
+      #
+      def amee_ivds
+        @amee_ivds||=amee_item_definition.item_value_definition_list.select{|x|x.versions.include?("2.0")}
+      end
+
+      # Returns a String representing the AMEE platform path for the usage currently
+      # used by <tt>self</tt>. If not usage is defined, returns nil
+      #
+      #   my_calculation.current_usage      #=> 'byMass'
+      #
+      def current_usage
+        usages.empty? ? fixed_usage : usages.first.value
+      end
+
+      # Returns an Array containing the AMEE platform paths for all valid usage
+      # available to <tt>self</tt> according to those defined under #item_definition. If
+      # no usage(s) is defined, returns nil, e.g.
+      #
+      #   my_calculation.amee_usages      #=> [ 'byMass', 'byEnergy' ]
+      #
+      def amee_usages
+        @amee_usages||=amee_item_definition.usages
+      end
+
+    end
+  end
+end

data/lib/amee-data-abstraction/calculation_set.rb

@@ -0,0 +1,101 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Class: AMEE::DataAbstraction::CalculationSet
+
+module AMEE
+  module DataAbstraction
+    
+    # The <i>CalculationSet</i> class represents a collection of prototype
+    # calculations (of the class <i>ProtptypeCalculation</i>.
+    #
+    # Prototype calculations are contained within the @calculations instance variable
+    # ordered hash. Calculations can be added manually to the @calculations hash or
+    # initialized in place using the <tt>#calculation</tt> method which takes an
+    # options hash or block for specifying the prototype calculation properties.
+    #
+    # Typical usage is to initialize the <i>CalculationSet</i> and its daughter
+    # prototype calculations together using block syntax, thus:
+    #
+    #   Calculations = CalculationSet.new {
+    #
+    #     calculation {
+    #       label :electricity
+    #       path "/some/path/for/electricity"
+    #       ...
+    #     }
+    #
+    #     calculation {
+    #       label :transport
+    #       path "a/transport/path"
+    #       ...
+    #     }
+    #
+    #     ...
+    #   }
+    #
+    class CalculationSet
+
+      # Initialize a <i>CalculationSet</i> with a "DSL" block, i.e. a block to be
+      # evaluated in the context of the instantiated CalculationSet
+      #
+      def initialize(options={},&block)
+        @calculations=ActiveSupport::OrderedHash.new
+        @all_blocks=[]
+        @all_options={}
+        instance_eval(&block) if block
+      end
+
+      # Access the @calculations instance variable ordered hash. Keys are labels
+      # assocaited with each prototype calculation; values are the instantiated
+      # <i>PrototypeCalculation</i> objects
+      #
+      attr_accessor :calculations
+
+      # Shorthand method for returning the prototype calculation which is represented
+      # by a label matching <tt>sym</tt>
+      #
+      def [](sym)
+        @calculations[sym.to_sym]
+      end
+
+      # Instantiate a <i>PrototypeCalculation</i> within this calculation set,
+      # initializing with the supplied DSL block to be evaluated in the context
+      # of the newly created calculation
+      #
+      def calculation(options={},&block)
+        new_content=PrototypeCalculation.new(options.merge(@all_options),&block)
+        @all_blocks.each {|all_block| new_content.instance_eval(&all_block) }
+        new_content.name new_content.label.to_s.humanize unless new_content.name
+        @calculations[new_content.label]=new_content
+      end
+
+      # Append the supplied block to the DSL block of ALL calculations in this
+      # calculation set. This is useful for configuration which is required
+      # across all calculations (e.g. overriding human readable names or adding
+      # globally applicable metadatum)
+      #
+      def all_calculations(options={},&dsl_block)
+        @all_blocks.push dsl_block
+        @all_options.merge(options)
+      end
+
+      # Instantiate several prototype calculations, by loading each possible usage
+      # for the category with path given in <tt>apath</tt>.
+      # 
+      # Each instantiated calculation is customised on the basis of the supplied
+      # DSL block. The usage is given as a parameter to the DSL block
+      #
+      def calculations_all_usages(apath,options={},&dsl_block)
+        dummycalc=PrototypeCalculation.new{path apath}
+        dummycalc.amee_usages.each do |usage|
+          calculation(options){
+            path apath
+            instance_exec(usage,&dsl_block)
+          }
+        end
+
+      end
+    end
+  end
+end

data/lib/amee-data-abstraction/drill.rb

@@ -0,0 +1,63 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Class: AMEE::DataAbstraction::Drill
+
+module AMEE
+  module DataAbstraction
+
+    # Subclass of <tt>Input</tt> providing methods and attributes appropriate for
+    # representing AMEE drill down choices and selections specifically
+    #
+    class Drill < Input
+
+      public
+
+      # Returns <tt>true</tt> if the UI element of <tt>self</tt> is disabled.
+      # Otherwise, returns <tt>false</tt>.
+      #
+      # A drill is considered disabled if it either (1) explicitly set using the
+      # <tt>#disable!</tt> method; (2) has a <i>fixed</i> value; or (3) is not the
+      # next drill (because drill should be chosen in order).
+      #
+      def disabled?
+        super || (!set? && !next?)
+      end
+
+      # Initialization of <i>Drill</i> objects follows that of the parent
+      # <i>Input</i> class. The <tt>interface</tt> attribute of <tt>self</tt> is
+      # set to <tt>:drop_down</tt> by default for <tt>Drill</tt> instances, but
+      # can be manually configured if required.
+      #
+      def initialize(options={},&block)
+        interface :drop_down
+        super
+        choice_validation_message
+      end
+
+      private
+
+      # Returns <tt>true</tt> if the value set for <tt>self</tt> is one of the
+      # available choices. Otherwise, returns <tt>false</tt>.
+      #
+      def valid?
+        super && (choices.include? value)
+      end
+
+      # Returns the list of available choices for <tt>self</tt>.
+      def choices
+        c=parent.amee_drill(:before=>label).choices
+        c.length==1 ? [value] : c #Intention is to get autodrilled, drill will result in a UID
+      end
+
+      # Returns <tt>true</tt> if <tt>self</tt> is the "first unset" drill, i.e.
+      # the one which should be set next
+      #
+      def next?
+        unset? && parent.drills.before(label).all?(&:set?)
+      end
+
+    end
+  end
+end
+