amee-analytics 1.0.1

data/.rvmrc

@@ -0,0 +1 @@
+rvm 1.8.7@amee-analytics

data/CHANGELOG.txt

@@ -0,0 +1,4 @@
+= Changelog
+
+== 1.0.0
+  * Initial public release

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+
+# Dependencies
+gem "amee-data-abstraction","~> 1.1"
+gem "amee-data-persistence","~> 1.1"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "jeweler", "~> 1.6.4"
+  gem 'rspec', '1.3.0'
+  gem 'rcov'
+  gem 'rspec_spinner', '1.1.3'
+  gem 'flexmock', '> 0.8.6'
+  gem 'activerecord', '~> 2.3.5'
+end

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2011, AMEE UK Ltd.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+    Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+    Neither the name of AMEE UK Ltd nor the names of its contributors may be
+    used to endorse or promote products derived from this software without
+    specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.txt

@@ -0,0 +1,94 @@
+== amee-analytics
+
+The amee-analytics gem provides support for handling collections of the class
+<i>AMEE::DataAbstraction::OngoingCalculation</i> and performing analytical
+operations across the collection.
+
+Licensed under the BSD 3-Clause license (See LICENSE.txt for details)
+
+Authors: James Smith, Andrew Berkeley, George Palmer
+
+Copyright: Copyright (c) 2011 AMEE UK Ltd
+
+Homepage: http://github.com/AMEE/amee-analytics
+
+Documentation: http://rubydoc.info/gems/amee-analytics
+
+== INSTALLATION
+
+ gem install amee-analytics
+
+== REQUIREMENTS
+
+ * ruby 1.8.7
+ * rubygems >= 1.5
+
+ All gem requirements should be installed as part of the rubygems installation process
+ above, but are listed here for completeness.
+
+ * amee-data-abstraction ~> 1.1
+ * amee-data-persistence ~> 1.1
+ 
+== USAGE
+
+The library extends a number of classes within the <i>AMEE::DataAbstraction</i>
+module:
+
+1. <i>AMEE::DataAbstraction::CalculationCollection</i> is extended by the
+<i>CalculationCollectionReportingSupport</i> module, providing the ability to filter
+specific calculation terms, sort by term values, standardize units and perform
+analytical operations on specific terms, such as sums, means, modes, and medians
+
+2. <i>AMEE::DataAbstraction::TermsList</i> is extended by the
+<i>TermsListReportingSupport</i> module. This provides much of the functionality
+used by <i>CalculationCollectionReportingSupport</i>, allowing lists to be sorted
+and summed, averaged, etc...
+
+3. <i>AMEE::DataAbstraction::Term</i> is extended by the <i>TermReportingSupport</i>
+module. This provides the ability to convert the units within a term (changing the
+term value attribute accordingly), and is used by the operations provided in
+<i>CalculationCollectionReportingSupport</i> and <i>TermsListReportingSupport</i>.
+
+4. A new subclass of <i>AMEE::DataAbstraction::Term</i> is defined, <i>Result</i>.
+This provides a simple container for returning the result of a <i>TermsList</i>
+analytical operation (e.g. sum, mean) complete with label, value, unit, etc...
+
+=Example usage
+
+  # find method returns instance of CalculationCollection
+  my_calculations = OngoingCalculation.find_by_type(:all, :electricity)
+    #=> <AMEE::DataAbstraction::CalculationCollection ... >
+
+  # Dynamic label-derived method returns TermsList of the named term from each
+  # calculation in the set
+
+  my_calculations.country #=> <AMEE::DataAbstraction::TermsList ... >
+
+  my_calculations.energy #=> <AMEE::DataAbstraction::TermsList ... >
+
+  my_calculations.co2 #=> <AMEE::DataAbstraction::TermsList ... >
+
+  # Analytical operations can be applied to lists of terms. These return new
+  # objects, of the Result class. #to_s used here for illustrative purposes
+
+  my_calculations.country.sum.to_s #=> "0.0"
+
+  my_calculations.energy.sum.to_s #=> "23456 kWh"
+
+  my_calculations.co2.sum.to_s #=> "12345 kg"
+
+  my_calculations.co2.sum(:lb).to_s #=> "23456 lb"
+
+  my_calculations.country.mode.to_s #=> "Sweden"
+
+  my_calculations.co2.mean.to_s #=> "4512.5 kg"
+
+  my_calculations.co2.mean('t').to_s #=> "4.5125 t"
+
+  my_calculations.co2.median.to_s #=> "4567 kg"
+
+  my_calculations.co2.predominant_unit #=> "kg"
+
+  my_calculations.sort_by_co2 #=> <AMEE::DataAbstraction::CalculationCollection ... >
+
+  my_calculations.sort_by_co2! #=> <AMEE::DataAbstraction::CalculationCollection ... >

data/Rakefile

@@ -0,0 +1,99 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+require 'spec'
+require 'spec/rake/spectask'
+
+task :default => [:spec]
+
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ['--options', "spec/spec.opts"]
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec,/*ruby*,/*gems*']
+end
+
+require 'jeweler'
+# Fix for Jeweler to use stable branch
+class Jeweler
+  module Commands
+    class ReleaseToGit
+      def run
+        unless clean_staging_area?
+          system "git status"
+          raise "Unclean staging area! Be sure to commit or .gitignore everything first. See `git status` above."
+        end
+        repo.checkout('stable')
+        repo.push('origin', 'stable')
+        if release_not_tagged?
+          output.puts "Tagging #{release_tag}"
+          repo.add_tag(release_tag)
+          output.puts "Pushing #{release_tag} to origin"
+          repo.push('origin', release_tag)
+        end
+      end
+    end
+    class ReleaseGemspec
+      def run
+        unless clean_staging_area?
+          system "git status"
+          raise "Unclean staging area! Be sure to commit or .gitignore everything first. See `git status` above."
+        end
+        repo.checkout('stable')
+        regenerate_gemspec!
+        commit_gemspec! if gemspec_changed?
+        output.puts "Pushing stable to origin"
+        repo.push('origin', 'stable')
+      end
+    end
+  end
+end
+
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "amee-analytics"
+  gem.homepage = "http://github.com/AMEE/amee-analytics"
+  gem.license = "MIT"
+  gem.summary = %Q{Analytics module for use with AMEE AppKit}
+  gem.description = %Q{Part of the AMEE AppKit, this gem provides the ability to do mathmatical operations over a set of calculations}
+  gem.email = "help@amee.com"
+  gem.authors = ["James Hetherington", "Andrew Berkeley", "James Smith", "George Palmer"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+  test.rcov_opts << '--exclude "gems/*"'
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "amee-analytics #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.1

data/amee-analytics.gemspec

@@ -0,0 +1,80 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{amee-analytics}
+  s.version = "1.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["James Hetherington", "Andrew Berkeley", "James Smith", "George Palmer"]
+  s.date = %q{2011-08-31}
+  s.description = %q{Part of the AMEE AppKit, this gem provides the ability to do mathmatical operations over a set of calculations}
+  s.email = %q{help@amee.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.txt"
+  ]
+  s.files = [
+    ".rvmrc",
+    "CHANGELOG.txt",
+    "Gemfile",
+    "LICENSE.txt",
+    "README.txt",
+    "Rakefile",
+    "VERSION",
+    "amee-analytics.gemspec",
+    "init.rb",
+    "lib/amee-analytics.rb",
+    "lib/amee/data_abstraction/calculation_collection_analytics_support.rb",
+    "lib/amee/data_abstraction/result.rb",
+    "lib/amee/data_abstraction/term_analytics_support.rb",
+    "lib/amee/data_abstraction/terms_list_analytics_support.rb",
+    "rails/init.rb",
+    "spec/amee/analytics/calculation_collection_spec.rb",
+    "spec/amee/analytics/term_spec.rb",
+    "spec/amee/analytics/terms_list_spec.rb",
+    "spec/spec.opts",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/AMEE/amee-analytics}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.6.2}
+  s.summary = %q{Analytics module for use with AMEE AppKit}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<amee-data-abstraction>, ["~> 1.1"])
+      s.add_runtime_dependency(%q<amee-data-persistence>, ["~> 1.1"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_development_dependency(%q<rspec>, ["= 1.3.0"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<rspec_spinner>, ["= 1.1.3"])
+      s.add_development_dependency(%q<flexmock>, ["> 0.8.6"])
+      s.add_development_dependency(%q<activerecord>, ["~> 2.3.5"])
+    else
+      s.add_dependency(%q<amee-data-abstraction>, ["~> 1.1"])
+      s.add_dependency(%q<amee-data-persistence>, ["~> 1.1"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_dependency(%q<rspec>, ["= 1.3.0"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<rspec_spinner>, ["= 1.1.3"])
+      s.add_dependency(%q<flexmock>, ["> 0.8.6"])
+      s.add_dependency(%q<activerecord>, ["~> 2.3.5"])
+    end
+  else
+    s.add_dependency(%q<amee-data-abstraction>, ["~> 1.1"])
+    s.add_dependency(%q<amee-data-persistence>, ["~> 1.1"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+    s.add_dependency(%q<rspec>, ["= 1.3.0"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<rspec_spinner>, ["= 1.1.3"])
+    s.add_dependency(%q<flexmock>, ["> 0.8.6"])
+    s.add_dependency(%q<activerecord>, ["~> 2.3.5"])
+  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/calculation_collection_analytics_support.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: Module: AMEE::DataAbstraction::CalculationCollectionAnalyticsSupport
+
+module AMEE
+  module DataAbstraction
+
+    # Mixin module for the <i>AMEE::DataAbstraction::CalculationCollection</i>
+    # class, providing methods for handling collections of calculations.
+    #
+    module CalculationCollectionAnalyticsSupport
+
+      # Returns <tt>true</tt> if all calculations in <tt>self</tt> are
+      # representatives of the same prototype calculation. Otherwise,
+      # returns <tt>false</tt>.
+      #
+      def homogeneous?
+        calculation_labels.size == 1
+      end
+
+      # Returns <tt>true</tt> if all calculations in <tt>self</tt> are NOT
+      # representatives of the same prototype calculation. Otherwise,
+      # returns <tt>false</tt>.
+      #
+      def heterogeneous?
+        !homogeneous?
+      end
+
+      # Returns an array containing all of the unique labels for calculations
+      # held in <tt>self</tt>.
+      #
+      def calculation_labels
+        map(&:label).uniq
+      end
+
+      def +(other_calc_coll)
+        self.class.new(self.to_a + other_calc_coll.to_a)
+      end
+
+      def -(other_calc_coll)
+        other_calc_coll = [other_calc_coll].flatten
+        self.delete_if { |calc| other_calc_coll.include?(calc) }
+      end
+
+      # Similar to <tt>#sort_by!</tt> but returns a new instance of
+      # <i>CalculationCollection</i> arranged according to the values on the
+      # term labelled <tt>term</tt>. E.g.
+      #
+      #   my_calculation_collection.sort_by :co2
+      #
+      #                   #=> <AMEE::DataAbstraction::CalculationCollection ... >
+      #
+      def sort_by(term)
+        term = term.to_sym unless term.is_a? Symbol
+        CalculationCollection.new(send(term).sort_by(:value).map(&:parent))
+      end
+
+      # Sorts the calculation collection in place according to the values on the
+      # term labelled <tt>term</tt>, returning <tt>self</tt>.
+      #
+      #   my_calculation_collection.sort_by! :mass
+      #
+      #                   #=> <AMEE::DataAbstraction::CalculationCollection ... >
+      #
+      def sort_by!(term)
+        replace(sort_by(term))
+      end
+
+      # Returns a new instance of <i>CalculationCollection</i> containing the same
+      # calculations contained within <tt>self</tt> but with the units of the term
+      # <tt>term</tt> standardized on each.
+      #
+      # If no further arguments are provided, the standardized units represent
+      # those which currently predominate amongst the relevent terms. Otherwise,
+      # the specific unit and/or per unit which are required for each instance
+      # of <tt>term</tt> can be explicitly specified as the second and third
+      # arguments respecitively. Units can be specified in any of the formats
+      # which are acceptable to the <tt>Quantify::Unit.for</tt> method (i.e.
+      # stringified unit names or symbols, symbolized labels, or
+      # <tt>Quantify::Unit::Base</tt> instances of the required unit). E.g.
+      #
+      #   my_calculation_collection.standardize_units(:mass)
+      #
+      #                   #=> <AMEE::DataAbstraction::CalculationCollection ... >
+      #
+      #   my_calculation_collection.standardize_units(:mass, :lb)
+      #
+      #                   #=> <AMEE::DataAbstraction::CalculationCollection ... >
+      #
+      #   my_calculation_collection.standardize_units(:mass, 'pound')
+      #
+      #                   #=> <AMEE::DataAbstraction::CalculationCollection ... >
+      #
+      #   my_calculation_collection.standardize_units(:mass, <Quantify::Unit::NonSI>)
+      #
+      #                   #=> <AMEE::DataAbstraction::CalculationCollection ... >
+      #
+      #   my_calculation_collection.standardize_units(:distance, :km, 'year')
+      #
+      #                   #=> <AMEE::DataAbstraction::CalculationCollection ... >
+      #
+      def standardize_units(term,unit=nil,per_unit=nil)
+        term = term.to_sym unless term.is_a? Symbol
+        new_calcs = send(term).standardize_units(unit,per_unit).map do |term|
+          calc = term.parent
+          calc.contents[term.label] = term
+          calc
+        end
+        CalculationCollection.new(new_calcs)
+      end
+
+      # Similar to <tt>#standardize_units</tt> but standardizes units in place,
+      # returning <tt>self</tt>
+      #
+      def standardize_units!(term,unit=nil,per_unit=nil)
+        new_calcs = standardize_units(term,unit,per_unit)
+        replace(new_calcs)
+      end
+
+      # Returns an array of instances of the <tt>Result</tt> class representing the
+      # sums of all outputs represented within the collection
+      #
+      def sum_all_outputs
+        TermsList.new(terms.outputs.visible.labels.uniq.map { |o| send(o).sum })
+      end
+
+      # Returns a new instance of the class <tt>TermsList</tt> representing either
+      # CO2 or CO2e outputs from each calculation
+      #
+      def co2_or_co2e_outputs
+        terms = TermsList.new
+        each do |calculation|
+          if calculation['co2e']
+            terms << calculation['co2e']
+          elsif calculation.outputs.visible.labels.size == 1 && calculation.outputs.visible.labels.first == :co2
+            terms << calculation['co2']
+          end
+        end
+        return terms
+      end
+
+      # Call the <tt>#calculate!</tt> method on all calculations contained within
+      # <tt>self</tt>.
+      #
+      def calculate_all!
+        each { |calc| calc.calculate! }
+      end
+
+      # Call the <tt>#save</tt> method on all calculations contained within
+      # <tt>self</tt>.
+      #
+      def save_all!
+        each { |calc| calc.save }
+      end
+
+      # Returns a terms list of all terms held by calculations contained within
+      # <tt>self</tt>.
+      #
+      def terms
+        TermsList.new( (self.map { |calc| calc.terms.map { |term| term } }).flatten )
+      end
+
+      TermsList::Selectors.each do |sel|
+        delegate sel,:to=>:terms
+      end
+
+      # Return an instance of <i>TermsList</i> containing only terms labelled 
+      # :type.
+      # 
+      # This method overrides the standard #type method (which is deprecated) and
+      # mimics the functionality provied by the first #method_missing method in
+      # dynamically retrieving a subset of terms according their labels.
+      #
+      def type
+        terms.type
+      end
+
+      def respond_to?(method)
+        if terms.labels.include? method.to_sym
+          return true
+        elsif method.to_s =~ /sort_by_(.*)!/ and terms.labels.include? $1.to_sym
+          return true
+        elsif method.to_s =~ /sort_by_(.*)/ and terms.labels.include? $1.to_sym
+          return true
+        else
+          super
+        end
+      end
+
+      # Syntactic sugar for several instance methods.
+      #
+      # ---
+      #
+      # Call a method on <tt>self</tt> which named after a specific term label
+      # contained with an associated calculation and return an instance of the
+      # <tt>TermsList</tt> class contain each of those terms. E.g.,
+      #
+      #   my_terms = my_calculation_collection.type  #=> <AMEE::DataAbstraction::TermsList>
+      #   my_terms.label                             #=> :type
+      #
+      #   my_terms = my_calculation_collection.mass  #=> <AMEE::DataAbstraction::TermsList>
+      #   my_terms.label                             #=> :mass
+      #
+      #   my_terms = my_calculation_collection.co2   #=> <AMEE::DataAbstraction::TermsList>
+      #   my_terms.label                             #=> :co2
+      #
+      # ---
+      #
+      # Call either the <tt>#sort_by</tt> or <tt>#sort_by!</tt> methods including
+      # the argument term as part of the method name, e.g.,
+      #
+      #   my_calculation_collection.sort_by_co2
+      #
+      #                   #=> <AMEE::DataAbstraction::CalculationCollection ... >
+      #
+      #   my_calculation_collection.sort_by_mass!
+      #
+      #                   #=> <AMEE::DataAbstraction::CalculationCollection ... >
+      #
+      def method_missing(method, *args, &block)
+        if terms.labels.include? method.to_sym
+          terms.send(method.to_sym)
+        elsif method.to_s =~ /sort_by_(.*)!/ and terms.labels.include? $1.to_sym
+          sort_by! $1.to_sym
+        elsif method.to_s =~ /sort_by_(.*)/ and terms.labels.include? $1.to_sym
+          sort_by $1.to_sym
+        else
+          super
+        end
+      end
+
+    end
+    
+  end
+end

data/lib/amee/data_abstraction/result.rb

@@ -0,0 +1,16 @@
+# 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::Result
+
+module AMEE
+  module DataAbstraction
+
+    # Subclass of <tt>Term</tt> providing methods and attributes appropriate for
+    # representing the results of cross calculation operations specifically
+    #
+    class Result < Term
+
+    end
+  end
+end

data/lib/amee/data_abstraction/term_analytics_support.rb

@@ -0,0 +1,28 @@
+
+# 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: Module: AMEE::DataAbstraction::TermAnalyticsSupport
+
+module AMEE
+  module DataAbstraction
+    
+    # Mixin module for the <i>AMEE::DataAbstraction::Term</i> class, providing
+    # methods for handling collections of calculations.
+    #
+    module TermAnalyticsSupport
+
+      # Returns an instance of <i>Result</i> based upon the attributes of
+      # <tt>self</tt>.
+      #
+      def to_result
+        result_term = Result.new
+        TermsList::TermProperties.each do |attr|
+          result_term.send(attr, self.send(attr))
+        end
+        return result_term
+      end
+     
+    end
+  end
+end