daru 0.1.3.1 → 0.1.4

data/lib/daru/date_time/offsets.rb

@@ -37,24 +37,14 @@ module Daru
     #   #=> #<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])
+      Offsets::LIST.each do |key, klass|
+        if opts.key?(key)
+          @offset = klass.new(n * opts[key])
+          break
         end
+      end
+
+      @offset = Offsets::Day.new(7*n*opts[:weeks]) if opts[:weeks]
     end
 
     # Offset a DateTime forward.
@@ -70,20 +60,46 @@ module Daru
     def - date_time
       @offset - date_time
     end
+
+    def -@
+      NegativeDateOffset.new(self)
+    end
+  end
+
+  class NegativeDateOffset
+    def initialize(offset)
+      @offset = offset
+    end
+
+    def + date_time
+      @offset - date_time
+    end
+
+    def - date_time
+      @offset + date_time
+    end
   end
 
   module Offsets
+    class DateOffsetType < DateOffset
+      def initialize n=1
+        @n = n
+      end
+
+      def freq_string
+        (@n == 1 ? '' : @n.to_s) + self.class::FREQ
+      end
+    end
+
     # Private superclass for Offsets with equal inter-frequencies.
     # @abstract
     # @private
-    class Tick < DateOffset
+    class Tick < DateOffsetType
+      # @method initialize
       # 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
@@ -102,13 +118,11 @@ module Daru
     #   offset + DateTime.new(2012,5,1,4,3)
     #   #=> #<DateTime: 2012-05-01T04:03:05+00:00 ((2456049j,14585s,0n),+0s,2299161j)>
     class Second < Tick
+      FREQ = 'S'.freeze
+
       def multiplier
         1.1574074074074073e-05
       end
-
-      def freq_string
-        (@n == 1 ? '' : @n.to_s) + 'S'
-      end
     end
 
     # Create a minutes offset
@@ -119,13 +133,11 @@ module Daru
     #   offset + DateTime.new(2012,5,1,4,3)
     #   #=> #<DateTime: 2012-05-01T04:11:00+00:00 ((2456049j,15060s,0n),+0s,2299161j)>
     class Minute < Tick
+      FREQ = 'M'.freeze
+
       def multiplier
         0.0006944444444444445
       end
-
-      def freq_string
-        (@n == 1 ? '' : @n.to_s) + 'M'
-      end
     end
 
     # Create an hours offset
@@ -136,13 +148,11 @@ module Daru
     #   offset + DateTime.new(2012,5,1,4,3)
     #   #=> #<DateTime: 2012-05-01T12:03:00+00:00 ((2456049j,43380s,0n),+0s,2299161j)>
     class Hour < Tick
+      FREQ = 'H'.freeze
+
       def multiplier
         0.041666666666666664
       end
-
-      def freq_string
-        (@n == 1 ? '' : @n.to_s) + 'H'
-      end
     end
 
     # Create an days offset
@@ -153,13 +163,11 @@ module Daru
     #   offset + DateTime.new(2012,5,1,4,3)
     #   #=> #<DateTime: 2012-05-03T04:03:00+00:00 ((2456051j,14580s,0n),+0s,2299161j)>
     class Day < Tick
+      FREQ = 'D'.freeze
+
       def multiplier
         1.0
       end
-
-      def freq_string
-        (@n == 1 ? '' : @n.to_s) + 'D'
-      end
     end
 
     # Create an months offset
@@ -170,9 +178,7 @@ module Daru
     #   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
+      FREQ = 'MONTH'.freeze
 
       def + date_time
         date_time >> @n
@@ -191,9 +197,7 @@ module Daru
     #   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
+      FREQ = 'YEAR'.freeze
 
       def + date_time
         date_time >> @n*12
@@ -247,14 +251,8 @@ module Daru
     #   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
+    class MonthBegin < DateOffsetType
+      FREQ = 'MB'.freeze
 
       def + date_time
         @n.times do
@@ -288,14 +286,8 @@ module Daru
     #   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
+    class MonthEnd < DateOffsetType
+      FREQ = 'ME'.freeze
 
       def + date_time
         @n.times do
@@ -333,14 +325,8 @@ module Daru
     #   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
+    class YearBegin < DateOffsetType
+      FREQ = 'YB'.freeze
 
       def + date_time
         DateTime.new(date_time.year + @n, 1, 1,
@@ -357,7 +343,7 @@ module Daru
       end
 
       def on_offset? date_time
-        date_time.month == 1 and date_time.day == 1
+        date_time.month == 1 && date_time.day == 1
       end
     end
 
@@ -368,14 +354,8 @@ module Daru
     #   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
+    class YearEnd < DateOffsetType
+      FREQ = 'YE'.freeze
 
       def + date_time
         if on_offset?(date_time)
@@ -392,9 +372,18 @@ module Daru
       end
 
       def on_offset? date_time
-        date_time.month == 12 and date_time.day == 31
+        date_time.month == 12 && date_time.day == 31
       end
     end
+
+    LIST = {
+      secs: Second,
+      mins: Minute,
+      hours: Hour,
+      days: Day,
+      months: Month,
+      years: Year
+    }.freeze
   end
 
   # rubocop:enable Style/OpMethod

data/lib/daru/formatters/table.rb

@@ -0,0 +1,54 @@
+module Daru
+  module Formatters
+    class Table
+      def self.format data, options={}
+        new(data, options[:headers], options[:row_headers])
+          .format(options[:threshold], options[:spacing])
+      end
+
+      def initialize(data, headers, row_headers)
+        @data = data || []
+        @headers = (headers || []).to_a
+        @row_headers = (row_headers || []).to_a
+      end
+
+      DEFAULT_SPACING = 10
+      DEFAULT_THRESHOLD = 15
+
+      def format threshold=nil, spacing=nil
+        rows = build_rows(threshold || DEFAULT_THRESHOLD)
+
+        formatter = construct_formatter rows, spacing || DEFAULT_SPACING
+
+        rows.map { |r| formatter % r }.join("\n")
+      end
+
+      private
+
+      def build_rows threshold # rubocop:disable Metrics/AbcSize
+        @row_headers.first(threshold).zip(@data).map do |(r, datarow)|
+          [*[r].flatten.map(&:to_s), *(datarow || []).map(&method(:pretty_to_s))]
+        end.tap do |rows|
+          unless @headers.empty?
+            spaces_to_add = rows.empty? ? 0 : rows.first.size - @headers.size
+            rows.unshift [''] * spaces_to_add + @headers.map(&:to_s)
+          end
+
+          rows << ['...'] * rows.first.count if @row_headers.count > threshold
+        end
+      end
+
+      def construct_formatter rows, spacing
+        width = rows.flatten.map(&:size).max
+        width = [3, width].max # not less than 'nil'
+        width = [width, spacing].min # not more than max width
+
+        " %#{width}.#{width}s" * rows.first.size
+      end
+
+      def pretty_to_s(val)
+        val.nil? ? 'nil' : val.to_s
+      end
+    end
+  end
+end

data/lib/daru/helpers/array.rb

@@ -0,0 +1,40 @@
+module Daru
+  module ArrayHelper
+    module_function
+
+    # Recode repeated values on an array, adding the number of repetition
+    # at the end
+    # Example:
+    #   a=%w{a b c c d d d e}
+    #   a.recode_repeated
+    #   => ["a","b","c_1","c_2","d_1","d_2","d_3","e"]
+    def recode_repeated(array)
+      return array if array.size == array.uniq.size
+
+      # create hash of { <name> => 0}
+      # for all names which are more than one time in array
+      counter = array
+                .group_by(&:itself)
+                .select { |_, g| g.size > 1 }
+                .map(&:first)
+                .collect { |n| [n, 0] }.to_h
+
+      # ...and use this hash for actual recode
+      array.collect do |n|
+        if counter.key?(n)
+          counter[n] += 1
+          new_n = '%s_%d' % [n, counter[n]]
+          n.is_a?(Symbol) ? new_n.to_sym : new_n
+        else
+          n
+        end
+      end
+    end
+
+    def array_of?(array, match)
+      array.is_a?(Array) &&
+        !array.empty? &&
+        array.all? { |el| match === el } # rubocop:disable Style/CaseEquality
+    end
+  end
+end

data/lib/daru/index.rb

@@ -21,19 +21,24 @@ module Daru
     # 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]
-
-      if source.respond_to?(:first) && source.first.is_a?(Array)
-        Daru::MultiIndex.from_tuples source
-      elsif source && source.is_a?(Array) && !source.empty? &&
-            source.all? { |e| e.is_a?(DateTime) }
-        Daru::DateTimeIndex.new(source, freq: :infer)
-      else
+      # FIXME: I'm not sure this clever trick really deserves our attention.
+      # Most of common ruby libraries just avoid it in favor of usual
+      # factor method, like `Index.create`. When `Index.new(...).class != Index`
+      # it just leads to confusion and surprises. - zverok, 2016-05-18
+      source = args.first
+
+      MultiIndex.try_from_tuples(source) ||
+        DateTimeIndex.try_create(source) ||
         allocate.tap { |i| i.send :initialize, *args, &block }
-      end
+    end
+
+    def self.coerce maybe_index
+      maybe_index.is_a?(Index) ? maybe_index : Daru::Index.new(maybe_index)
     end
 
     def each(&block)
+      return to_enum(:each) unless block_given?
+
       @relation_hash.each_key(&block)
       self
     end
@@ -70,36 +75,88 @@ module Daru
         @relation_hash.values == other.relation_hash.values
     end
 
-    def [](*key)
-      loc = key[0]
-
+    def [](key, *rest)
       case
-      when loc.is_a?(Range)
-        first = loc.first
-        last = loc.last
-
-        slice first, last
-      when key.size > 1
-        if include? key[0]
-          Daru::Index.new key.map { |k| k }
-        else
-          # Assume the user is specifing values for index not keys
-          # Return index object having keys corresponding to values provided
-          Daru::Index.new key.map { |k| key k }
-        end
+      when key.is_a?(Range)
+        by_range key
+      when !rest.empty?
+        by_multi_key key, *rest
       else
-        v = @relation_hash[loc]
-        unless v
-          return loc if loc.is_a?(Numeric) && loc < size
-          raise IndexError, "Specified index #{loc.inspect} does not exist"
-        end
-        v
+        by_single_key key
+      end
+    end
+
+    # Returns true if all arguments are either a valid category or position
+    # @param [Array<object>] *indexes categories or positions
+    # @return [true, false]
+    # @example
+    #   idx.valid? :a, 2
+    #   # => true
+    #   idx.valid? 3
+    #   # => false
+    def valid? *indexes
+      indexes.all? { |i| to_a.include?(i) || (i.is_a?(Numeric) && i < size) }
+    end
+
+    # Returns positions given indexes or positions
+    # @note If the arugent is both a valid index and a valid position,
+    #   it will treated as valid index
+    # @param [Array<object>] *indexes indexes or positions
+    # @example
+    #   x = Daru::Index.new [:a, :b, :c]
+    #   x.pos :a, 1
+    #   # => [0, 1]
+    def pos *indexes
+      indexes = preprocess_range(indexes.first) if indexes.first.is_a? Range
+
+      if indexes.size == 1
+        self[indexes.first]
+      else
+        indexes.map { |index| by_single_key index }
+      end
+    end
+
+    def subset *indexes
+      if indexes.first.is_a? Range
+        slice indexes.first.begin, indexes.first.end
+      elsif include? indexes.first
+        # Assume 'indexes' contain indexes not positions
+        Daru::Index.new indexes
+      else
+        # Assume 'indexes' contain positions not indexes
+        Daru::Index.new indexes.map { |k| key k }
+      end
+    end
+
+    # Takes positional values and returns subset of the self
+    #   capturing the indexes at mentioned positions
+    # @param [Array<Integer>] positional values
+    # @return [object] index object
+    # @example
+    #   idx = Daru::Index.new [:a, :b, :c]
+    #   idx.at 0, 1
+    #   # => #<Daru::Index(2): {a, b}>
+    def at *positions
+      positions = preprocess_positions(*positions)
+      validate_positions(*positions)
+      if positions.is_a? Integer
+        key(positions)
+      else
+        self.class.new positions.map(&method(:key))
+      end
+    end
+
+    def inspect threshold=20
+      if size <= threshold
+        "#<#{self.class}(#{size}): {#{to_a.join(', ')}}>"
+      else
+        "#<#{self.class}(#{size}): {#{to_a.first(threshold).join(', ')} ... #{to_a.last}}>"
       end
     end
 
     def slice *args
-      start   = args[0]
-      en      = args[1]
+      start = args[0]
+      en = args[1]
 
       if start.is_a?(Integer) && en.is_a?(Integer)
         Index.new @keys[start..en]
@@ -118,6 +175,7 @@ module Daru
 
     # Produce a new index from the set intersection of two indexes
     def & other
+      Index.new(to_a & other.to_a)
     end
 
     def to_a
@@ -125,7 +183,8 @@ module Daru
     end
 
     def key(value)
-      @relation_hash.keys[value]
+      return nil unless value.is_a?(Numeric)
+      @keys[value]
     end
 
     def include? index
@@ -140,6 +199,10 @@ module Daru
       Daru::Index.new @relation_hash.keys
     end
 
+    def add *indexes
+      Daru::Index.new(to_a + indexes)
+    end
+
     def _dump(*)
       Marshal.dump(relation_hash: @relation_hash)
     end
@@ -157,11 +220,78 @@ module Daru
     def conform(*)
       self
     end
+
+    def reorder(new_order)
+      from = to_a
+      self.class.new(new_order.map { |i| from[i] })
+    end
+
+    private
+
+    def preprocess_range rng
+      start   = rng.begin
+      en      = rng.end
+
+      if start.is_a?(Integer) && en.is_a?(Integer)
+        @keys[start..en]
+      else
+        start_idx = @relation_hash[start]
+        en_idx    = @relation_hash[en]
+
+        @keys[start_idx..en_idx]
+      end
+    end
+
+    def by_range rng
+      slice rng.begin, rng.end
+    end
+
+    def by_multi_key *key
+      if include? key[0]
+        Daru::Index.new key.map { |k| k }
+      else
+        # Assume the user is specifing values for index not keys
+        # Return index object having keys corresponding to values provided
+        Daru::Index.new key.map { |k| key k }
+      end
+    end
+
+    def by_single_key key
+      if @relation_hash.key?(key)
+        @relation_hash[key]
+      elsif key.is_a?(Numeric) && key < size
+        key
+      else
+        raise IndexError, "Specified index #{key.inspect} does not exist"
+      end
+    end
+
+    # Raises IndexError when one of the positions is an invalid position
+    def validate_positions *positions
+      positions = [positions] if positions.is_a? Integer
+      positions.each do |pos|
+        raise IndexError, "#{pos} is not a valid position." if pos >= size
+      end
+    end
+
+    # Preprocess ranges, integers and array in appropriate ways
+    def preprocess_positions *positions
+      if positions.size == 1
+        case positions.first
+        when Integer
+          positions.first
+        when Range
+          size.times.to_a[positions.first]
+        else
+          raise ArgumentError, 'Unkown position type.'
+        end
+      else
+        positions
+      end
+    end
   end # class Index
 
   class MultiIndex < Index
-    include Enumerable
-
     def each(&block)
       to_a.each(&block)
     end
@@ -179,7 +309,6 @@ module Daru
     def initialize opts={}
       labels = opts[:labels]
       levels = opts[:levels]
-
       raise ArgumentError,
         'Must specify both labels and levels' unless labels && levels
       raise ArgumentError,
@@ -188,31 +317,23 @@ module Daru
         'Incorrect labels and levels' if incorrect_fields?(labels, levels)
 
       @labels = labels
-      @levels = levels.map { |e| Hash[e.map.with_index.to_a] }
+      @levels = levels.map { |e| e.map.with_index.to_h }
     end
 
     def incorrect_fields?(_labels, levels)
-      levels[0].size # FIXME: without this call everything fails
-
-      correct = levels.all? { |e| e.uniq.size == e.size }
+      levels[0].size # FIXME: without this exact call some specs are failing
 
-      !correct
+      levels.any? { |e| e.uniq.size != e.size }
     end
 
     private :incorrect_fields?
 
     def self.from_arrays arrays
       levels = arrays.map { |e| e.uniq.sort_by(&:to_s) }
-      labels = []
 
-      arrays.each_with_index do |arry, level_index|
-        label = []
+      labels = arrays.each_with_index.map do |arry, level_index|
         level = levels[level_index]
-        arry.each do |lvl|
-          label << level.index(lvl)
-        end
-
-        labels << label
+        arry.map { |lvl| level.index(lvl) }
       end
 
       MultiIndex.new labels: labels, levels: levels
@@ -222,11 +343,21 @@ module Daru
       from_arrays tuples.transpose
     end
 
+    def self.try_from_tuples tuples
+      if tuples.respond_to?(:first) && tuples.first.is_a?(Array)
+        from_tuples(tuples)
+      else
+        nil
+      end
+    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])
+      when key[0].is_a?(Range)
+        retrieve_from_range(key[0])
+      when key[0].is_a?(Integer) && key.size == 1
+        try_retrieve_from_integer(key[0])
       else
         begin
           retrieve_from_tuples key
@@ -236,9 +367,71 @@ module Daru
       end
     end
 
+    def valid? *indexes
+      # FIXME: This is perhaps not a good method
+      pos(*indexes)
+      return true
+    rescue IndexError
+      return false
+    end
+
+    # Returns positions given indexes or positions
+    # @note If the arugent is both a valid index and a valid position,
+    #   it will treated as valid index
+    # @param [Array<object>] *indexes indexes or positions
+    # @example
+    #   idx = Daru::MultiIndex.from_tuples [[:a, :one], [:a, :two], [:b, :one], [:b, :two]]
+    #   idx.pos :a
+    #   # => [0, 1]
+    def pos *indexes
+      if indexes.first.is_a? Integer
+        return indexes.first if indexes.size == 1
+        return indexes
+      end
+      res = self[indexes]
+      return res if res.is_a? Integer
+      res.map { |i| self[i] }
+    end
+
+    def subset *indexes
+      if indexes.first.is_a? Integer
+        MultiIndex.from_tuples(indexes.map { |index| key(index) })
+      else
+        self[indexes].conform indexes
+      end
+    end
+
+    # Takes positional values and returns subset of the self
+    #   capturing the indexes at mentioned positions
+    # @param [Array<Integer>] positional values
+    # @return [object] index object
+    # @example
+    #   idx = Daru::MultiIndex.from_tuples [[:a, :one], [:a, :two], [:b, :one], [:b, :two]]
+    #   idx.at 0, 1
+    #   # => #<Daru::MultiIndex(2x2)>
+    #   #   a one
+    #   #     two
+    def at *positions
+      positions = preprocess_positions(*positions)
+      validate_positions(*positions)
+      if positions.is_a? Integer
+        key(positions)
+      else
+        Daru::MultiIndex.from_tuples positions.map(&method(:key))
+      end
+    end
+
+    def add *indexes
+      Daru::MultiIndex.from_tuples to_a << indexes
+    end
+
+    def reorder(new_order)
+      from = to_a
+      self.class.from_tuples(new_order.map { |i| from[i] })
+    end
+
     def try_retrieve_from_integer int
-      return retrieve_from_tuples([int]) if @levels[0].key?(int)
-      int
+      @levels[0].key?(int) ? retrieve_from_tuples([int]) : int
     end
 
     def retrieve_from_range range
@@ -279,17 +472,9 @@ module Daru
       raise ArgumentError,
         "Key #{index} is too large" if index >= @labels[0].size
 
-      level_indexes =
-        @labels.each_with_object([]) do |label, memo|
-          memo << label[index]
-        end
-
-      tuple = []
-      level_indexes.each_with_index do |level_index, i|
-        tuple << @levels[i].keys[level_index]
-      end
-
-      tuple
+      @labels
+        .each_with_index
+        .map { |label, i| @levels[i].keys[label[index]] }
     end
 
     def dup
@@ -309,15 +494,13 @@ module Daru
     end
 
     def empty?
-      @labels.flatten.empty? and @levels.all?(&:empty?)
+      @labels.flatten.empty? && @levels.all?(&:empty?)
     end
 
     def include? tuple
-      tuple.flatten!
-      tuple.each_with_index do |tup, i|
-        return false unless @levels[i][tup]
-      end
-      true
+      return false unless tuple.is_a? Enumerable
+      tuple.flatten.each_with_index
+           .all? { |tup, i| @levels[i][tup] }
     end
 
     def size
@@ -342,8 +525,14 @@ module Daru
       Array.new(size) { |i| i }
     end
 
-    def inspect
-      "Daru::MultiIndex:#{object_id} (levels: #{levels}\nlabels: #{labels})"
+    def inspect threshold=20
+      "#<Daru::MultiIndex(#{size}x#{width})>\n" +
+        Formatters::Table.format([], row_headers: sparse_tuples, threshold: threshold)
+    end
+
+    def to_html
+      path = File.expand_path('../iruby/templates/multi_index.html.erb', __FILE__)
+      ERB.new(File.read(path).strip).result(binding)
     end
 
     # Provide a MultiIndex for sub vector produced
@@ -354,5 +543,219 @@ module Daru
       return self if input_indexes[0].is_a? Range
       drop_left_level input_indexes.size
     end
+
+    # Return tuples with nils in place of repeating values, like this:
+    #
+    # [:a , :bar, :one]
+    # [nil, nil , :two]
+    # [nil, :foo, :one]
+    #
+    def sparse_tuples
+      tuples = to_a
+      [tuples.first] + each_cons(2).map { |prev, cur|
+        left = cur.zip(prev).drop_while { |c, p| c == p }
+        [nil] * (cur.size - left.size) + left.map(&:first)
+      }
+    end
+  end
+
+  class CategoricalIndex < Index
+    # Create a categorical index object.
+    # @param indexes [Array<object>] array of indexes
+    # @return [Daru::CategoricalIndex] categorical index
+    # @example
+    #   Daru::CategoricalIndex.new [:a, 1, :a, 1, :c]
+    #   # => #<Daru::CategoricalIndex(5): {a, 1, a, 1, c}>
+    def initialize indexes
+      # Create a hash to map each category to positional indexes
+      categories = indexes.each_with_index.group_by(&:first)
+      @cat_hash = categories.map { |cat, group| [cat, group.map(&:last)] }.to_h
+
+      # Map each category to a unique integer for effective storage in @array
+      map_cat_int = categories.keys.each_with_index.to_h
+
+      # To link every instance to its category,
+      # it stores integer for every instance representing its category
+      @array = map_cat_int.values_at(*indexes)
+    end
+
+    # Duplicates the index object and return it
+    # @return [Daru::CategoricalIndex] duplicated index object
+    def dup
+      # Improve it by intializing index by hash
+      Daru::CategoricalIndex.new to_a
+    end
+
+    # Returns true index or category is valid
+    # @param index [object] the index value to look for
+    # @return [true, false] true if index is included, false otherwise
+    def include? index
+      @cat_hash.include? index
+    end
+
+    # Returns array of categories
+    # @example
+    #   x = Daru::CategoricalIndex.new [:a, 1, :a, 1, :c]
+    #   x.categories
+    #   # => [:a, 1, :c]
+    def categories
+      @cat_hash.keys
+    end
+
+    # Returns positions given categories or positions
+    # @note If the argument does not a valid category it treats it as position
+    #   value and return it as it is.
+    # @param [Array<object>] *indexes categories or positions
+    # @example
+    #   x = Daru::CategoricalIndex.new [:a, 1, :a, 1, :c]
+    #   x.pos :a, 1
+    #   # => [0, 1, 2, 3]
+    def pos *indexes
+      positions = indexes.map do |index|
+        if include? index
+          @cat_hash[index]
+        elsif index.is_a?(Numeric) && index < @array.size
+          index
+        else
+          raise IndexError, "#{index.inspect} is neither a valid category"\
+            ' nor a valid position'
+        end
+      end
+
+      positions.flatten!
+      positions.size == 1 ? positions.first : positions.sort
+    end
+
+    # Returns index value from position
+    # @param pos [Integer] the position to look for
+    # @return [object] category corresponding to position
+    # @example
+    #   idx = Daru::CategoricalIndex.new [:a, :b, :a, :b, :c]
+    #   idx.index_from_pos 1
+    #   # => :b
+    def index_from_pos pos
+      cat_from_int @array[pos]
+    end
+
+    # Returns enumerator enumerating all index values in the order they occur
+    # @return [Enumerator] all index values
+    # @example
+    #   idx = Daru::CategoricalIndex.new [:a, :a, :b]
+    #   idx.each.to_a
+    #   # => [:a, :a, :b]
+    def each
+      return enum_for(:each) unless block_given?
+      @array.each { |pos| yield cat_from_int pos }
+      self
+    end
+
+    # Compares two index object. Returns true if every instance of category
+    # occur at the same position
+    # @param [Daru::CateogricalIndex] other index object to be checked against
+    # @return [true, false] true if other is similar to self
+    # @example
+    #   a = Daru::CategoricalIndex.new [:a, :a, :b]
+    #   b = Daru::CategoricalIndex.new [:b, :a, :a]
+    #   a == b
+    #   # => false
+    def == other
+      self.class == other.class &&
+        size == other.size &&
+        to_h == other.to_h
+    end
+
+    # Returns all the index values
+    # @return [Array] all index values
+    # @example
+    #   idx = Daru::CategoricalIndex.new [:a, :b, :a]
+    #   idx.to_a
+    def to_a
+      each.to_a
+    end
+
+    # Returns hash table mapping category to positions at which they occur
+    # @return [Hash] hash table mapping category to array of positions
+    # @example
+    #   idx = Daru::CategoricalIndex.new [:a, :b, :a]
+    #   idx.to_h
+    #   # => {:a=>[0, 2], :b=>[1]}
+    def to_h
+      @cat_hash
+    end
+
+    # Returns size of the index object
+    # @return [Integer] total number of instances of all categories
+    # @example
+    #   idx = Daru::CategoricalIndex.new [:a, :b, :a]
+    #   idx.size
+    #   # => 3
+    def size
+      @array.size
+    end
+
+    # Returns true if index object is storing no category
+    # @return [true, false] true if index object is empty
+    # @example
+    #   i = Daru::CategoricalIndex.new []
+    #   # => #<Daru::CategoricalIndex(0): {}>
+    #   i.empty?
+    #   # => true
+    def empty?
+      @array.empty?
+    end
+
+    # Return subset given categories or positions
+    # @param [Array<object>] *indexes categories or positions
+    # @return [Daru::CategoricalIndex] subset of the self containing the
+    #   mentioned categories or positions
+    # @example
+    #   idx = Daru::CategoricalIndex.new [:a, :b, :a, :b, :c]
+    #   idx.subset :a, :b
+    #   # => #<Daru::CategoricalIndex(4): {a, b, a, b}>
+    def subset *indexes
+      positions = pos(*indexes)
+      new_index = positions.map { |pos| index_from_pos pos }
+
+      Daru::CategoricalIndex.new new_index.flatten
+    end
+
+    # Takes positional values and returns subset of the self
+    #   capturing the categories at mentioned positions
+    # @param [Array<Integer>] positional values
+    # @return [object] index object
+    # @example
+    #   idx = Daru::CategoricalIndex.new [:a, :b, :a, :b, :c]
+    #   idx.at 0, 1
+    #   # => #<Daru::CategoricalIndex(2): {a, b}>
+    def at *positions
+      positions = preprocess_positions(*positions)
+      validate_positions(*positions)
+      if positions.is_a? Integer
+        index_from_pos(positions)
+      else
+        Daru::CategoricalIndex.new positions.map(&method(:index_from_pos))
+      end
+    end
+
+    # Add specified index values to the index object
+    # @param [Array<object>] *indexes index values to add
+    # @return [Daru::CategoricalIndex] index object with added values
+    # @example
+    #   idx = Daru::CategoricalIndex.new [:a, :b, :a, :b, :c]
+    #   idx.add :d
+    #   # => #<Daru::CategoricalIndex(6): {a, b, a, b, c, d}>
+    def add *indexes
+      Daru::CategoricalIndex.new(to_a + indexes)
+    end
+
+    private
+
+    def int_from_cat cat
+      @cat_hash.keys.index cat
+    end
+
+    def cat_from_int cat
+      @cat_hash.keys[cat]
+    end
   end
 end