ce-bucketize 0.1.0

data/lib/ce-bucketize.rb

@@ -0,0 +1,341 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+require 'date'
+require 'json'
+require 'ce-greenbutton'
+require 'ce-bucketize/bucketizer'
+require 'ce-bucketize/model/tariff_rule'
+
+# This module aggregates 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.
+#
+#
+# Example
+#   see demo/demo.rb for detailed usage example.
+#
+# Author:  ahmed.seddiq
+# Version: 1.0
+module Bucketize
+
+  # The consumption intervals should be summed by the hours of the day
+  #  and summed to daily values.
+  #
+  # month   -   a Time representing the first hour of the first day in the month
+  #             to which the data will be aggregated. (required)
+  # download_options  - options used to download GreenButton data
+  #
+  # Supported download options:
+  #   use_ftp         -   a Boolean flag to switch between ftp and API modes.
+  #   API (HTTP) options
+  #     access_token  -   the OAuth2 token used by the GreenButton gem to
+  #                       authenticate to the GreenButton custodians.
+  #     subscription_url  - the url used by the GreenButton gem to retrieve the data
+  #   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.
+  #
+  #
+  # Returns an array in the form [{date1 => value, date2 => value}]
+  #
+  # Raises ArgumentError if month is not the first hour of first day of a month.
+  def self.consumption_from_month_start(month, download_options)
+    check_first_day_of_month(month)
+
+    first_day = month
+    last_day = DateTime.new(month.year, month.month, -1, -1, -1, -1,
+                            first_day.gmt_offset)
+    # convert to time with the same zone offset of the first day
+    last_day = Time.new(last_day.year, last_day.month, last_day.day,
+                            last_day.hour, last_day.min, last_day.sec,
+                            first_day.gmt_offset) + 1
+    Bucketize::Bucketizer
+        .new(download_options, first_day, last_day)
+        .daily_consumption_values
+  end
+
+  # The consumption is calculated by summing the consumption data in totals
+  # of hours groups and summed to daily values.
+  #
+  # date    -   a Date representing the day to which the data will
+  #             be aggregated, it must be Time object referring to the first hour
+  #             of the required day (required).
+  #
+  # download_options  - options used to download GreenButton data
+  #
+  # Supported download options:
+  #   use_ftp         -   a Boolean flag to switch between ftp and API modes.
+  #   API (HTTP) options
+  #     access_token  -   the OAuth2 token used by the GreenButton gem to
+  #                       authenticate to the GreenButton custodians.
+  #     subscription_url  - the url used by the GreenButton gem to retrieve the data
+  #   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.
+  #
+  #
+  # Returns an array in the form [{date1 => value, date2 => value}]
+  def self.consumption_by_date(date, download_options)
+    check_first_hour(date)
+
+    first_hour = date
+    last_hour = DateTime.new(date.year, date.month, date.day, -1, -1, -1,
+                             first_hour.gmt_offset)
+    last_hour = Time.new(last_hour.year, last_hour.month, last_hour.day,
+                         last_hour.hour, last_hour.min, last_hour.sec,
+                         first_hour.gmt_offset) + 1
+
+    Bucketize::Bucketizer
+        .new(download_options, first_hour, last_hour).daily_consumption_values
+  end
+
+  # daily consumption should be calculated by summing the consumption data
+  # into totals for the hour groups. These hour groups are summed to daily
+  # values.
+  #
+  # date1    -   a Time representing the first hour of the start day of the
+  #             range to which the data will be aggregated.
+  #             It must be in the timezone of the consumer (required).
+  # date2    -   a Time representing the last second of the end day of the range
+  #              to which the data will be aggregated. (required).
+  #              It must be in the timezone of the consumer (required).
+  # download_options  - options used to download GreenButton data
+  #
+  # Supported download options:
+  #   use_ftp         -   a Boolean flag to switch between ftp and API modes.
+  #   API (HTTP) options
+  #     access_token  -   the OAuth2 token used by the GreenButton gem to
+  #                       authenticate to the GreenButton custodians.
+  #     subscription_url  - the url used by the GreenButton gem to retrieve the data
+  #   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.
+  #
+  # Returns an array in the form [{date1 => value, date2 => value}]
+  #
+  def self.consumption_date_range(date1, date2, download_options)
+    check_first_hour(date1)
+    check_last_second(date2)
+
+    first_day = date1
+    last_day = date2 + 1
+
+    Bucketize::Bucketizer
+        .new(download_options, first_day, last_day).daily_consumption_values
+  end
+
+
+  # The consumption intervals should be summed by the hours of the day
+  # relevant to the tariff, and summed to daily values. Daily consumption
+  # values are multiplied with the appropriate tariff for the day of the week
+  # to get costs. Tariff selection varies depending on the consumption total
+  # since when the beginning of the month falls
+  #
+  # month   -   a Time representing the first hour of the first day in the month
+  #             to which the data will be aggregated. (required)
+  # tariff  -   The tariff rules (json string).
+  #
+  # download_options  - options used to download GreenButton data
+  #
+  # Supported download options:
+  #   use_ftp         -   a Boolean flag to switch between ftp and API modes.
+  #   API (HTTP) options
+  #     access_token  -   the OAuth2 token used by the GreenButton gem to
+  #                       authenticate to the GreenButton custodians.
+  #     subscription_url  - the url used by the GreenButton gem to retrieve the data
+  #   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.
+  #
+  #
+  # Returns an array in the form [{date1 => cost, date2 => cost}]
+  #
+  def self.cost_from_month_start(month, tariff, download_options)
+    check_first_day_of_month(month)
+
+    first_day = month
+    last_day = DateTime.new(month.year, month.month, -1, -1, -1, -1,
+                            first_day.gmt_offset)
+    # convert to time with the same zone offset of the first day
+    last_day = Time.new(last_day.year, last_day.month, last_day.day,
+                        last_day.hour, last_day.min, last_day.sec,
+                        first_day.gmt_offset) + 1
+    tariff_rules = JSON.parse(tariff, :object_class => Bucketize::TariffRule)
+
+    Bucketize::Bucketizer
+        .new(download_options, first_day, last_day)
+        .daily_consumption_costs(tariff_rules)
+  end
+
+  # The consumption is calculated by summing the consumption data in totals of
+  # hours groups and summed to daily values. Daily values are multiplied with
+  # the appropriate tariff for the day of the week.
+  #
+  # date    -   a Date representing the day to which the data will
+  #             be aggregated, it must be Time object referring to the first hour
+  #             of the required day (required).
+  # tariff  -   The tariff rules (json string).
+  #
+  # download_options  - options used to download GreenButton data
+  #
+  # Supported download options:
+  #   use_ftp         -   a Boolean flag to switch between ftp and API modes.
+  #   API (HTTP) options
+  #     access_token  -   the OAuth2 token used by the GreenButton gem to
+  #                       authenticate to the GreenButton custodians.
+  #     subscription_url  - the url used by the GreenButton gem to retrieve the data
+  #   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.
+  #
+  #
+  # Returns an array in the form [{date1 => cost, date2 => cost}]
+  #
+  def self.cost_by_date(date, tariff, download_options)
+    check_first_hour(date)
+
+    first_hour = date
+    last_hour = DateTime.new(date.year, date.month, date.day, -1, -1, -1,
+                             first_hour.gmt_offset)
+    last_hour = Time.new(last_hour.year, last_hour.month, last_hour.day,
+                         last_hour.hour, last_hour.min, last_hour.sec,
+                         first_hour.gmt_offset) + 1
+    tariff_rules = JSON.parse(tariff, :object_class => Bucketize::TariffRule)
+
+    Bucketize::Bucketizer
+        .new(download_options, first_hour, last_hour)
+        .daily_consumption_costs(tariff_rules)
+  end
+
+
+  # Daily cost should be calculated by summing the consumption data into
+  # totals for the hour groups, and using the appropriate tariff based on the
+  # day of the week and hour group.
+  #
+  # date1    -   a Time representing the first hour of the start day of the
+  #             range to which the data will be aggregated.
+  #             It must be in the timezone of the consumer (required).
+  # date2    -   a Time representing the last second of the end day of the range
+  #              to which the data will be aggregated. (required).
+  #              It must be in the timezone of the consumer (required).
+  # tariff  -   The tariff rules (json string).
+  #
+  # download_options  - options used to download GreenButton data
+  #
+  # Supported download options:
+  #   use_ftp         -   a Boolean flag to switch between ftp and API modes.
+  #   API (HTTP) options
+  #     access_token  -   the OAuth2 token used by the GreenButton gem to
+  #                       authenticate to the GreenButton custodians.
+  #     subscription_url  - the url used by the GreenButton gem to retrieve the data
+  #   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.
+  #
+  # Returns an array in the form [{date1 => cost, date2 => cost}]
+  def self.cost_date_range(date1, date2, tariff, download_options)
+    check_first_hour(date1)
+    check_last_second(date2)
+
+    first_day = date1
+    last_day = date2 + 1
+
+    tariff_rules = JSON.parse(tariff, :object_class => Bucketize::TariffRule)
+
+    Bucketize::Bucketizer
+        .new(download_options, first_day, last_day)
+        .daily_consumption_costs(tariff_rules)
+  end
+
+  # Public: configures the Bucketize module. It must be called before usage.
+  #
+  # For example:
+  #   Bucketize.config(reg_access_token: "your access token"
+  #                      application_information_url: "http://app_info_url")
+  #
+  # Returns nothing.
+  #
+  def self.config(options = {})
+    GreenButton.config(options)
+  end
+
+  # Internal: Checks if the given time is a Time object referring to a first
+  # hour of the first day of a month.
+  #
+  # Raises ArgumentError if invalid.
+  def self.check_first_day_of_month(time)
+    check_time(time)
+    unless time.day == 1
+      raise ArgumentError, "#{time} is not the first day of Month #{time.month}"
+    end
+    check_first_hour(time)
+  end
+
+  # Internal: Checks if the given time is a Time object referring to a first
+  # hour of a day.
+  #
+  # Raises ArgumentError if invalid.
+  def self.check_first_hour(time)
+    check_time(time)
+    if time.hour != 0 or time.min != 0 or time.sec != 0
+      raise ArgumentError, "#{time} is not the first hour of the day"
+    end
+  end
+
+  # Internal: Checks if the given time is a Time object referring to the last
+  # second of a day.
+  #
+  # Raises ArgumentError if invalid.
+  def self.check_last_second(time)
+    check_time(time)
+    next_sec = time + 1
+    if next_sec.hour != 0 or next_sec.min != 0 or next_sec.sec != 0
+      raise ArgumentError, "#{time} is not the last second of the day"
+    end
+
+  end
+
+  # Internal: Checks if the given time is a Time object.
+  #
+  # Raises ArgumentError if invalid.
+  def self.check_time(time)
+    raise ArgumentError, "#{time} is not a Time object" unless time.is_a? Time
+  end
+
+  private_class_method :check_time
+  private_class_method :check_first_hour
+  private_class_method :check_last_second
+  private_class_method :check_first_day_of_month
+
+
+  # This error will be raised if an invalid tariff json is provided.
+  #
+  # Author: ahmed.seddiq
+  # Version: 1.0
+  class InvalidTariffError < Exception
+
+  end
+
+
+end

metadata

@@ -0,0 +1,161 @@
+--- !ruby/object:Gem::Specification
+name: ce-bucketize
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- TCSASSEMBLER
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+- !ruby/object:Gem::Dependency
+  name: yard-tomdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+- !ruby/object:Gem::Dependency
+  name: interpolate
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: ce-greenbutton
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: |-
+  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.
+email:
+- TCSASSEMBLER@topcoder.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- ce-bucketize.gemspec
+- lib/ce-bucketize.rb
+- lib/ce-bucketize/bucketizer.rb
+- lib/ce-bucketize/daily_data.rb
+- lib/ce-bucketize/hourly_values.rb
+- lib/ce-bucketize/model/hour_cost.rb
+- lib/ce-bucketize/model/hour_value.rb
+- lib/ce-bucketize/model/tariff_rule.rb
+- lib/ce-bucketize/tariffed_hourly_costs.rb
+- lib/ce-bucketize/tariffed_hourly_values.rb
+- lib/ce-bucketize/version.rb
+homepage: http://greenbuttondata.org
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Aggregates consumption data and calculates costs based on predefined tariffs.
+test_files: []