object_table 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 14a01cfa80b77105e5a243dbaacc894fec8fa9ad
-  data.tar.gz: 6bf1d3259550812b745eee202f0937bf7c278732
+  metadata.gz: 4b1327f62f465f8305a265b6a7f865c5ca43a66b
+  data.tar.gz: 8dc9d380fecb0ac14556f3cbe38acae87ec943b3
 SHA512:
-  metadata.gz: 1106df0b67029df89d4e8f52e171946f38f4a19c6c16fc0c316823731c8d073fa565b35ce141c2dc399c8d2f2d9002ab11e25178b38cb686db656fc5e4e5fb09
-  data.tar.gz: 8a6423b764125e33c092c7d80dbc5fab723995f82873528f8d72e441d54bbe2340b2f9a2022e521fe2d762db0dcbe0fbe90cdfce78643e3479932bb46ad242fe
+  metadata.gz: 666c0551cef6acff77df23fee41986c49b05e2959bb770d0c1ed06cee357774c9e57a31f359eb50603be8d9f87e03b216eec4272a1cb6e2b8ab420a934513c40
+  data.tar.gz: 18841d8933d04755b955fd6882fb7d8480d199d442306c0a02d44b041984f7f131f0f81d7bd4e5c4da277b4fca91847bae7d35e2a8fc63771119f8a14989e222

data/README.md

@@ -57,7 +57,18 @@ Otherwise the scalars are extended to match the length of the vector columns
 - `#stack(table1, table2, ...)` appends then supplied tables
 - `#apply(&block)` evaluates `block` in the context of the table
 - `#where(&block)` filters the table
-- `#group(&block)` splits the table into groups
+- `#group_by(&block)` splits the table into groups
+
+For any methods taking a block, when passing a block which takes an argument, the block will be called with the table as the argument, otherwise (block with no arguments), the block is `#instance_eval`ed in the context of the block.
+
+```ruby
+>>> data = ObjectTable.new
+# block with argument, binding is preserved
+>>> data.apply{|tbl| self.class }
+Object
+>>> data.apply{ self.class }
+ObjectTable
+```
 
 ### Getting columns
 
@@ -79,7 +90,7 @@ You can get a column by using `#[]` or using the column name as a method.
 
 ### Setting columns
 
-You can set/add columns by using `#[]=`.
+You can set/add columns by using `#[]=`. This works for both vectors and scalars. Scalars are given a default type of object.
 
 ```ruby
 >>> data = ObjectTable.new(a: [1, 2, 3], b: 100, c: ['a', 'b', 'c'])
@@ -121,6 +132,37 @@ IndexError: dst.shape[0]=3 != src.shape[0]=4
 IndexError: dst.shape[0]=3 != src.shape[0]=4
 ```
 
+#### `#set_column(name, value, typecode='object', shape...)`
+
+`#[]=` really just calls `#set_column`, but you can have more control over the columns by calling `#set_column` yourself and adding additional arguments. Additional arguments control the shape and type of the column. They are the same as for `NArray.new`
+
+```ruby
+>>> data = ObjectTable.new(col0: [0]*3)
+>>> data[:col1] = [1, 2, 3]
+>>> data.col1
+ => ObjectTable::Column.int(3): 
+[ 1, 2, 3 ] 
+
+# this time, let's make it a float instead
+>>> data.set_column(:col2, [1, 2, 3], 'float')
+>>> data.col2
+ => ObjectTable::Column.float(3): 
+[ 1.0, 2.0, 3.0 ] 
+
+>>> data[:col3] = 4
+>>> data.col3
+ => ObjectTable::Column.object(3): 
+[ 4, 4, 4 ] 
+
+# this time, let's make it multi dimensional
+>>> data.set_column(:col4, 4, 'int', 5)
+>>> data.col4
+ => ObjectTable::Column.int(5,3): 
+[ [ 4, 4, 4, 4, 4 ], 
+  [ 4, 4, 4, 4, 4 ], 
+  [ 4, 4, 4, 4, 4 ] ] 
+```
+
 ### Operating on columns
 
 All standard NArray operations apply (addition, subtraction etc.)
@@ -136,7 +178,6 @@ Missing methods are vectorised over the column
 ### `#apply`
 
 This is just a convenience method.
-It basically `#instance_eval`s the block passed to it.
 
 ```ruby
 >>> data = ObjectTable.new(a: [1, 2, 3], b: [4, 5, 6])
@@ -154,20 +195,47 @@ It basically `#instance_eval`s the block passed to it.
   0:   1  4   4
   1:   2  5  10
   2:   3  6  18
-       a  b   c 
+       a  b   c
+
+# if you don't want it to steal the binding (self), make the block take an argument
+>>> data.apply{|tbl| tbl.a + tbl.c }
+ => ObjectTable::Column.int(3): 
+[ 5, 12, 21 ] 
+```
+
+If you return a grid (e.g. through the `@R` shortcut) it will be coerced to a table.
+
+```ruby
+>>> data = ObjectTable.new(a: [1, 2, 3], b: [4, 5, 6])
+# let's make a new table but with a=a*3
+>>> data.apply{ @R[a: a*3, b: b] }
+ => ObjectTable(3, 2)
+       a  b
+  0:   3  4
+  1:   6  5
+  2:   9  6
+       a  b 
+
+# or if you called apply expecting an argument
+>>> data.apply{|tbl| tbl.R[a: tbl.a*3, b: tbl.b] }
+ => ObjectTable(3, 2)
+       a  b
+  0:   3  4
+  1:   6  5
+  2:   9  6
+       a  b 
 ```
 
 ## Filtering
 
 Use the `#where` method and pass a filtering block.
-The block is evaluated in the context of the table (like for `#apply`).
-This creates a `TempView` which syncs with the parent table.
+This creates a `View`, which syncs with the parent table.
 This means any changes made to the parent also affect the view.
 
 ```ruby
 >>> data = ObjectTable.new(a: 0...5, b: 5...10)
 >>> a_lt_3 = data.where{ a < 3 }
- => ObjectTable::TempView(3, 2)
+ => ObjectTable::View(3, 2)
        a  b
   0:   0  5
   1:   1  6
@@ -178,7 +246,7 @@ This means any changes made to the parent also affect the view.
 >>> data[:b] = data.b.reverse
 # and the view gets updated too
 >>> a_lt_3
- => ObjectTable::TempView(3, 2)
+ => ObjectTable::View(3, 2)
        a  b
   0:   0  9
   1:   1  8
@@ -187,7 +255,7 @@ This means any changes made to the parent also affect the view.
 
 # you can also chain #where calls
 >>> data.where{ a < 3 }.where{ b > 7 }
- => ObjectTable::TempView(3, 2)
+ => ObjectTable::View(3, 2)
        a  b
   0:   0  9
   1:   1  8
@@ -196,8 +264,7 @@ This means any changes made to the parent also affect the view.
 >>> data.where{ a < 3 && b > 7 }
 ```
 
-Changes are propagated to the parent.
-This means any changes made to the view also affect the parent.
+Any changes made to the view also affect the parent.
 
 ```ruby
 >>> data.where{ a < 3 }[:b] = 100
@@ -243,66 +310,131 @@ Added columns have a default value of `nil` outside the view.
        a  b    c 
 ```
 
-### Other notes
+### `#apply`
+
+Using `#apply` creates a `StaticView`. Any modifications made to the parent will not refresh the static view. Changes to the static view still affect the parent however.
+
+```ruby
+>>> data = ObjectTable.new(a: 0...5, b: 5...10)
+
+>>> a_lt_3 = data.where{ a < 3 }
+ => ObjectTable::View(3, 2)
+       a  b
+  0:   0  5
+  1:   1  6
+  2:   2  7
+       a  b 
+>>> a_lt_3[:a] = 5
+# our view will refresh, so we can't see the changes!
+>>> a_lt_3
+ => ObjectTable::View(0, 2)
+    a  b
+    a  b 
 
-You can also use `#apply` on a view (as for a table).
+# use apply instead
+>>> data = ObjectTable.new(a: 0...5, b: 5...10)
+>>> data.where{a < 3}.apply{ self[:a] = 5; p self; nil }
+ObjectTable::StaticView(3, 2)
+       a  b
+  0:   5  5
+  1:   5  6
+  2:   5  7
+       a  b
+ => nil 
+```
+
+You should never try to use a static view outside of its `#apply` block.
+
+
+### Other notes
 
 If you want to filter a table and keep that data (i.e. without it syncing with the parent, propagating changes etc.) just `#clone` it.
 
+
 ## Grouping (and aggregating)
 
-Use the `#group` method and pass a block that returns grouping keys.
+Use the `#group_by` method and pass column names or a block that returns grouping keys.
 Then call `#each` to iterate through the groups or `#apply` to aggregate the results.
-The blocks are evaluated in the context of the table (in the case of `#apply`, the context of the group).
 
-The argument to `#group` should be a hash mapping key name => key. See the below example.
+The argument to `#group_by` should be a hash mapping key name => key. See the below example.
 
 ```ruby
->>> data = ObjectTable.new(name: ['John', 'Tom', 'Jim', 'Tim', 'Jack'], value: 1..5)
+>>> data = ObjectTable.new(name: ['John', 'Tom', 'John', 'Tom', 'Jim'], value: 1..5)
+ => ObjectTable(5, 2)
          name  value
   0:   "John"      1
   1:    "Tom"      2
-  2:    "Jim"      3
-  3:    "Tim"      4
-  4:   "Jack"      5
-         name  value 
-
-# group by the first letter of the name and print out each group
->>> data.group{ {initial: name.map{|n| n[0]}} }.each{ p self; puts }
-ObjectTable::View(3, 2)
-         name  value
-  0:   "John"      1
-  1:    "Jim"      3
-  2:   "John"      5
+  2:   "John"      3
+  3:    "Tom"      4
+  4:    "Jim"      5
          name  value
 
-ObjectTable::View(2, 2)
-        name  value
-  0:   "Tom"      2
-  1:   "Tim"      4
-        name  value
-
-# calculate the average 'value' for each group and get the result in a table
->>> data.group{ {initial: name.map{|n| n[0]}} }.apply{ value.mean }
- => ObjectTable(2, 2)
-       initial  v_0                                        
-  0:       "J"  3.0                                        
-  1:       "T"  3.0                                        
-       initial  v_0
+# group by the name and get the no. of rows in each group
+>>> num_rows = []
+>>> data.group_by(:name).each{ num_rows.push(nrows) }
+>>> num_rows
+ => [2, 2, 1]
+ 
+# or group with a block
+>>> num_rows = []
+# let's group by initial letter of the name
+>>> data.group_by{ {initial: name.map{|n| n[0]}} }.each{ num_rows.push(nrows) }
+>>> num_rows
+ => [3, 2]
+```
+
+The group keys are accessible through the `@K` shortcut
+
+```ruby
+>>> data = ObjectTable.new(name: ['John', 'Tom', 'John', 'Tom', 'Jim'], value: 1..5)
+>>> data.group_by(:name).each{ p @K }
+{:name=>"John"}
+{:name=>"Tom"}
+{:name=>"Jim"}
+
+# or if you are using a block with args
+>>> data.group_by(:name).each{|grp| p grp.K }
+{:name=>"John"}
+{:name=>"Tom"}
+{:name=>"Jim"}
 ```
 
+
 ### Aggregation
 
+Call `#apply` and the results are stored into a table.
+
+```ruby
+>>> data = ObjectTable.new(name: ['John', 'Tom', 'John', 'Tom', 'Jim'], value: 1..5)
+>>> data.group_by(:name).apply{ value.mean }
+ => ObjectTable(3, 2)
+         name  v_0
+  0:   "John"  2.0
+  1:    "Tom"  3.0
+  2:    "Jim"  5.0
+         name  v_0 
+```
+
 Normally you can only have one aggregated column with a default name of v_0.
 You can have more columns and set column names by making a `ObjectTable` or using the @R shortcut.
 
 ```ruby
->>> data.group{ {initial: name.map{|n| n[0]}} }.apply{ @R[ mean: value.mean, sum: value.sum ] }
- => ObjectTable(2, 4)
-       initial  mean  sum                 std
-  0:       "J"   3.0    9                 2.0
-  1:       "T"   3.0    6  1.4142135623730951
-       initial  mean  sum                 std 
+>>> data.group_by(:name).apply{ @R[ mean: value.mean, sum: value.sum] }
+ => ObjectTable(3, 3)
+         name  mean  sum
+  0:   "John"   2.0    4
+  1:    "Tom"   3.0    6
+  2:    "Jim"   5.0    5
+         name  mean  sum 
+
+# or if you are using a block with args
+>>> data.group_by(:name).apply{|grp| grp.R[ mean: grp.value.mean, sum: grp.value.sum] }
+ => ObjectTable(3, 3)
+         name  mean  sum
+  0:   "John"   2.0    4
+  1:    "Tom"   3.0    6
+  2:    "Jim"   5.0    5
+         name  mean  sum 
 ```
 
 ### Assigning to columns
@@ -310,13 +442,74 @@ You can have more columns and set column names by making a `ObjectTable` or usin
 Assigning to columns will assign by group.
 
 ```ruby
->>> data.group{ {initial: name.map{|n| n[0]}} }.each{ self[:num_same_initial] = nrows }
+# every row with the same name will get the same group_values
+>>> data.group_by(:name).each{|grp| grp[:group_values] = grp.value.to_a.join(',') }
  => ObjectTable(5, 3)
-         name  value  num_same_initial
-  0:   "John"      1                 3
-  1:    "Tom"      2                 2
-  2:    "Jim"      3                 3
-  3:    "Tim"      4                 2
-  4:   "John"      5                 3
-         name  value  num_same_initial 
+         name  value  group_values
+  0:   "John"      1         "1,3"
+  1:    "Tom"      2         "2,4"
+  2:   "John"      3         "1,3"
+  3:    "Tom"      4         "2,4"
+  4:    "Jim"      5           "5"
+         name  value  group_values 
+```
+
+## Subclassing ObjectTable
+
+The act of subclassing itself is easy, but any methods you add won't be available to child views and groups.
+
+```ruby
+>>> class BrokenTable < ObjectTable
+      def a_plus_b
+        a + b
+      end
+    end
+
+>>> data = BrokenTable.new(a: 1..3, b: 4..6)
+>>> data.a_plus_b
+ => ObjectTable::Column.int(3): 
+[ 5, 7, 9 ] 
+
+# this won't work!
+>>> data.where{ a > 1 }.a_plus_b
+NoMethodError: undefined method `a_plus_b' for #<ObjectTable::View:0x000000011d4dd0>
+```
+
+To make it work, you'll need to subclass `View`, `StaticView` and `Group` too. Then set the `Table` constant on each. The easiest way is just to include a module.
+
+```ruby
+>>> class WorkingTable < ObjectTable
+      module Mixin
+        # this mixin will set the Table constant on each of the subclasses
+        Table = WorkingTable
+
+        def a_plus_b
+          a + b
+        end
+      end
+
+      include Mixin
+
+      # subclass each of these and include the Mixin too
+      class StaticView < StaticView; include Mixin; end
+      class View < View; include Mixin; end
+      class Group < Group; include Mixin; end
+    end
+
+>>> data = WorkingTable.new(a: 1..3, b: 4..6)
+>>> data.a_plus_b
+ => ObjectTable::Column.int(3): 
+[ 5, 7, 9 ] 
+
+# hurrah!
+>>> data.where{ a > 1 }.a_plus_b
+ => ObjectTable::Column.int(2): 
+[ 7, 9 ] 
+
+# also works in groups!
+>>> data.group_by{{odd: a % 2}}.each do
+      p "when a % 2 == #{@K[:odd]}, a + b == #{a_plus_b.to_a}"
+    end
+"when a % 2 == 1, a + b == [5, 9]"
+"when a % 2 == 0, a + b == [7]"
 ```

data/lib/object_table/basic_grid.rb

@@ -13,7 +13,7 @@ class ObjectTable::BasicGrid < Hash
     narrays, scalars = scalars.partition{|k, v| v.is_a?(NArray) }
 
     unique_rows = arrays.map{|k, v| v.count}
-    unique_rows += narrays.map{|k, v| v.shape.last}
+    unique_rows += narrays.map{|k, v| v.shape.last or 0}
     unique_rows = unique_rows.uniq
 
     if rows

data/lib/object_table/group.rb

@@ -0,0 +1,10 @@
+require_relative 'static_view'
+
+class ObjectTable::Group < ObjectTable::StaticView
+  attr_reader :K
+
+  def initialize(parent, keys, value)
+    super(parent, value)
+    @K = keys
+  end
+end

data/lib/object_table/grouped.rb

@@ -1,17 +1,8 @@
-require_relative 'view'
+require_relative 'group'
 
 class ObjectTable::Grouped
   DEFAULT_VALUE_PREFIX = 'v_'
 
-  class Group < ObjectTable::View
-    attr_reader :K
-
-    def initialize(parent, keys, value)
-      super(parent, value)
-      @K = keys
-    end
-  end
-
   def initialize(parent, names, groups)
     @parent = parent
     @names = names
@@ -19,19 +10,23 @@ class ObjectTable::Grouped
   end
 
   def each(&block)
+    group_cls = @parent.class::Table::Group
+
     @groups.each do |k, v|
       names = @names.zip(k)
-      Group.new(@parent, Hash[names], v).apply &block
+      group_cls.new(@parent, Hash[names], v).apply &block
     end
     @parent
   end
 
   def apply(&block)
+    table_cls = @parent.class::Table
+    group_cls = table_cls::Group
     value_key = self.class._generate_name(DEFAULT_VALUE_PREFIX, @names).to_sym
 
     data = @groups.map do |k, v|
       names = @names.zip(k)
-      value = Group.new(@parent, Hash[names], v).apply &block
+      value = group_cls.new(@parent, Hash[names], v).apply &block
 
       if value.is_a?(ObjectTable::TableMethods)
         value = value.columns
@@ -46,7 +41,7 @@ class ObjectTable::Grouped
       grid._ensure_uniform_columns!
     end
 
-    ObjectTable.stack(*data)
+    table_cls.stack(*data)
   end
 
   def self._generate_name(prefix, existing_names)

data/lib/object_table/masked_column.rb

@@ -28,8 +28,10 @@ class ObjectTable::MaskedColumn < ObjectTable::Column
   alias_method :super_slice_assign, :[]=
 
   def []=(*keys, value)
-    parent[*padded_dims, indices[*keys]] = value
-    super
+    unless (value.is_a?(Array) or value.is_a?(NArray)) and value.empty?
+      parent[*padded_dims, indices[*keys]] = value
+      super
+    end
   end
 
 #   make destructive methods affect parent

data/lib/object_table/static_view.rb

@@ -0,0 +1,24 @@
+require_relative 'view_methods'
+require_relative 'basic_grid'
+require_relative 'masked_column'
+
+class ObjectTable::StaticView
+  include ObjectTable::ViewMethods
+  attr_reader :indices
+
+  def initialize(parent, indices)
+    super()
+    @parent = parent
+    @indices = indices
+    columns
+  end
+
+  def columns
+    @columns ||= super
+  end
+
+  def add_column(name, *args)
+    @columns[name] = super
+  end
+
+end

data/lib/object_table/table_methods.rb

@@ -1,6 +1,11 @@
 require 'forwardable'
 
 module ObjectTable::TableMethods
+  # this line is important!! which classes to use to make Views/StaticViews/Groups
+  # are taken from this constant, e.g. Table::View
+  Table = ObjectTable
+
+
   extend Forwardable
 
   attr_reader :R
@@ -19,7 +24,7 @@ module ObjectTable::TableMethods
   end
 
   def nrows
-    columns.empty? ? 0 : columns.values.first.shape[-1]
+    columns.empty? ? 0 : (columns.values.first.shape[-1] or 0)
   end
 
   def ncols
@@ -41,14 +46,16 @@ module ObjectTable::TableMethods
 
     if (value.is_a?(Array) or value.is_a?(NArray)) and args.empty?
       value =  NArray.to_na(value)
-      unless value.shape[-1] == nrows
-        raise ArgumentError.new("Expected size of last dimension to be #{nrows}, was #{value.shape[-1]}")
+      unless (value.shape[-1] or 0) == nrows
+        raise ArgumentError.new("Expected size of last dimension to be #{nrows}, was #{value.shape[-1].inspect}")
       end
 
       args = [value.typecode] + value.shape[0...-1]
     end
 
     column = add_column(name, *args)
+    return column if value.is_a?(NArray) and value.empty?
+
     begin
       column[] = value
     rescue Exception => e
@@ -63,25 +70,30 @@ module ObjectTable::TableMethods
   end
 
   def apply(&block)
-    result = instance_eval &block
+    if block.arity == 0
+      result = instance_eval &block
+    else
+      result = block.call(self)
+    end
+
     if result.is_a? ObjectTable::BasicGrid
-      result = ObjectTable.new(result)
+      result = self.class::Table.new(result)
     end
     result
   end
 
   def where(&block)
-    ObjectTable::TempView.new(self, &block)
+    self.class::Table::View.new(self, &block)
   end
 
-  def group(*args, &block)
+  def group_by(*args, &block)
     ObjectTable::TempGrouped.new(self, *args, &block)
   end
 
   def sort_by(*keys)
     sort_index = _get_sort_index(keys)
     cols = ObjectTable::BasicGrid[columns.map{|k, v| [k, v[sort_index]]}]
-    ObjectTable.new(cols)
+    self.class::Table.new(cols)
   end
 
   def method_missing(meth, *args, &block)
@@ -136,7 +148,7 @@ module ObjectTable::TableMethods
 
   def clone
     cols = ObjectTable::BasicGrid[columns.map{|k, v| [k, v.clone]}]
-    ObjectTable.new(cols)
+    self.class::Table.new(cols)
   end
 
   def _get_sort_index(columns)

data/lib/object_table/temp_grouped.rb

@@ -22,7 +22,7 @@ class ObjectTable::TempGrouped
 
   def _keys
     if @names.empty?
-      keys = @parent.instance_eval(&@grouper)
+      keys = @parent.apply(&@grouper)
       raise 'Group keys must be hashes' unless keys.is_a?(Hash)
       keys = ObjectTable::BasicGrid.new.replace keys
     else

data/lib/object_table/version.rb

@@ -1,3 +1,3 @@
 class ObjectTable
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end