ce-bucketize 0.1.0

data/lib/ce-bucketize/hourly_values.rb

@@ -0,0 +1,251 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+require 'ce-bucketize/model/hour_value'
+require 'ce-greenbutton/model/gb_data_reading'
+require 'interpolate'
+
+module Bucketize
+  # An Enumerable for hourly consumption values. The values are aggregated from
+  #   the raw GreenButton data.
+  #
+  # Author: ahmed.seddiq
+  # Version: 1.0
+  class HourlyValues
+    include Enumerable
+
+    # hour in seconds
+    HOUR = 3600
+
+    # The length (in seconds) of the maximum allowed gap in input data.
+    attr_accessor :max_gap_length
+
+    # This is a readonly attribute that will hold the combined interpolated
+    # raw data. It will be initialized in the constructor.
+    attr_reader :readings
+
+
+    # Creates a new instance of the HourlyValues collection.
+    #
+    # gb_data_description - the input GreenButton data.
+    # from  - the start Time, must represent an hour start.
+    # to  - the end Time, must represent an hour start.
+    #
+    # Raises ArgumentError if from or to don't represent an hour start.
+    def initialize(gb_data_description, from=nil, to=nil)
+      unless from.nil? or (from.min == 0 and from.sec == 0)
+        raise ArgumentError, '"from" should be an hour start'
+      end
+      unless to.nil? or (to.min == 0 and to.sec == 0)
+        raise ArgumentError, '"to" should be an hour start'
+      end
+
+      @gb_data_description = gb_data_description
+      @from = from
+      @to = to
+      @max_gap_length = 4 * HOUR
+      @readings = prepare_readings
+    end
+
+
+    # The "each" method required by the Enumerable mixin. It yields the hourly
+    # consumption values for the GreenButton data associated with this instance.
+    #
+    # Yields HourValue instances representing the hourly consumption of the data.
+    def each(&block)
+      return enum_for(:each) if block.nil?
+      readings = @readings.each
+
+      finished = false # will be set to true when raw data are all consumed.
+      cv = 0 # will aggregate current hour value
+      current_reading = readings.next
+      t0 = current_reading.time_start # the start of the first reading
+      d0 = current_reading.time_duration.to_f # duration of the first reading
+      # last reading time.
+      tn = @readings.last.time_start + @readings.last.time_duration - HOUR
+      hour_start = @from || t0 # will point to the current hour start
+      last_hour_start = ((@to - HOUR) unless @to.nil?) || tn # the last hour_start
+      d = (t0 + d0 - hour_start).to_f # remaining seconds from the current reading.
+      rem = (d/d0) * current_reading.value # remaining value from the current reading.
+      hf = 1.to_f # remaining fraction of hour for the current hour value
+      until finished do
+        # ratio to be consumed from the current reading
+        rat = [1.0, (hf * HOUR) / d].min
+        # increment current value by the ratio from the current reading
+        cv = cv + rat * rem
+        # decrement consumed value from current reading
+        rem = [0, rem * (1 - rat)].max
+        # update remaining fraction by the consumed duration
+        hf = [0, hf - ((rat * d)/ HOUR)].max
+        # update remaining duration
+        d = d * (1 - rat)
+
+        if hf == 0.0
+          # a complete hour is calculated
+          yield Bucketize::HourValue.new(hour_start, cv.round(2))
+          # reset the current hour value and fraction
+          cv = 0
+          hf = 1.to_f
+          hour_start += HOUR
+          if hour_start > last_hour_start
+            finished = true
+          end
+        end
+        if rem == 0
+          # current reading is totally consumed.
+          begin
+            # get next reading
+            current_reading = readings.next
+            d = current_reading.time_duration.to_f
+            rem = current_reading.value
+          rescue StopIteration
+            finished = true
+          end
+        end
+      end
+    end
+
+    # Internal: this method will combine, sort, check for gaps and interpolates
+    # the raw data in the @gb_data_description.
+    #
+    # Returns the readings array; array of (GbDataReading)
+    #
+    # Raises TooManyDataMissingError if there is more than @max_gap_length
+    #   missing data
+    #
+    private
+    def prepare_readings
+      # Combine all interval_readings in all gb_data instances.
+      readings = @gb_data_description.gb_data_array.reduce([]) do |all, gb_data|
+        all + gb_data.interval_readings
+      end
+      # Sort by reading time start
+      readings.sort_by! { |reading| reading.time_start }
+
+      # Compute average value per second
+      sec_avg = readings.reduce(0) do |avg, r|
+        avg + (r.value.to_f / r.time_duration.to_f)
+      end / readings.length
+
+      # check first reading
+      first_time = readings.first.time_start
+      if first_time.to_i % HOUR != 0
+        # add first reading to cover the missing part of the first hour.
+        first_reading = GbDataReading.new
+        first_reading.time_start = first_time - first_time.to_i % HOUR
+        first_reading.time_duration = first_time.to_i % HOUR
+        first_reading.value = (first_reading.time_duration * sec_avg).round(2)
+        readings = [first_reading] + readings
+      end
+      # check gaps
+      gaps = {}
+      readings.each_with_index do |reading, i|
+        next_time = reading.time_start + reading.time_duration
+        if reading.value.nil? or reading.value.to_f.nan? or reading.value == 0
+          # a gap detected
+          gaps[i] = {:from => reading.time_start, :to => next_time, :replace => true}
+        end
+
+        next_reading = readings[i + 1]
+        unless next_reading.nil? or (next_reading.time_start == next_time)
+          # a gap detected
+          unless next_reading.time_start - next_time <= @max_gap_length
+            raise Bucketize::TooManyDataMissingError
+          end
+          gaps[i + 1] = {:from => next_time, :to => next_reading.time_start}
+        end
+      end
+      # check last reading
+      last_time = readings.last.time_start + readings.last.time_duration
+      if last_time.to_i % HOUR != 0
+        # add last reading to cover the missing part of last hour.
+        last_reading = GbDataReading.new
+        last_reading.time_start = last_time
+        last_reading.time_duration = HOUR - last_time.to_i % HOUR
+        last_reading.value = (last_reading.time_duration * sec_avg).round(2)
+        readings << last_reading
+      end
+
+      # interpolation
+      interpolate_missing_data(gaps, readings)
+
+      # get start and end reading indicies
+      r0 = (get_reading_for(@from, readings) unless @from.nil?) || 0
+      rn = (get_reading_for(@to, readings) unless @to.nil?) ||
+          readings.length - 1
+
+      readings[r0..rn]
+    end
+
+    # Get the index of reading that covers the given time.
+    #
+    # time - the time to search for.
+    # reading - the reading array.
+    #
+    # Returns the index of the reading that covers this time
+
+    # Raises ArgumentError if not found.
+    def get_reading_for(time, readings)
+      readings.each_with_index do |reading, i|
+        if time.between? reading.time_start,
+                         reading.time_start + reading.time_duration - 1
+          return i
+        end
+      end
+      raise ArgumentError, "#{time} is out of range"
+    end
+
+    # Internal: interpolates the given gaps in the readings.
+    #
+    # gaps  - a hash {index_of_gap_in_readings => {:from=> time, :to =>time}}
+    # readings  - the readings array
+    #
+    # Returns Nothing, the interpolated data will be injected to the readings
+    #  array.
+    def interpolate_missing_data(gaps, readings)
+      if gaps.size > 0
+        # get points for interpolation
+        points = readings.reduce({}) do |all, reading|
+          unless reading.value.nil? or reading.value.to_f.nan? or
+              reading.value == 0
+            all[reading.time_start.to_i] = reading.value
+          end
+          all
+        end
+
+        interpolate = Interpolate::Points.new(points)
+        gaps_filled = 0
+        gaps.each_pair do |i, gap|
+          missing_index = i + gaps_filled # offset for previously filled gaps
+          if gap[:replace]
+            readings[missing_index].value = interpolate.at(readings[missing_index].time_start.to_i)
+          else
+            reading_before = readings[i - 1]
+            unless reading_before.nil?
+              missing_time = gap[:from]
+              until missing_time >= gap[:to]
+                new_reading = GbDataReading.new
+                new_reading.time_start = missing_time
+                new_reading.time_duration = reading_before.time_duration
+                new_reading.value = interpolate.at(missing_time.to_i)
+                readings.insert(missing_index, new_reading)
+                gaps_filled += 1
+                missing_index += 1
+                missing_time += reading_before.time_duration
+              end
+            end
+          end
+
+        end
+      end
+    end
+
+
+  end
+
+  # This error will be raised if large data gaps encountered while processing.
+  #   by default, it will check for "4 hour" gaps; this can be configured by
+  #   the "max_gap_length" attribute in seconds.
+  class TooManyDataMissingError < Exception
+
+  end
+end

data/lib/ce-bucketize/model/hour_cost.rb

@@ -0,0 +1,27 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+require 'ce-bucketize/model/hour_value'
+
+module Bucketize
+  # The consumption cost for a given hour.
+  #
+  # Author: ahmed.seddiq
+  # Version: 1.0
+  class HourCost
+    # A Time object represents the start of the hour in the local time of the
+    # consumer.
+    attr_accessor :hour_start
+
+    # The consumption value for this hour.
+    attr_accessor :value
+
+    # The consumption cost.
+    attr_accessor :cost
+
+    def initialize(hour_start, value, cost)
+      @hour_start = hour_start
+      @value = value
+      @cost = cost
+    end
+  end
+end

data/lib/ce-bucketize/model/hour_value.rb

@@ -0,0 +1,21 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+module Bucketize
+  # The consumption value for a given hour.
+  #
+  # Author: ahmed.seddiq
+  # Version: 1.0
+  class HourValue
+    # A Time object represents the start of the hour in the local time of the
+    # consumer.
+    attr_accessor :hour_start
+
+    # The consumption value for this hour.
+    attr_accessor :value
+
+    def initialize(hour_start, value)
+      @hour_start = hour_start
+      @value = value
+    end
+  end
+end

data/lib/ce-bucketize/model/tariff_rule.rb

@@ -0,0 +1,134 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+require 'json'
+require 'ce-bucketize'
+
+module Bucketize
+  # A TariffRule is the rule that defines the way in which data will be
+  #   aggregated.
+  #
+  # It provides the "applies_to" method which checks a given point in time
+  # against this rule.
+  #
+  # Author: ahmed.seddiq
+  # Version: 1.0
+  class TariffRule
+    # The maximum integer for the current machine.
+    MAX_INT = (2**((0.size * 8) - 1)) - 1
+    
+    # The utility ID related to this TariffRule.
+    attr_accessor :utility_id
+
+    # The rate class related to this TariffRule.
+    attr_accessor :rate_class
+
+    # The start Date for which this TariffRule is applied. Can be nil.
+    attr_accessor :start_date
+
+    # The end Date for which this TariffRule is applied. Can be nil.
+    attr_accessor :end_date
+
+    # The time start (hour in day) for which this TariffRule is applied.
+    #   Defaults to 1
+    attr_accessor :time_start
+
+    # The time end (hour in day) for which this TariffRule is applied.
+    #   Defaults to 24
+    attr_accessor :time_end
+
+    # An array of days for which this TariffRule is applied. Monday is 1 and
+    #   Sunday is 7
+    attr_accessor :day_of_week
+
+    # The lower bound of the monthly aggregated consumption value for which this
+    #   TariffRule is applied. Can be nil.
+    attr_accessor :kwh_low
+
+    # The upper bound of the monthly aggregated consumption value for which this
+    #   TariffRule is applied. Can be nil.
+    attr_accessor :kwh_high
+
+    # The tariff value.
+    attr_accessor :tariff
+
+    # Sets the default value for attributes.
+    def initialize
+      @time_start = 1
+      @time_end = 24
+    end
+
+    # Validates the fields of this rule.
+    #
+    # Raises Bucketize::InvalidTariffError if invalid.
+    def validate
+      not_valid_err = Bucketize::InvalidTariffError
+      raise not_valid_err, 'tariff is required' if @tariff.nil?
+      raise not_valid_err, 'time_start is require' if @time_start.nil?
+      raise not_valid_err, 'time_end is required' if @time_end.nil?
+      raise not_valid_err, 'time_end < time_start' if @time_end < @time_start
+      raise not_valid_err, 'time not in 1..24' unless @time_end.between? 1, 24
+      raise not_valid_err, 'time not in 1..24' unless @time_start.between? 1, 24
+      raise not_valid_err, 'utility_id is required' if @utility_id.nil?
+      raise not_valid_err, 'rate_class is required' if @rate_class.nil?
+
+      if not @end_date.nil? and not @start_date.nil?
+        raise not_valid_err, 'end_date < start_date' if @end_date < @start_date
+      end
+      unless @day_of_week.nil? or @day_of_week.all? { |d| d.between? 1, 7 }
+        raise not_valid_err, 'day_of_week invalid, not in 1..7 range'
+      end
+    end
+
+    # Public: Checks if this rule applies to the given time and aggregated
+    #   value.
+    #
+    # time       - the Time to check against this rule.
+    # total_kwh  - the aggregated value of the consumption till the given time.
+    #
+    # Returns true if this rule applies to the given time and aggregated value.
+    def applies_to?(time, total_kwh=nil)
+      start_date = @start_date || Time.at(0).utc
+      end_date = @end_date || Time.at(MAX_INT)
+      day_of_week = @day_of_week || (1..7).to_a
+      kwh_low = @kwh_low || 0
+      kwh_high = @kwh_high || MAX_INT
+
+      wday = time.wday
+      wday = 7 if wday == 0 # sunday is 7 not 0
+      hour = time.hour + 1 # hour from 1 - 24
+      time.between? start_date, end_date and
+          hour.between? @time_start, @time_end and
+          day_of_week.include? wday and
+          (total_kwh.nil? or total_kwh.between? kwh_low, kwh_high)
+    end
+
+
+    # This operator will be called by JSON.parse to decode the json to an
+    # instance of TariffRule
+    #
+    # key - the property name
+    # value - the property value
+    def []=(key, value)
+      # convert date properties
+      if %w(start_date end_date).include? key and !value.nil?
+        value = Date.parse(value)
+      end
+      # call the setter
+      public_send(key + '=', value)
+    end
+
+    # The equal operator. Two rules are equal if and only if all instance
+    # variables are equal.
+    #
+    # Returns whether this object equals the given object.
+    def ==(other)
+      equals = true
+      instance_variables.each do |property|
+        equals &&= (instance_variable_get(property) ==
+            other.instance_variable_get(property))
+      end
+      equals
+    end
+
+  end
+end

data/lib/ce-bucketize/tariffed_hourly_costs.rb

@@ -0,0 +1,50 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+require 'ce-bucketize/model/hour_cost'
+
+module Bucketize
+  # A collection of tariffed hourly consumption costs. This collection will be
+  # initialized by the input HourlyValues and the TariffRule(s). This collection
+  # will provide the costs after applying the given TariffRule(s).
+  #
+  # Author: ahmed.seddiq
+  # Version: 1.0
+  class TariffedHourlyCosts
+    include Enumerable
+
+    # Initializes this instance with the given hourly values and tariff rules.
+    #
+    # hourly_values - the Collection of hourly values on which the tariff rules
+    #                 will be applied.
+    # tariff_rules  - the Array of TariffRules to be used for aggregation.
+    #
+    def initialize(hourly_values, tariff_rules)
+      @hourly_values = hourly_values
+      @tariff_rules = tariff_rules
+    end
+
+    # The "each" method required by the Enumerable mixin. It yields the HourCost
+    # instances after applying the given TariffRule(s).
+    #
+    # Yields HourCost instances representing the tariffed hourly cost of the data.
+    def each(&block)
+      return enum_for(:each) if block.nil?
+
+      total_kwh = 0
+      @hourly_values.each do |h_value|
+        total_kwh += h_value.value
+        matched_rule = @tariff_rules.find {|rule| rule.applies_to? h_value.hour_start, total_kwh}
+        tariff = 1
+        tariff = matched_rule.tariff unless matched_rule.nil?
+        yield Bucketize::HourCost.new(h_value.hour_start, h_value.value,
+                                h_value.value * tariff)
+      end
+    end
+  end
+
+  # This error will be raised if no matched tariff found while calculating the
+  #   costs.
+  class NoMatchedTariffError < Exception
+
+  end
+end

data/lib/ce-bucketize/tariffed_hourly_values.rb

@@ -0,0 +1,46 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+module Bucketize
+  # An Enumerable for tariffed hourly consumption values. This collection will be
+  # initialized by the input HourlyValues and the TariffRule(s). It will provide
+  # the values after applying the given TariffRule(s). If no rule was matched
+  # , the corresponding hourly value will be returned.
+  #
+  #
+  # Author: ahmed.seddiq
+  # Version: 1.0
+  class TariffedHourlyValues
+    include Enumerable
+
+    # Initializes this instance with the given hourly values and tariff rules.
+    #
+    # hourly_values - the Collection of hourly values on which the tariff rules
+    #                 will be applied.
+    # tariff_rules  - the Array of TariffRules to be used for aggregation.
+    #
+    def initialize(hourly_values, tariff_rules)
+      @hourly_values = hourly_values
+      @tariff_rules = tariff_rules
+    end
+
+    # The "each" method required by the Enumerable mixin. It yields the HourCost
+    # instances after applying the given TariffRule(s).
+    #
+    # Yields HourCost instances representing the tariffed hourly cost of the data.
+    def each(&block)
+      return enum_for(:each) if block.nil?
+
+      total_kwh = 0
+      @hourly_values.each do |h_value|
+        total_kwh += h_value.value
+        @tariff_rules.each do |rule|
+          if rule.applies_to? h_value.hour_start, total_kwh
+            h_value.value = h_value.value * rule.tariff
+            break
+          end
+        end
+        yield h_value
+      end
+    end
+  end
+end

data/lib/ce-bucketize/version.rb

@@ -0,0 +1,5 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+module Bucketize
+  VERSION = "0.1.0"
+end