multimatrix 0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 270b3c84f142d440457ef16d2f3632351234d405
+  data.tar.gz: 58401fba050650b4aa3e076fd050c7de8a8159a2
+SHA512:
+  metadata.gz: aa9c8a1215fd93ce7d6bf575f674f42bde33c06a7554ef7c73de7fef07c8a940604eec01a7485790d8044d60be790922844aa627b467cd4cd14002b9de43e454
+  data.tar.gz: ca4e08406a23535a8856fb48852cba777b6371da47dbcdb123d570f1a887f2c241416e6a674524a4389b0d98fb99db09b3a8c5f4e1e49e12ebe16ff2b1b05b01

data/lib/multimatrix.rb

@@ -0,0 +1,296 @@
+class MultiMatrixException < Exception
+end
+
+# An n-dimensonal matrix, where dimensions are labels
+#
+# Imagine: your urgent need is to store a dataset more than 1 or 2 dimensions large.
+# The default way to do this is tu use multi dimensional arrays, like "array[][][]" for
+# example. Inserting or retrieveing a value from this dataset would be kind of an easy task,
+# but what happens when You have to summarize all the elements of a dimension. For example
+# sum all the elements where the second level array's index is 2. You have to loop through
+# n*n*n elements, just to find some of them. Tedious.
+#
+# MultiMatrix comes to the rescue.
+#
+# MultiMatrix makes it easy to create multi-level data structures, and makes finding and looping through
+# them nice and easy. And fast.
+#
+# @author Gergely Dömsödi <mailto:gergely.domsodi@uhusystems.com>
+#
+# To easily show an example, and concept of this class let's see a 2 dimensional array
+#
+# m = MultiMatrix.new(:x, :y)
+# m.insert(:x => 1, :y = 3) = 10
+# m.insert(:x => 2, :y = 1) = 20
+# m.insert(:x => 2, :y =>2) = 30
+#
+# could be imagined as
+#    x| 1 | 2 | 3 |
+#   y |___|___|___|
+#   1 | ? | 20| ? |
+#     |___|___|___|
+#   2 | ? | 30| ? |
+#     |___|___|___|
+#   3 | 10| ? | ? |
+#     |___|___|___|
+#
+#  >> m.sum(x: 2)
+#  => 50
+#  >> m.sum(x: 3)
+#  => 0
+#  >> m.to_a(y: 2)
+#  => [30]
+#  >> m[:x => 1, :y => 1]
+#  => nil
+#  >> m[:x => 3] == MultiMatrix.new(:y)
+#  => true
+#
+# Usage:
+#
+#  >> x = MultiMatrix.new(:x, :y, :z)
+#  >> x[:x => 1, :y => 1, :z => 1] = 1
+#  >> x[:x => 1, :y => 1, :z => 2] = 1
+#  >> x[:x => 2, :y => 1, :z => 2] = 1
+#
+#  >> x[:x => 1, :y => 1, :z => 1]
+#  => 1
+#
+#  >> x[:x => 1, :y => 1]
+#  => MultiMatrix({:z=>2}=>2)
+#
+#  >> x.sum(:x => 1)
+#  => 2
+#  >> x.sum(:z => 1)
+#  => 1
+#  >> x.to_a(:z => 1)
+#  => [1]
+#
+# Wait! There is more:
+#
+#  >> x[:z => [1,2]]
+#  => [1,1,1]
+#  >> x.sum(:z => [1,2])
+#  => 3
+
+class MultiMatrix
+
+  # Creates a new MultiMatrix object, where labels will be the dimensions of the dataset
+  # use labels appropriate for Hash keys, because they will be stored as such internally.
+  # labels could be Symbols, Integers, even ActiveModel objects, the only requirement for it that it have to
+  # have a meaningful == method.
+  # @param labels an [Array] of values to be used as dimension labels
+  def initialize(*labelskeys)
+    raise MultiMatrixException, "no dimensions" if labelskeys.length == 0
+    @labels = labelskeys
+    @dim = @labels.length
+    @values = Hash.new
+    @values_by_id = Hash.new
+    @labels_by_id = Hash.new
+    @sumcache = {}
+    @seq = 0
+    @finderhash = {}
+  end
+
+  # Inserts a value to the data set.
+  #
+  # @param labels [Hash] the position where to insert the value.
+  #   beware, at insert all dimension of the positin must be given
+  # @param value The value to be inserted
+  # @return [true] on success, raises MultiMatrixException otherwise
+  def insert(labels, value)
+    if check_labels(labels) and labels.keys.length == @dim
+      if @values.key?(labels)
+        id = @values[labels]
+        if block_given?
+          save_value(labels, yield(get_value(labels), value), :override => id)
+        else
+          save_value(labels, get_value(labels) + value, :override => id)
+        end
+      else
+        save_value(labels, value)
+      end
+    else
+      raise MultiMatrixException, 'not enough key supplied'
+    end
+    @sumcache = {}
+    true
+  end
+
+  # Executes block on all value at position given by labels
+  # @param labels finder hash
+  def each(labels = {})
+    if check_labels(labels) and labels.keys.length <= @dim
+      ids = find_ids(labels)
+      ids.each do |id|
+        if block_given?
+          yield @values_by_id[id]
+        end
+      end
+    end
+  end
+
+  # Same as Enumerable#inject, but filter hash is accepted
+  # @param labels finder hash
+  # @param default beginning value of the memo
+  def inject(labels = {}, default = 0)
+    memo = default
+    if check_labels(labels) and labels.keys.length <= @dim
+      ids = find_ids(labels)
+      ids.each do |id|
+        if block_given?
+          memo = yield memo, @values_by_id[id]
+        end
+      end
+    end
+    return memo
+  end
+
+  # Returns an array of values matching @param labels
+  # @param labels finder hash
+  # @return [Array] values found
+  def to_a(labels = {})
+    if check_labels(labels)
+      ids=find_ids(labels)
+      return ids.map{|id| @values_by_id[id]}
+    end
+  end
+
+  # Summarizes all elements matching labels
+  # a little faster than using MultiMatrix#inject(labels) {|a,b| a+b} because of two factors:
+  # - if every dimension is given, sum return only one element without looping through the data structure
+  # - sum is cached so if sum is called twice with the same selector hash, the result is given back instantly
+  # @param labels finder hash
+  # @param default default value of sum
+  def sum(labels = {}, default = 0)
+    if check_labels(labels)
+      if labels.keys.length == @dim and labels.values.find_all {|val| val.class.to_s == 'Array'}.empty?
+        return get_value(labels)
+      end
+      if @sumcache.key?(labels)
+        return @sumcache[labels]
+      end
+      ret = self.inject(labels, default) {|a,b| a+b}
+      @sumcache[labels] = ret
+      ret
+    end
+  end
+
+  # Retrieves a value
+  # If every dimension is given, retrieve just a value at the specified position,
+  # if not, retrieves an MultiMatrix of the matching elements, leaving the fixed dimensions behind
+  # @param labels finder hash
+  # @return value/MultiMatrix
+  def retrieve(labels = {})
+    if check_labels(labels)
+      if labels.keys.length < @dim or labels.values.find_all {|val| val.class == Array}.length > 0
+        tmp = MultiMatrix.new(*(@labels - labels.keys.find_all {|val| labels[val].class != Array}))
+        ids = find_ids(labels)
+        ids.each do |id|
+          hash = @labels_by_id[id]
+          labels.keys.find_all {|val| labels[val].class != Array}.each do |key|
+            hash.delete(key)
+          end
+          tmp[hash] = @values_by_id[id]
+        end
+        return tmp
+      elsif labels.keys.length == @dim
+        return get_value(labels)
+      end
+    end
+  end
+
+  # return the possible values of a dimension
+  # where values match the labels given in [rest]
+  # @param needle a key of the labels hash
+  # @param rest a selector hash
+  def values_for_label(needle, rest = {})
+    raise MultiMatrixException, 'labels don\'t match: '+rest.keys.join(",") unless check_labels(rest)
+    raise MultiMatrixException, 'label does not exist' unless check_labels({needle => nil})
+    ids = find_ids(rest)
+    ids.map{|id| @labels_by_id[id][needle]}
+  end
+
+  alias_method :[], :retrieve
+  alias_method :[]=, :insert
+
+  # Test the equality of two NMatrices
+
+  # NMatrices are equal if they have the same labels,
+  # label values, and  all their respective values are equal
+  # @param other [MultiMatrix]
+  def ==(other)
+    [[self, other],[other,self]].each do |x|
+      x.first.keys do |k|
+        if !x.last.key?(k)
+          return false
+        end
+        if x.last[k] != x.first[k]
+          return false
+        end
+      end
+    end
+    return true
+  end
+
+  # @return labels in MultiMatrix
+  def keys
+    @values.keys
+  end
+
+  # @return  String representation of an MultiMatrix - shown as a Hash of label => value pairs
+  def to_s
+    hash = {}
+    @values.each_pair do |k,v|
+      hash[k] = @values_by_id[v]
+    end
+    hash.to_s
+  end
+
+  private
+
+  def check_labels(to_check)
+    raise MultiMatrixException, 'labels not a hash' if to_check.class != Hash
+    raise MultiMatrixException, 'labels hash contains an unknown label' unless (to_check.keys-@labels).empty?
+    return true;
+  end
+
+  def get_value(labels)
+    @values_by_id[@values[labels]]
+  end
+
+  def save_value(labels, val, options = {})
+    if options.key?(:override)
+      @values_by_id[options[:override]] = val
+    else
+      id = generate_id
+      @values[labels] = id
+      @values_by_id[id] = val
+      @labels_by_id[id] = labels
+      labels.each_pair do |k, v|
+        @finderhash[k] ||= {}
+        @finderhash[k][v] ||= []
+        @finderhash[k][v].push(id)
+      end
+    end
+  end
+
+  def find_ids(labels)
+    ids = @values.values
+    labels.each_pair do |k,v|
+      if v.class == Array
+        ids &= v.map {|v| @finderhash[k][v]}.flatten.uniq
+      elsif @finderhash[k][v].nil?
+        return []
+      else
+        ids &= @finderhash[k][v]
+      end
+    end
+    return ids
+  end
+
+  def generate_id
+    @seq = @seq.succ
+    return @seq
+  end
+
+end

data/test/test_multimatrix.rb

@@ -0,0 +1,142 @@
+require 'test/unit'
+require 'multimatrix'
+
+class MultiMatrixTest < Test::Unit::TestCase
+  def test_new
+    assert_raise(MultiMatrixException, "no dimensions") do
+      MultiMatrix.new()
+    end
+    assert_nothing_raised do
+      MultiMatrix.new(:x, :y, :z)
+    end
+    assert_equal MultiMatrix.new(:x,:y,:z).class, MultiMatrix
+  end
+
+  def test_insert
+    x = MultiMatrix.new(:x, :y, :z)
+
+    assert_raise MultiMatrixException do
+      x[:x => 1 , :y => 1, :a => 1] = 1
+    end
+
+    assert_raise MultiMatrixException do
+      x[:x => 1, :y => 1] = 1
+    end
+
+    assert_raise ArgumentError do
+      x[] = 1
+    end
+
+    assert_nothing_raised do
+      x[:x => 1, :y => 1, :z => 1] = 1
+      x[:x => 1, :y => 1, :z => 2] = 1
+      x[:x => 1, :y => 1, :z => 3] = 1
+
+      x[:x => 1, :y => 1, :z => 1] = 1
+      x.insert({:x => 1, :y => 1, :z => 1}, 1) {|a,b| a+b}
+      x.insert({:x => 1, :y => 1, :z => 1}, 1) {|a,b| a-b}
+    end
+  end
+
+  def test_values
+    x = MultiMatrix.new(:i, :j, :x, :y, :z)
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 1] = 1
+
+    assert_equal x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 1], 1
+
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 1] = 1
+
+    assert_equal x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 1], 2
+
+    x.insert({:i => 1, :j => 1, :x => 1, :y => 1, :z => 1}, 1) {|a,b| a-b}
+
+    assert_equal x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 1], 1
+
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 2] = 1
+
+    assert_equal x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 1], 1
+  end
+
+  def test_equality
+    x = MultiMatrix.new(:i, :j, :x, :y, :z)
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 1] = 1
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 2] = 1
+
+    y = MultiMatrix.new(:i, :j, :x, :y, :z)
+    y[:i => 1, :j => 1, :x => 1, :y => 1, :z => 1] = 1
+    y[:i => 1, :j => 1, :x => 1, :y => 1, :z => 2] = 1
+
+    assert_equal x,y
+  end
+
+  def test_MultiMatrix_returns
+    x = MultiMatrix.new(:i, :j, :x, :y, :z)
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 1] = 1
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 2] = 1
+
+    y = MultiMatrix.new(:z)
+    y[:z => 1] = 1
+    y[:z => 2] = 1
+
+    assert_equal x[:i => 1, :j => 1, :x => 1, :y => 1], y
+    assert_equal x[:i => 1, :j => 1, :x => 1, :y => 1, :z => [1,2]], y
+  end
+
+  def test_sum
+    x = MultiMatrix.new(:i, :j, :x, :y, :z)
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 1] = 1
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 2] = 1
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 3] = 1
+
+    x[:i => 1, :j => 1, :x => 1, :y => 2, :z => 1] = 1
+    x[:i => 1, :j => 1, :x => 1, :y => 2, :z => 2] = 1
+    x[:i => 1, :j => 1, :x => 1, :y => 2, :z => 3] = 1
+
+    assert_equal x.sum({:y => 1}), 3
+    assert_equal x.sum({:z => 1}), 2
+    assert_equal x.sum({:z => 1, :y=> 1}), 1
+    assert_equal x.sum({:i => 1}), 6
+    assert_equal x.sum({:y => [1,2]}), 6
+    assert_equal x.sum({:y => [1,2], :z => [1,2]}), 4
+
+  end
+
+  def test_to_a
+    x = MultiMatrix.new(:i, :j, :x, :y, :z)
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 1] = 1
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 2] = 2
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 3] = 3
+
+    x[:i => 1, :j => 1, :x => 1, :y => 2, :z => 1] = 4
+    x[:i => 1, :j => 1, :x => 1, :y => 2, :z => 2] = 5
+    x[:i => 1, :j => 1, :x => 1, :y => 2, :z => 3] = 6
+
+    assert_equal x.to_a.sort, [1,2,3,4,5,6]
+    assert_equal x.to_a(:i => 1).sort, [1,2,3,4,5,6]
+    assert_equal x.to_a(:z => 2).sort, [2,5]
+    assert_equal x.to_a(:y => 1).sort, [1,2,3]
+    assert_equal x.to_a(:y => 1, :z => 1), [1]
+  end
+
+  def test_values_for_label
+    x = MultiMatrix.new(:i, :j, :x, :y, :z)
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 1] = 4
+    x[:i => 1, :j => 1, :x => 1, :y => 1, :z => 2] = 5
+    x[:i => 1, :j => 1, :x => 1, :y => 2, :z => 3] = 6
+
+    assert_equal x.values_for_label(:i), [1,1,1]
+    assert_equal x.values_for_label(:z).sort, [1,2,3]
+    assert_equal x.values_for_label(:y).sort, [1,1,2]
+    assert_equal x.values_for_label(:y, :z => 3).sort, [2]
+  end
+
+  def test_nonexistent_values
+    x = MultiMatrix.new(:x, :y)
+    x[:x => 2, :y => 2] = 1
+
+    assert_nil x[:x => 1, :y => 1]
+    y = MultiMatrix.new(:y)
+    assert_equal x[:x => 1],y
+  end
+
+end

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification
+name: multimatrix
+version: !ruby/object:Gem::Version
+  version: '0.2'
+platform: ruby
+authors:
+- Gergely Dömsödi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-15 00:00:00.000000000 Z
+dependencies: []
+description: An n-dim matrix featuring labels
+email: doome@uhusystems.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/multimatrix.rb
+- test/test_multimatrix.rb
+homepage: http://rubygems.org/gems/multimatrix
+licenses:
+- WTFPL
+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.1.11
+signing_key: 
+specification_version: 4
+summary: n-dim Matrix!
+test_files: []
+has_rdoc: