ce-bucketize 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: aa75c7b3b340eff4180b1eeeb39713e7924bd1d3
+  data.tar.gz: 8274b993868aa63cf4d383f78f740aaa9105e8dc
+SHA512:
+  metadata.gz: 42c8b54e45ce7f49090bccb799ed7bab95630b9105001b9f72d121f0acde4d6d5777640251f3ad93f93bbff0da9a68cf2f035078805643dfb1960aff04bb57a6
+  data.tar.gz: 8794ff5e9c7a2342e28862ed9b4809673f45771f775452d3e205940df3fb3f7c1797b136236b21f043107df00616152df4e35ed08e007054c8ca354168a679af

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ce-bucketize.gemspec
+gemspec
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 TopCoder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,241 @@
+# Bucketize
+
+This gem will aggregate consumption data with heterogeneous granularity across time into systematic intervals.
+These intervals are then either multiplied with a relevant tariff value then summed into daily totals, or directly summed into daily totals.
+The simplest example would be to sum hourly data into daily totals, subject to data completeness checks and multiply them with a single tariff number.
+
+## Prerequisites
+    Ruby ~> 2.0.0
+    Bundler
+    gem install bundler
+
+## Installation
+### GreenButton gem
+Follow installation instructions in the README file of
+the GreenButton Library module
+### Bucketize gem
+Using Bundler, add the following line to your Gemfile
+
+    ```ruby
+    gem 'bucketize'
+    ```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem build bucketize.gemspec
+    $ gem install bucketize-0.1.0.gem
+
+## Usage
+
+    ```ruby
+    require 'ce-greenbutton'
+    require 'ce-bucketize'
+    
+    reg_access_token = 'd89bb056-0f02-4d47-9fd2-ec6a19ba8d0c'
+    app_inf_url = 'https://services.greenbuttondata.org:443/DataCustodian/espi/1_1/resource/ApplicationInformation/2'
+    subscription_url = 'https://services.greenbuttondata.org:443/DataCustodian/espi/1_1/resource/Batch/RetailCustomer/5/UsagePoint'
+    access_token = '688b026c-665f-4994-9139-6b21b13fbeee'
+    
+    # FTP related values
+    ftp_host = 'us1.hostedftp.com'
+    ftp_user = 'clearlyenergy'
+    ftp_password = 'store_clearly'
+    ftp_path = 'SDGETest'
+    utility_name = 'CLEARLY'
+    application_id = '10066_CONSUMPTION'
+    ftp_time = Time.new(2015, 3, 19, 1, 1, 1, 0)
+    
+    download_options = {access_token: access_token, subscription_url: subscription_url}
+    ftp_download_options = {
+        use_ftp: true,
+        application_id: application_id,
+        utility_name: utility_name,
+        time: ftp_time
+    }
+    
+    
+    # configure the GreenButton Library
+    Bucketize.config(
+        reg_access_token: reg_access_token,
+        application_information_url: app_inf_url,
+        ftp_host: ftp_host,
+        ftp_user: ftp_user,
+        ftp_password: ftp_password,
+        ftp_path: ftp_path
+    )
+    
+    # get consumptions from month start
+    daily_data = Bucketize.consumption_from_month_start(Time.new(2011, 2, 1, 0, 0, 0, -28800), download_options)
+    puts 'Consumption From Month Start 2012/02'
+    puts JSON.pretty_generate(daily_data.to_a)
+    
+    daily_data = Bucketize.consumption_from_month_start(Time.new(2013, 1, 1, 0, 0, 0, -14400), ftp_download_options)
+    puts 'Consumption From Month Start 2013/01 Using FTP'
+    puts JSON.pretty_generate(daily_data.to_a)
+    
+    
+    
+    # get cost from month start
+    tariff = '[{
+      "utility_id": 1,
+      "rate_class": "R",
+      "day_of_week": [1,2,3,4,5,6,7],
+      "kwh_low": 0,
+      "kwh_high":1000,
+      "tariff":10
+    },
+    {
+      "utility_id": 1,
+      "rate_class": "R",
+      "day_of_week": [1,2,3,4,5,6,7],
+      "kwh_low": 1000,
+      "tariff":20
+    }]'
+    daily_data = Bucketize.cost_from_month_start(Time.new(2011, 2, 1, 0, 0, 0, -28800), tariff, download_options)
+    puts 'Cost From Month Start 2012/02:'
+    puts JSON.pretty_generate(daily_data.to_a)
+    
+    daily_data = Bucketize.cost_from_month_start(Time.new(2013, 1, 1, 0, 0, 0, -14400), tariff, ftp_download_options)
+    puts 'Cost From Month Start 2013/01 Using FTP'
+    puts JSON.pretty_generate(daily_data.to_a)
+    
+    
+    
+    # get consumption by date
+    daily_data = Bucketize.consumption_by_date(Time.new(2011, 2, 5, 0, 0, 0, -28800), download_options)
+    puts 'Consumption For Date 2011/02/05'
+    puts JSON.pretty_generate(daily_data.to_a)
+    
+    daily_data = Bucketize.consumption_by_date(Time.new(2013, 1, 5, 0, 0, 0, -14400), ftp_download_options)
+    puts 'Consumption For Date 2013/01/05 Using FTP'
+    puts JSON.pretty_generate(daily_data.to_a)
+    
+    
+    # get cost by date
+    tariff = '[{
+        "utility_id": 1,
+        "rate_class": "R",
+        "time_start": 1,
+        "time_end": 3,
+        "tariff":10
+    },
+    {
+        "utility_id": 1,
+        "rate_class": "R",
+        "time_start": 4,
+        "time_end": 24,
+        "tariff":20
+    }]'
+    daily_data = Bucketize.cost_by_date(Time.new(2011, 2, 5, 0, 0, 0, -28800), tariff,
+                                        download_options)
+    puts 'Consumption For Date 2011/02/05'
+    puts JSON.pretty_generate(daily_data.to_a)
+    
+    daily_data = Bucketize.cost_by_date(Time.new(2013, 1, 5, 0, 0, 0, -14400), tariff,
+                                        ftp_download_options)
+    puts 'Consumption For Date 2013/01/05 Using FTP'
+    puts JSON.pretty_generate(daily_data.to_a)
+    
+    
+    
+    # get consumption by date range.
+    daily_data = Bucketize.consumption_date_range(Time.new(2011, 2, 5, 0, 0, 0, -28800),
+                                                  Time.new(2011, 2, 10, 23, 59, 59, -28800),
+                                                  download_options)
+    puts 'Consumption For Dates 2011/02/05 to 2011/02/10 :'
+    puts JSON.pretty_generate(daily_data.to_a)
+    
+    daily_data = Bucketize.consumption_date_range(Time.new(2013, 1, 5, 0, 0, 0, -14400),
+                                                  Time.new(2013, 1, 10, 23, 59, 59, -14400),
+                                                  ftp_download_options)
+    puts 'Consumption For Dates 2013/01/05 to 2013/01/10 :'
+    puts JSON.pretty_generate(daily_data.to_a)
+    
+    # get cost by date range.
+    tariff = '[{
+        "utility_id": 1,
+        "rate_class": "R",
+        "time_start": 1,
+        "time_end": 12,
+        "day_of_week": [1,2,3,4],
+        "tariff":5
+    },
+    {
+        "utility_id": 1,
+        "rate_class": "R",
+        "time_start": 1,
+        "time_end": 12,
+        "day_of_week": [5,6,7],
+        "tariff":7
+    },
+    {
+        "utility_id": 1,
+        "rate_class": "R",
+        "time_start": 13,
+        "time_end": 24,
+        "day_of_week": [1,2,3,4],
+        "tariff":10
+    },
+    {
+        "utility_id": 1,
+        "rate_class": "R",
+        "time_start": 13,
+        "time_end": 24,
+        "day_of_week": [5,6,7],
+        "tariff":12
+    }]'
+    daily_data = Bucketize.cost_date_range(Time.new(2011, 2, 5, 0, 0, 0, -28800),
+                                           Time.new(2011, 2, 10, 23, 59, 59, -28800),
+                                           tariff,
+                                           download_options)
+    puts 'Cost For Dates 2011/02/05 to 2011/02/10'
+    puts JSON.pretty_generate(daily_data.to_a)
+    
+    daily_data = Bucketize.cost_date_range(Time.new(2013, 1, 5, 0, 0, 0, -14400),
+                                           Time.new(2013, 1, 10, 23, 59, 59, -14400),
+                                           tariff,
+                                           ftp_download_options)
+    puts 'Cost For Dates 2013/01/05 to 2013/01/10 Using FTP'
+    puts JSON.pretty_generate(daily_data.to_a)
+    ```
+Other aggregation methods can be called in the manner like above.
+
+## Development
+This gem was designed in a modular way to allow further modification. An expected
+scenario is to adapt a MapReduce solution to help analyze the data more efficiently.
+
+The aggregation was separated to phases; each was encapsulated in a custom Enumerable
+that operates on the input data and produces new data.
+
+API ==> GreenButton ==> HourlyValues ==> TariffedHourlyValues/Costs ==> DailyData ==> output data
+
+1. API: the GreenButton API (REST endpoint)
+2. GreenButton: The GreenButton Library that maps the API response to set of Ruby Objects
+3. HourlyValues: a custom Enumerable that takes the generated GbDataDescription and produces an hourly data.
+    input data gaps are detected and interpolated in this stage.
+4. TariffedHourlyValues/TariffedHourlyCosts: custom Enumerables that takes the HourlyData and applies the input
+ tariff rules on them. The output will be the values after applying the matched tariff.
+5. DailyData: a custom Enumerable that aggregates a day data from the tariffed hourly data.
+
+## Test
+From the base directory of the module (the directory containing the .gemspec file.
+
+    $ bundle install
+    $ bundle exec rspec
+
+Coverage reports will be found under the `coverage` subfolder.
+
+
+## GreenButton API reference
+- [Green Button Home](http://www.greenbuttondata.org)
+- [Green Button API sandbox](http://energyos.github.io/OpenESPI-GreenButton-API-Documentation/API/)
+- [GReen Button Concept overview](http://www.greenbuttondata.org/developers/)
+
+
+### Reference this Ruby Gem Documentation
+`tomdoc` was used to generate documentation files for this gem. The generated files are included in `doc` directory.
+documentation is generated by [Yard.](https://github.com/rubyworks/yard-tomdoc)

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler/gem_tasks'
+

data/ce-bucketize.gemspec

@@ -0,0 +1,35 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ce-bucketize/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'ce-bucketize'
+  spec.version       = Bucketize::VERSION
+  spec.authors       = ['TCSASSEMBLER']
+  spec.email         = ['TCSASSEMBLER@topcoder.com']
+
+  spec.summary       = %q{Aggregates consumption data and calculates costs based on predefined tariffs.}
+
+  spec.description   = %q{aggregate consumption data with heterogeneous granularity across time into systematic intervals.
+These intervals are then either multiplied with a relevant tariff value then summed into daily totals,
+or directly summed into daily totals. The simplest example would be to sum hourly data into daily totals,
+ subject to data completeness checks and multiply them with a single tariff number.}
+  spec.homepage      = 'http://greenbuttondata.org'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.8'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.2'
+  spec.add_development_dependency 'simplecov', '~> 0.9.2'
+  spec.add_development_dependency 'yard-tomdoc', '~> 0.7.1'
+
+  spec.add_runtime_dependency 'interpolate', '~> 0.3.0'
+  spec.add_runtime_dependency 'ce-greenbutton', '~> 0.1.0'
+
+end

data/lib/ce-bucketize/bucketizer.rb

@@ -0,0 +1,134 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+require 'ce-bucketize/hourly_values'
+require 'ce-bucketize/tariffed_hourly_values'
+require 'ce-bucketize/tariffed_hourly_costs'
+require 'ce-bucketize/daily_data'
+
+module Bucketize
+  # This class is responsible for executing an aggregation method for the
+  # Bucketize module. It orchestras some other helper classes to perform the
+  # required aggregation.
+  #
+  # Author: ahmed.seddiq
+  # Version: 1.0
+  class Bucketizer
+    # Initializes the Bucketizer with the given arguments.
+    #
+    # download_options  - options used to download GreenButton data
+    # from              - represents the start Date for required aggregation
+    # to                - represents the end date for required aggregation
+    #
+    # supported download_options
+    #   use_ftp           - a Boolean flag to switch between ftp and API modes.
+    #   API (HTTP) options
+    #     subscription_url  - the GreenButton subscription url.
+    #     access_token      - the GreenButton OAuth2 access_token.
+    #   FTP options
+    #     application_id  - represents the GreenButton 3rd party application id.
+    #     time            - used to construct file name. (optional, defaults
+    #                       to current time)
+    #     utility_name    - represents the utility name, used to construct the
+    #                       XML file name.
+    # Raises ArgumentError if download_options are not valid
+    #
+    def initialize(download_options, from=nil, to=nil)
+      @download_options = download_options
+      check_download_options
+      @from = from
+      @to = to
+    end
+
+    # Fetches and aggregates the consumption data to daily usage values
+    #
+    # Returns an array in the form [{date1 => value, date2 => value}]
+    def daily_consumption_values
+      gb = download_data(@from)
+      gb.map do |gb_data_description|
+        hourly_values = Bucketize::HourlyValues.new(gb_data_description, @from, @to)
+        daily_data(hourly_values, :value)
+      end
+
+    end
+
+
+
+    # Fetches and aggregates the data based on the given array of TariffRules
+    #
+    # tariff_rules  - an Array of TariffRule to be applied to the GreenButton
+    #                 data for this Bucketizer.
+    # Returns a collection of [gb_data_description, date, cost]
+    def daily_consumption_costs(tariff_rules)
+      # Validate tariff rules
+      tariff_rules.each { |rule| rule.validate }
+      gb = download_data(@from)
+      gb.map do |gb_data_description|
+        hourly_values = Bucketize::HourlyValues.new(gb_data_description, @from, @to)
+        tariffed_hourly_costs =
+            Bucketize::TariffedHourlyCosts.new(hourly_values, tariff_rules)
+        daily_data(tariffed_hourly_costs, :cost)
+      end
+    end
+
+    # Internal: aggregates the given hourly data to a daily data.
+    #
+    # hourly_data - the hourly data, an Enumerable
+    # aggregation_method - the getter method to be called for elements in the
+    #                   hourly_data. this value will be summed for each day.
+    # Returns a DailyData enumerable.
+    def daily_data(hourly_data, aggregation_method )
+      daily_data = Bucketize::DailyData.new(hourly_data, aggregation_method)
+      # convert the daily_data to hash date => value
+      daily_data.reduce({}) do |all, entry|
+        all[entry[0]] = entry[1]
+        all
+      end
+    end
+
+    private
+    # Internal: checks the validity of the download options
+    #
+    # Raises  ArgumentError if options are invalid
+    def check_download_options
+      raise ArgumentError, 'No download options provided'if @download_options.nil?
+      if @download_options[:use_ftp]
+        if @download_options[:application_id].nil? or
+            @download_options[:utility_name].nil?
+          raise ArgumentError, 'application_id and utility_name are mandatory
+              options for FTP download'
+        end
+      else
+        if @download_options[:access_token].nil? or
+            @download_options[:subscription_url].nil?
+          raise ArgumentError, 'access_token and subscription_url are mandatory
+              options for API(HTTP) download'
+        end
+      end
+    end
+
+
+    # Internal: downloads data using GreenButton gem according to the configured
+    #   downlaod_options
+    #
+    # from  - the Time object representing the start date of required data, used
+    #         only in the API(HTTP) download.
+    #
+    # Returns array of GbDataDescription
+    def download_data(from)
+      if @download_options[:use_ftp]
+        GreenButton.download_data_ftp(
+                       @download_options[:application_id],
+                       @download_options[:time] || Time.now,
+                       @download_options[:utility_name]
+        )
+      else
+        GreenButton.download_data(
+                       @download_options[:access_token],
+                       @download_options[:subscription_url],
+                       from
+        )
+      end
+    end
+
+  end
+end

data/lib/ce-bucketize/daily_data.rb

@@ -0,0 +1,41 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+module Bucketize
+  # An Enumerable that will aggregate hourly data to daily data.
+  #
+  # Author: ahmed.seddiq
+  # Version: 1.0
+  class DailyData
+    include Enumerable
+    # Creates a new instance of this Enumerable
+    #
+    # hourly_data  -  the hourly data source. (an Enumerable)
+    # aggregated_method - the method that will be called on the items from the
+    #                     source and summed up in the result value.
+    def initialize (hourly_data, aggregate_method)
+      @hourly_data = hourly_data
+      @aggregate_method = aggregate_method
+    end
+
+    def each(&block)
+      return enum_for(:each) if block.nil?
+
+      date = @hourly_data.first.hour_start
+      day_value = 0
+      day = date.day
+      @hourly_data.each do |h_data|
+        value = h_data.public_send(@aggregate_method)
+        if h_data.hour_start.day == day
+          day_value += value
+        else
+          yield date, day_value
+          date = h_data.hour_start
+          day_value = value
+          day = date.day
+        end
+      end
+      # the last
+      yield date, day_value
+    end
+  end
+end