daru 0.1.0 → 0.1.1

data/lib/daru/date_time/offsets.rb

@@ -0,0 +1,397 @@
+module Daru
+  # Generic class for generating date offsets.
+  class DateOffset
+    # A Daru::DateOffset object is created by a passing certain options
+    # to the constructor, which determine the kind of offset the object
+    # will support.
+    #
+    # You can pass one of the following options followed by their number
+    # to the DateOffset constructor:
+    #
+    # * :secs - Create a seconds offset
+    # * :mins - Create a minutes offset
+    # * :hours - Create an hours offset
+    # * :days  - Create a days offset
+    # * :weeks - Create a weeks offset
+    # * :months - Create a months offset
+    # * :years - Create a years offset
+    # 
+    # Additionaly, passing the `:n` option will apply the offset that many times.
+    #
+    # @example Usage of DateOffset
+    #   # Create an offset of 3 weeks.
+    #   offset = Daru::DateOffset.new(weeks: 3)
+    #   offset + DateTime.new(2012,5,3)
+    #   #=> #<DateTime: 2012-05-24T00:00:00+00:00 ((2456072j,0s,0n),+0s,2299161j)>
+    #  
+    #   # Create an offset of 5 hours
+    #   offset = Daru::DateOffset.new(hours: 5)
+    #   offset + DateTime.new(2015,3,3,23,5,1)
+    #   #=> #<DateTime: 2015-03-04T04:05:01+00:00 ((2457086j,14701s,0n),+0s,2299161j)>
+    #
+    #   # Create an offset of 2 minutes, applied 5 times
+    #   offset = Daru::DateOffset.new(mins: 2, n: 5)
+    #   offset + DateTime.new(2011,5,3,3,5)
+    #   #=> #<DateTime: 2011-05-03T03:15:00+00:00 ((2455685j,11700s,0n),+0s,2299161j)>
+    def initialize opts={}
+      n = opts[:n] || 1
+
+      @offset =
+      case 
+      when opts[:secs]
+        Offsets::Second.new(n*opts[:secs])
+      when opts[:mins]
+        Offsets::Minute.new(n*opts[:mins])
+      when opts[:hours]
+        Offsets::Hour.new(n*opts[:hours])
+      when opts[:days]
+        Offsets::Day.new(n*opts[:days])
+      when opts[:weeks]
+        Offsets::Day.new(7*n*opts[:weeks])
+      when opts[:months]
+        Offsets::Month.new(n*opts[:months])
+      when opts[:years]
+        Offsets::Year.new(n*opts[:years])
+      end
+    end
+
+    # Offset a DateTime forward.
+    #
+    # @param date_time [DateTime] A DateTime object which is to offset.
+    def + date_time
+      @offset + date_time
+    end
+
+    # Offset a DateTime backward.
+    #
+    # @param date_time [DateTime] A DateTime object which is to offset.
+    def - date_time
+      @offset - date_time
+    end
+  end
+
+  module Offsets
+    # Private superclass for Offsets with equal inter-frequencies.
+    # @abstract
+    # @private
+    class Tick < DateOffset
+      # Initialize one of the subclasses of Tick with the number of the times
+      # the offset should be applied, which is the supplied as the argument.
+      #
+      # @param n [Integer] The number of times an offset should be applied.
+      def initialize n=1
+        @n = n
+      end
+
+      def + date_time
+        date_time + @n*multiplier
+      end
+
+      def - date_time
+        date_time - @n*multiplier
+      end
+    end
+
+    # Create a seconds offset
+    # 
+    # @param n [Integer] The number of times an offset should be applied.
+    # @example Create a Seconds offset
+    #   offset = Daru::Offsets::Second.new(5)
+    #   offset + DateTime.new(2012,5,1,4,3)
+    #   #=> #<DateTime: 2012-05-01T04:03:05+00:00 ((2456049j,14585s,0n),+0s,2299161j)>
+    class Second < Tick
+      def multiplier
+        1.1574074074074073e-05
+      end
+
+      def freq_string
+        (@n == 1 ? '' : @n.to_s) + 'S'
+      end
+    end
+
+    # Create a minutes offset
+    # 
+    # @param n [Integer] The number of times an offset should be applied.
+    # @example Create a Minutes offset
+    #   offset = Daru::Offsets::Minute.new(8)
+    #   offset + DateTime.new(2012,5,1,4,3)
+    #   #=> #<DateTime: 2012-05-01T04:11:00+00:00 ((2456049j,15060s,0n),+0s,2299161j)>
+    class Minute < Tick
+      def multiplier
+        0.0006944444444444445
+      end
+
+      def freq_string
+        (@n == 1 ? '' : @n.to_s) + 'M'
+      end
+    end
+
+    # Create an hours offset
+    # 
+    # @param n [Integer] The number of times an offset should be applied.
+    # @example Create a Hour offset
+    #   offset = Daru::Offsets::Hour.new(8)
+    #   offset + DateTime.new(2012,5,1,4,3)
+    #   #=> #<DateTime: 2012-05-01T12:03:00+00:00 ((2456049j,43380s,0n),+0s,2299161j)>
+    class Hour < Tick
+      def multiplier
+        0.041666666666666664
+      end
+      
+      def freq_string
+        (@n == 1 ? '' : @n.to_s) + 'H'
+      end
+    end
+
+    # Create an days offset
+    # 
+    # @param n [Integer] The number of times an offset should be applied.
+    # @example Create a Day offset
+    #   offset = Daru::Offsets::Day.new(2)
+    #   offset + DateTime.new(2012,5,1,4,3)
+    #   #=> #<DateTime: 2012-05-03T04:03:00+00:00 ((2456051j,14580s,0n),+0s,2299161j)>
+    class Day < Tick
+      def multiplier
+        1.0
+      end
+
+      def freq_string
+        (@n == 1 ? '' : @n.to_s) + 'D'
+      end
+    end
+
+    # Create an months offset
+    # 
+    # @param n [Integer] The number of times an offset should be applied.
+    # @example Create a Month offset
+    #   offset = Daru::Offsets::Month.new(5)
+    #   offset + DateTime.new(2012,5,1,4,3)
+    #   #=> #<DateTime: 2012-10-01T04:03:00+00:00 ((2456202j,14580s,0n),+0s,2299161j)>
+    class Month < Tick
+      def freq_string
+        (@n == 1 ? '' : @n.to_s) + 'MONTH'
+      end
+
+      def + date_time
+        date_time >> @n
+      end
+
+      def - date_time
+        date_time << @n
+      end
+    end
+
+    # Create a years offset
+    # 
+    # @param n [Integer] The number of times an offset should be applied.
+    # @example Create a Year offset
+    #   offset = Daru::Offsets::Year.new(2)
+    #   offset + DateTime.new(2012,5,1,4,3)
+    #   #=> #<DateTime: 2014-05-01T04:03:00+00:00 ((2456779j,14580s,0n),+0s,2299161j)>
+    class Year < Tick
+      def freq_string
+        (@n == 1 ? '' : @n.to_s) + 'YEAR'
+      end
+
+      def + date_time
+        date_time >> @n*12
+      end
+
+      def - date_time
+        date_time << @n*12
+      end
+    end
+
+    class Week < DateOffset
+      def initialize *args
+        @n = !args[0].is_a?(Hash)? args[0] : 1
+        opts = args[-1]
+        @weekday = opts[:weekday] || 0
+      end
+
+      def + date_time
+        wday = date_time.wday
+        distance = (@weekday - wday).abs
+        if @weekday > wday
+          date_time + distance + 7*(@n-1)
+        else
+          date_time + (7-distance) + 7*(@n -1)
+        end
+      end
+
+      def - date_time
+        wday = date_time.wday
+        distance = (@weekday - wday).abs
+        if @weekday >= wday
+          date_time - ((7 - distance) + 7*(@n -1))
+        else
+          date_time - (distance + 7*(@n-1))
+        end
+      end
+
+      def on_offset? date_time
+        date_time.wday == @weekday
+      end
+
+      def freq_string
+        (@n == 1 ? '' : @n.to_s) + 'W' + '-' + Daru::DAYS_OF_WEEK.key(@weekday)
+      end
+    end
+
+    # Create a month begin offset
+    # 
+    # @param n [Integer] The number of times an offset should be applied.
+    # @example Create a MonthBegin offset
+    #   offset = Daru::Offsets::MonthBegin.new(2)
+    #   offset + DateTime.new(2012,5,5)
+    #   #=> #<DateTime: 2012-07-01T00:00:00+00:00 ((2456110j,0s,0n),+0s,2299161j)>
+    class MonthBegin < DateOffset
+      def initialize n=1
+        @n = n
+      end
+
+      def freq_string
+        (@n == 1 ? '' : @n.to_s) + "MB"
+      end
+
+      def + date_time
+        @n.times do
+          days_in_month = Daru::MONTH_DAYS[date_time.month]
+          days_in_month += 1 if date_time.leap? and date_time.month == 2
+          date_time = date_time + (days_in_month - date_time.day + 1)
+        end
+
+        date_time
+      end
+
+      def - date_time
+        @n.times do
+          date_time = date_time << 1 if on_offset?(date_time)
+          date_time = DateTime.new(date_time.year, date_time.month, 1, 
+            date_time.hour, date_time.min, date_time.sec)
+        end
+
+        date_time
+      end
+
+      def on_offset? date_time
+        date_time.day == 1
+      end
+    end
+
+    # Create a month end offset
+    # 
+    # @param n [Integer] The number of times an offset should be applied.
+    # @example Create a MonthEnd offset
+    #   offset = Daru::Offsets::MonthEnd.new
+    #   offset + DateTime.new(2012,5,5)
+    #   #=> #<DateTime: 2012-05-31T00:00:00+00:00 ((2456079j,0s,0n),+0s,2299161j)>
+    class MonthEnd < DateOffset
+      def initialize n=1
+        @n = n
+      end
+
+      def freq_string
+        (@n == 1 ? '' : @n.to_s) + 'ME'
+      end
+
+      def + date_time
+        @n.times do 
+          date_time     = date_time >> 1 if on_offset?(date_time)
+          days_in_month = Daru::MONTH_DAYS[date_time.month]
+          days_in_month += 1 if date_time.leap? and date_time.month == 2
+
+          date_time = date_time + (days_in_month - date_time.day)
+        end
+
+        date_time
+      end
+
+      def - date_time
+        @n.times do 
+          date_time = date_time << 1
+          days_in_month = Daru::MONTH_DAYS[date_time.month]
+          days_in_month += 1 if date_time.leap? and date_time.month == 2
+
+          date_time = date_time + (days_in_month - date_time.day)
+        end
+
+        date_time
+      end
+
+      def on_offset? date_time
+        (date_time + 1).day == 1
+      end
+    end
+
+    # Create a year begin offset
+    # 
+    # @param n [Integer] The number of times an offset should be applied.
+    # @example Create a YearBegin offset
+    #   offset = Daru::Offsets::YearBegin.new(3)
+    #   offset + DateTime.new(2012,5,5)
+    #   #=> #<DateTime: 2015-01-01T00:00:00+00:00 ((2457024j,0s,0n),+0s,2299161j)>
+    class YearBegin < DateOffset
+      def initialize n=1
+        @n = n
+      end
+
+      def freq_string
+        (@n == 1 ? '' : @n.to_s) + 'YB'
+      end
+
+      def + date_time
+        DateTime.new(date_time.year + @n, 1, 1,
+          date_time.hour,date_time.min, date_time.sec)
+      end
+
+      def - date_time
+        if on_offset?(date_time)
+          DateTime.new(date_time.year - @n, 1, 1, 
+            date_time.hour,date_time.min, date_time.sec)
+        else
+          DateTime.new(date_time.year - (@n-1), 1, 1)
+        end
+      end
+
+      def on_offset? date_time
+        date_time.month == 1 and date_time.day == 1
+      end
+    end
+
+    # Create a year end offset
+    # 
+    # @param n [Integer] The number of times an offset should be applied.
+    # @example Create a YearEnd offset
+    #   offset = Daru::Offsets::YearEnd.new
+    #   offset + DateTime.new(2012,5,5)
+    #   #=> #<DateTime: 2012-12-31T00:00:00+00:00 ((2456293j,0s,0n),+0s,2299161j)>
+    class YearEnd < DateOffset
+      def initialize n=1
+        @n = n
+      end
+
+      def freq_string
+        (@n == 1 ? '' : @n.to_s) + 'YE'
+      end
+
+      def + date_time
+        if on_offset?(date_time)
+          DateTime.new(date_time.year + @n, 12, 31,
+            date_time.hour, date_time.min, date_time.sec)
+        else
+          DateTime.new(date_time.year + (@n-1), 12, 31,
+            date_time.hour, date_time.min, date_time.sec)
+        end
+      end
+
+      def - date_time
+        DateTime.new(date_time.year - 1, 12, 31)
+      end
+
+      def on_offset? date_time
+        date_time.month == 12 and date_time.day == 31
+      end
+    end
+  end
+end

data/lib/daru/index.rb

@@ -1,6 +1,42 @@
 module Daru
   class Index
     include Enumerable
+    # It so happens that over riding the .new method in a super class also
+    # tampers with the default .new method for class that inherit from the
+    # super class (Index in this case). Thus we first alias the original 
+    # new method (from Object) to __new__ when the Index class is evaluated, 
+    # and then we use an inherited hook such that the old new method (from
+    # Object) is once again the default .new for the subclass.
+    # Refer http://blog.sidu.in/2007/12/rubys-new-as-factory.html
+    class << self
+      alias :__new__ :new
+      
+      def inherited subclass
+        class << subclass
+          alias :new :__new__
+        end
+      end
+    end
+
+    # We over-ride the .new method so that any sort of Index can be generated
+    # from Daru::Index based on the types of arguments supplied.
+    def self.new *args, &block
+      source = args[0]
+
+      idx =
+      if source and source[0].is_a?(Array)
+        Daru::MultiIndex.from_tuples source
+      elsif source and source.is_a?(Array) and !source.empty? and 
+        source.all? { |e| e.is_a?(DateTime) }
+        Daru::DateTimeIndex.new(source, freq: :infer)
+      else
+        i = self.allocate
+        i.send :initialize, *args, &block
+        i
+      end
+
+      idx
+    end
 
     def each(&block)
       @relation_hash.each_key(&block)
@@ -11,84 +47,73 @@ module Daru
       to_a.map(&block)
     end
 
-    attr_reader :relation_hash
-
-    attr_reader :size
-
-    attr_reader :index_class
-
-    def initialize index, values=nil
-      @relation_hash = {}
+    attr_reader :relation_hash, :size
 
+    def initialize index
       index = 0                         if index.nil?
       index = Array.new(index) { |i| i} if index.is_a? Integer
       index = index.to_a                if index.is_a? Daru::Index
 
-      if values.nil?
-        index.each_with_index do |n, idx|
-          n = n.to_sym unless n.is_a?(Integer)
-
-          @relation_hash[n] = idx 
-        end
-      else
-        raise IndexError, "Size of values : #{values.size} and index : #{index.size} do not match" if
-          index.size != values.size
-
-        values.each_with_index do |value,i|
-          @relation_hash[index[i]] = value
-        end
+      @relation_hash = {}
+      index.each_with_index do |n, idx|
+        @relation_hash[n] = idx 
       end
 
       @relation_hash.freeze
+      @keys = @relation_hash.keys
       @size = @relation_hash.size
-
-      if index[0].is_a?(Integer)
-        @index_class = Integer
-      else
-        @index_class = Symbol
-      end
     end
 
     def ==(other)
-      return false if other.size != @size
+      return false if self.class != other.class or other.size != @size
 
-      @relation_hash.keys == other.to_a and @relation_hash.values == other.relation_hash.values
+      @relation_hash.keys   == other.to_a and 
+      @relation_hash.values == other.relation_hash.values
     end
 
-    def [](key)
-      case key
-      when Range
-        if key.first.is_a?(Integer) and key.last.is_a?(Integer)
-          first = key.first
-          last = key.last
-        else
-          first = @relation_hash[key.first]
-          last  = @relation_hash[key.last]
-        end
+    def [](*key)
+      loc = key[0]
 
-        indexes = []
-        (first..last).each do |idx|
-          indexes << @relation_hash.key(idx)
-        end
+      case 
+      when loc.is_a?(Range)
+        first = loc.first
+        last = loc.last
 
-        Daru::Index.new indexes, (first..last).to_a
-      when Array # works only with numeric indices
-        Daru::Index.new key.map { |k| @relation_hash.key(k) }, key
+        slice first, last
+      when key.size > 1
+        Daru::Index.new key.map { |k| self[k] }
       else
-        @relation_hash[key]
+        v = @relation_hash[loc]
+        return loc if v.nil?
+        v
       end
     end
 
-    def +(other)
-      if other.respond_to? :relation_hash #another index object
-        (@relation_hash.keys + other.relation_hash.keys).uniq.to_index
-      elsif other.is_a?(Symbol) or other.is_a?(Integer)
-        (@relation_hash.keys << other).uniq.to_index
+    def slice *args
+      start   = args[0]
+      en      = args[1]
+      indexes = []
+
+      if start.is_a?(Integer) and en.is_a?(Integer)
+        Index.new @keys[start..en]
       else
-        (@relation_hash.keys + other).uniq.to_index
+        start_idx = @relation_hash[start]
+        en_idx    = @relation_hash[en]
+
+        Index.new @keys[start_idx..en_idx]
       end
     end
 
+    # Produce new index from the set union of two indexes.
+    def |(other)
+      Index.new(to_a | other.to_a)
+    end
+
+    # Produce a new index from the set intersection of two indexes
+    def & other
+      
+    end
+
     def to_a
       @relation_hash.keys
     end
@@ -116,7 +141,194 @@ module Daru
     def self._load data
       h = Marshal.load data
 
-      Daru::Index.new(h[:relation_hash].keys, h[:relation_hash].values)
+      Daru::Index.new(h[:relation_hash].keys)
+    end
+  end # class Index
+
+  class MultiIndex < Index
+    include Enumerable
+
+    def each(&block)
+      to_a.each(&block)  
+    end
+
+    def map(&block)
+      to_a.map(&block)
+    end
+
+    attr_reader :labels
+
+    def levels
+      @levels.map { |e| e.keys }
+    end
+
+    def initialize opts={}
+      labels = opts[:labels]
+      levels = opts[:levels]
+
+      raise ArgumentError, 
+        "Must specify both labels and levels" unless labels and levels
+      raise ArgumentError,
+        "Labels and levels should be same size" if labels.size != levels.size
+      raise ArgumentError,
+        "Incorrect labels and levels" if incorrect_fields?(labels, levels)
+
+      @labels = labels
+      @levels = levels.map { |e| Hash[e.map.with_index.to_a]}
+    end
+
+    def incorrect_fields? labels, levels
+      max_level = levels[0].size
+
+      correct = labels.all? { |e| e.size == max_level }
+      correct = levels.all? { |e| e.uniq.size == e.size }
+
+      !correct
+    end
+
+    private :incorrect_fields?
+
+    def self.from_arrays arrays
+      levels = arrays.map { |e| e.uniq.sort_by { |a| a.to_s  } }
+      labels = []
+
+      arrays.each_with_index do |arry, level_index|
+        label = []
+        level = levels[level_index]
+        arry.each do |lvl|
+          label << level.index(lvl)
+        end
+
+        labels << label
+      end
+
+      MultiIndex.new labels: labels, levels: levels
+    end
+
+    def self.from_tuples tuples
+      from_arrays tuples.transpose
+    end
+
+    def [] *key
+      key.flatten!
+      case
+      when key[0].is_a?(Range) then retrieve_from_range(key[0])
+      when (key[0].is_a?(Integer) and key.size == 1) then try_retrieve_from_integer(key[0])
+      else retrieve_from_tuples(key)
+      end
+    end
+
+    def try_retrieve_from_integer int
+      return retrieve_from_tuples([int]) if @levels[0].has_key?(int)
+      int
+    end
+
+    def retrieve_from_range range
+      MultiIndex.from_tuples(range.map { |index| key(index) })
+    end
+
+    def retrieve_from_tuples key
+      chosen = []
+
+      key.each_with_index do |k, depth|
+        level_index = @levels[depth][k]
+        label = @labels[depth]
+        chosen = find_all_indexes label, level_index, chosen
+      end
+
+      return chosen[0] if chosen.size == 1
+      return multi_index_from_multiple_selections(chosen)              
+    end
+
+    def multi_index_from_multiple_selections chosen
+      MultiIndex.from_tuples(chosen.map { |e| key(e) })
+    end
+
+    def find_all_indexes label, level_index, chosen
+      if chosen.empty?
+        label.each_with_index do |lbl, i|
+          if lbl == level_index then chosen << i end
+        end
+      else
+        chosen.keep_if { |c| label[c] == level_index }
+      end
+
+      chosen
+    end
+
+    private :find_all_indexes, :multi_index_from_multiple_selections,
+      :retrieve_from_range, :retrieve_from_tuples
+
+    def key index
+      raise ArgumentError,
+        "Key #{index} is too large" if index >= @labels[0].size
+
+      level_indexes = 
+      @labels.inject([]) do |memo, label|
+        memo << label[index]
+        memo
+      end
+
+      tuple = []
+      level_indexes.each_with_index do |level_index, i|
+        tuple << @levels[i].keys[level_index]
+      end
+
+      tuple
+    end
+
+    def dup
+      MultiIndex.new levels: levels.dup, labels: labels
+    end
+
+    def drop_left_level by=1
+      MultiIndex.from_arrays to_a.transpose[by..-1]
+    end
+
+    def | other
+      MultiIndex.from_tuples(to_a | other.to_a)
+    end
+
+    def & other
+      MultiIndex.from_tuples(to_a & other.to_a)
+    end
+
+    def empty?
+      @labels.flatten.empty? and @levels.all? { |l| l.empty? }
+    end
+
+    def include? tuple
+      tuple.flatten!
+      tuple.each_with_index do |tup, i|
+        return false unless @levels[i][tup]
+      end
+      true
+    end
+
+    def size
+      @labels[0].size
+    end
+
+    def width
+      @levels.size
+    end
+
+    def == other
+      self.class == other.class  and 
+      labels     == other.labels and 
+      levels     == other.levels 
+    end
+
+    def to_a
+      (0...size).map { |e| key(e) }
+    end
+
+    def values
+      Array.new(size) { |i| i }
+    end
+
+    def inspect
+      "Daru::MultiIndex:#{self.object_id} (levels: #{levels}\nlabels: #{labels})"
     end
   end
 end