namo 0.18.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ed38a77d14075cbe3c28ff53097d539c2fefe4a91ff515e165e02c280311fd3
-  data.tar.gz: ba009835a59174f2e60327f3583753d2e6c2b0e81b06f23de4a15dd792981526
+  metadata.gz: ae1731b55ec8d0de8dedfb35fc643f6fb6a68e72bb3464c4139242c1bc6bb91e
+  data.tar.gz: 161a1842a4daf8a4365a8420600f2824f5f15fd2ea3951e18d00d811eec22010
 SHA512:
-  metadata.gz: 7328696a6b4032561fa1b68c0eb4d3e7d3582ee4d5fc24926779112413867f1713100d9c21a3aa2f18c299e50802c866b5c95e874e569f4ef41f40e7b3924f58
-  data.tar.gz: 8028776be37f1f183ca2cefc3c9de7229d6918cf37d05b5f925675dd2ffd7d05603cc21ba53665f74094991b0c8d08f22479de2f50ee35e36ba772777bdbfb6e
+  metadata.gz: 4a563c97ca83b91e578375af09e533f633d2ed2d6bca1152297d3bf4b24dc60c5f25a5679e0e87023e3031f5019b3c32e825f35f23b75b0259cee6fb765a02b5
+  data.tar.gz: 140f9b808a8f406ca1ca16611ab776544c332830353f1d9dba58d4cf3578ff746d2ff7788671fd9eda0c082d6cc3f1457f29ee38473d88ec2c1f0aa457a0dace

data/CHANGELOG

@@ -1,6 +1,58 @@
 CHANGELOG
 _________
 
+20260615
+0.20.0: + group_by(dimension) — splits a Namo into a Namo::Collection, one member per distinct value, completing the Enumerable coherence pass begun at 0.11.0.
+
+1. ~ lib/Namo/Enumerable.rb: + Namo#group_by(dimension). Returns a Namo::Collection
+   whose members are the groups — one member per distinct value, each a Namo of the
+   matching rows, named by its group value, carrying the surviving formulae, preserving
+   subclass type via self.class.new. The grouping dimension is retained (the split is
+   along the axis, not consuming it), so namo.group_by(d).as_detail(d) inverts it. A
+   nil-valued group produces a nil-named member that holds its rows and round-trips, the
+   use-site naming decision (0.18.0) paying off. A ternary makes the materialise
+   decision: when dimension is derived, the group source is the projection
+   (self[*data_dimensions, dimension], 0.16.0) so the grouped-by formula becomes a stored
+   column and is dropped while every other formula carries through live; when data, the
+   source is self untouched. A parameterised formula raises the 0.17.0 ArgumentError at
+   the materialisation site, group_by needing no enforcement of its own.
+2. ~ test/namo_test.rb: + "#group_by" describe — return type, one-member-per-value,
+   row partitioning, grouping-dimension retention, find-by-name, formula carry-through,
+   subclass preservation, non-mutation, empty-Namo; the uniform inversion law
+   (data: exact; formula: against the materialised form); grouping by a formula
+   (partition by value, materialise-and-drop, only-grouped-formula-altered with a live
+   dependent, parameterised raise); the nil-valued grouping dimension (nil-named member,
+   no rows dropped, round-trip); and consistency with assembly (summary/detail on a
+   partitioned Collection).
+3. ~ README.md: + group_by subsection under Collections — the partition constructor as
+   the mirror of <<, the round-trip example, the materialise-on-formula behaviour, and
+   the cross-reference to the assembly side.
+4. ~ ROADMAP.md: Promote 0.20.0 to shipped; Current state -> 0.20.0; + the materialisation
+   rationale (unified-treatment requires it; materialise-and-drop is the only invertible
+   choice; the uniform inversion law); Summary folds in group_by; next phase -> 1.0.0.
+5. ~ COMPARISON.md: Aggregation entry — group_by repointed from planned (0.20.0) to
+   shipped, the partition constructor now realised; + the grouping-by-formula comparison
+   (computed-key grouping is parity, but only Namo partitions on a named, attached formula
+   through the data-dimension interface). Date bumped.
+6. ~ Namo::VERSION: /0.19.0/0.20.0/
+
+20260614
+0.19.0: ~ row-multiset equality — replace the sorted canonical form with a row multiset, so ==, eql?, hash, and the subset operators compare without sorting: nil/NaN-safe, row- and dimension-order blind, and consistently type-strict.
+
+1. ~ lib/namo.rb: replace canonical_data (which sorted @data by row.values_at(*data_dimensions.sort))
+   with row_multiset (@data.tally). ==, eql?, hash, and subset_of_rows? now compare row
+   multisets keyed by Hash#hash/#eql?. The sort was only ever a mechanism for reaching the
+   already-decided multiset semantics (0.6.0); a multiset reaches them directly and needs no
+   ordering, so the latent ArgumentError when a dimension mixed nil (or NaN) with present
+   values — neither has a <=> against the other — is gone. The relation is now uniformly
+   eql?-based, so == agrees with the subset operators, which already tallied: {a: 1} and
+   {a: 1.0} are consistently distinct (== previously called them equal via Hash#==, while <=
+   called them distinct).
+2. ~ test/namo_test.rb: + four "#==" cases — equality across row order and across dimension
+   (key) order when a dimension mixes nil and non-nil values; inequality when such rows
+   differ; and type-strictness on values, consistent with <=.
+3. ~ Namo::VERSION: /0.18.0/0.19.0/
+
 20260613
 0.18.0: + Namo::Collection — hierarchical aggregate of named Namos with summary/detail views.
 

data/README.md

@@ -1006,7 +1006,7 @@ gt.as_detail(:assembly)                    # gt's data becomes the detail; retur
 - If `by` is **already a dimension** in a member's rows, the row passes through untouched — the dimension is intrinsic.
 - If `by` is **not** present, `detail` injects it (`row.merge(by => member.name)`), promoting the member's name into a dimension.
 
-This single conditional is where assembly (`<<`, members named extrinsically) and partition (`group_by`, members named by an intrinsic value — 0.19.0) meet. For an assembled Collection, `as_detail(:assembly)` is the dimension-creating step: it promotes the member name into real data and **retains** it. From then on the structure is intrinsic and round-trips are exact; the promoted dimension is removed only by explicit contraction (`gt[-:assembly]`), never automatically.
+This single conditional is where assembly (`<<`, members named extrinsically) and partition (`group_by`, members named by an intrinsic value — 0.20.0) meet. For an assembled Collection, `as_detail(:assembly)` is the dimension-creating step: it promotes the member name into real data and **retains** it. From then on the structure is intrinsic and round-trips are exact; the promoted dimension is removed only by explicit contraction (`gt[-:assembly]`), never automatically.
 
 #### `<<` and unnamed members
 
@@ -1038,11 +1038,36 @@ gt << front_suspension                     # re-materialises detail
 gt.values(:weight)                         # => [200, 80, 150, 60, ...]   (line items again)
 ```
 
-Freeze-gated memoisation is a 2.x optimisation — opt-in via `freeze`, transparent, and never changing this observable behaviour. `group_by` (0.19.0) is the partition-side constructor for the same type: it splits a Namo into a `Collection`, the mirror of assembling one with `<<`.
+Freeze-gated memoisation is a 2.x optimisation — opt-in via `freeze`, transparent, and never changing this observable behaviour. `group_by` (0.20.0) is the partition-side constructor for the same type: it splits a Namo into a `Collection`, the mirror of assembling one with `<<`.
 
-## Why?
+#### Partitioning with `group_by`
 
-Every other multi-dimensional array library requires you to pre-shape your data before you can work with it. Namo takes it in the form it likely already comes in.
+`group_by(dimension)` is the partition-side constructor for a `Collection` — the mirror of assembling one with `<<`. It splits a Namo into one member per distinct value of the dimension, each a Namo holding that group's rows, named by its group value:
+
+```ruby
+prices.group_by(:symbol)
+# => #<Namo::Collection members: [:BHP, :RIO, :CBA]>
+
+prices.group_by(:symbol).summary(:close, reducer: :mean)
+# => Namo with {member:, close:} rows — mean close per symbol
+```
+
+The grouping dimension is retained in every member — the split runs *along* the axis, it doesn't consume it — so the partition inverts exactly through `as_detail` on the same dimension:
+
+```ruby
+prices.group_by(:symbol).as_detail(:symbol) == prices
+# => true
+```
+
+Because data and derived dimensions are treated alike, you can group by a formula as readily as by a stored column. Grouping by a derived dimension materialises it first — the grouped-by formula becomes a stored value in each member and is dropped, while every other formula carries through live:
+
+```ruby
+prices[:value_score] = proc{|r| r[:pe] < 10 ? 2 : r[:pe] < 15 ? 1 : 0}
+prices.group_by(:value_score)
+# => one member per score; :value_score is now a data column in each
+```
+
+This gives a single inversion law over the whole namespace — `namo.group_by(d).as_detail(d) == namo[*namo.data_dimensions, d]` for any `d`, with the exact-original round-trip being the data-dimension instance of it. A nil-valued group produces a nil-named member, holding its rows and round-tripping like any other.
 
 ## Name
 

data/lib/Namo/Enumerable.rb

@@ -68,5 +68,14 @@ class Namo
         self.class.new(non_matches, formulae: @formulae.dup),
       ]
     end
+
+    def group_by(dimension)
+      collection = Collection.new
+      source = derived_dimensions.include?(dimension) ? self[*data_dimensions, dimension] : self
+      source.data.group_by{|row_data| row_data[dimension]}.each do |value, rows|
+        collection << self.class.new(rows, formulae: source.formulae.dup, name: value)
+      end
+      collection
+    end
   end
 end

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.18.0'
+  VERSION = '0.20.0'
 end

data/lib/namo.rb

@@ -164,7 +164,7 @@ class Namo
 
   def ==(other)
     return false unless other.is_a?(Namo)
-    canonical_data == other.canonical_data
+    row_multiset == other.row_multiset
   end
 
   def ===(other)
@@ -175,12 +175,12 @@ class Namo
 
   def eql?(other)
     self.class == other.class &&
-      canonical_data == other.canonical_data &&
+      row_multiset == other.row_multiset &&
       @formulae.keys.sort == other.formulae.keys.sort
   end
 
   def hash
-    [self.class, canonical_data, @formulae.keys.sort].hash
+    [self.class, row_multiset, @formulae.keys.sort].hash
   end
 
   def <(other)
@@ -217,13 +217,13 @@ class Namo
 
   protected
 
-  def canonical_data
-    @data.sort_by{|row| row.values_at(*data_dimensions.sort)}
+  def row_multiset
+    @data.tally
   end
 
   def subset_of_rows?(other)
-    self_counts = canonical_data.tally
-    other_counts = other.canonical_data.tally
+    self_counts = row_multiset
+    other_counts = other.row_multiset
     self_counts.all?{|row, count| (other_counts[row] || 0) >= count}
   end
 

data/test/namo_test.rb

@@ -2312,6 +2312,31 @@ describe Namo do
       _(a == 'string').must_equal false
       _(a == nil).must_equal false
     end
+
+    it "compares rows whose dimension mixes nil and non-nil values" do
+      a = Namo.new([{symbol: 'BHP', sector: 'Mining'}, {symbol: 'CBA', sector: nil}])
+      b = Namo.new([{symbol: 'CBA', sector: nil}, {symbol: 'BHP', sector: 'Mining'}])
+      _(a == b).must_equal true
+    end
+
+    it "is false for differing rows when a dimension contains nil" do
+      a = Namo.new([{symbol: 'BHP', sector: 'Mining'}, {symbol: 'CBA', sector: nil}])
+      b = Namo.new([{symbol: 'BHP', sector: 'Mining'}, {symbol: 'CBA', sector: 'Banking'}])
+      _(a == b).must_equal false
+    end
+
+    it "ignores dimension (key) order within a row" do
+      a = Namo.new([{a: 1, b: 2, c: 3}])
+      b = Namo.new([{c: 3, b: 2, a: 1}])
+      _(a == b).must_equal true
+    end
+
+    it "is type-strict on values, consistent with the subset operators" do
+      a = Namo.new([{x: 1}])
+      b = Namo.new([{x: 1.0}])
+      _(a == b).must_equal false
+      _(a <= b).must_equal false
+    end
   end
 
   describe "#===" do
@@ -2548,4 +2573,135 @@ describe Namo do
       _(sales.to_a).must_equal sample_data
     end
   end
+
+  describe "#group_by" do
+    let(:price_data) do
+      [
+        {symbol: 'BHP', date: 1, close: 42.5, pe: 12.0},
+        {symbol: 'BHP', date: 2, close: 43.0, pe: 12.0},
+        {symbol: 'RIO', date: 1, close: 118.3, pe: 9.0},
+        {symbol: 'CBA', date: 1, close: 100.0, pe: 22.0}
+      ]
+    end
+    let(:prices) { Namo.new(price_data) }
+
+    it "returns a Namo::Collection" do
+      _(prices.group_by(:symbol)).must_be_kind_of Namo::Collection
+    end
+
+    it "has one member per distinct value of the dimension" do
+      collection = prices.group_by(:symbol)
+      _(collection.members.length).must_equal 3
+      _(collection.members.map(&:name)).must_equal ['BHP', 'RIO', 'CBA']
+    end
+
+    it "gives each member exactly the rows matching its group value" do
+      collection = prices.group_by(:symbol)
+      _(collection.find('BHP').values(:date)).must_equal [1, 2]
+      _(collection.find('RIO').values(:date)).must_equal [1]
+    end
+
+    it "retains the grouping dimension in each member (it is not consumed)" do
+      _(prices.group_by(:symbol).find('BHP').data_dimensions).must_include :symbol
+    end
+
+    it "names each member by its group value, found via find" do
+      _(prices.group_by(:symbol).find('CBA').values(:close)).must_equal [100.0]
+    end
+
+    it "carries the parent's formulae into each member" do
+      prices[:cheap] = proc{|r| r[:pe] < 15}
+      _(prices.group_by(:symbol).find('BHP').values(:cheap)).must_equal [true, true]
+    end
+
+    it "preserves the receiver's class in each member" do
+      subclass = Class.new(Namo)
+      collection = subclass.new(price_data).group_by(:symbol)
+      _(collection.members.first).must_be_instance_of subclass
+    end
+
+    it "does not mutate the receiver" do
+      prices.group_by(:symbol)
+      _(prices.data).must_equal price_data
+    end
+
+    it "returns an empty Collection for an empty Namo" do
+      collection = Namo.new.group_by(:symbol)
+      _(collection).must_be_kind_of Namo::Collection
+      _(collection.members).must_equal []
+    end
+
+    context "the uniform inversion law" do
+      it "round-trips exactly on a data dimension" do
+        _(prices.group_by(:symbol).as_detail(:symbol)).must_equal prices
+      end
+
+      it "round-trips against the materialised form on a formula dimension" do
+        prices[:value_score] = proc{|r| r[:pe] < 10 ? 2 : r[:pe] < 15 ? 1 : 0}
+        recovered = prices.group_by(:value_score).as_detail(:value_score)
+        _(recovered).must_equal prices[*prices.data_dimensions, :value_score]
+      end
+    end
+
+    context "grouping by a formula" do
+      before do
+        prices[:value_score] = proc{|r| r[:pe] < 10 ? 2 : r[:pe] < 15 ? 1 : 0}
+      end
+
+      it "partitions by the formula's value" do
+        collection = prices.group_by(:value_score)
+        _(collection.members.map(&:name).sort).must_equal [0, 1, 2]
+        _(collection.find(1).values(:symbol)).must_equal ['BHP', 'BHP']
+      end
+
+      it "materialises the grouped-by formula into a data column in each member" do
+        member = prices.group_by(:value_score).find(1)
+        _(member.data_dimensions).must_include :value_score
+        _(member.derived_dimensions).wont_include :value_score
+      end
+
+      it "alters only the grouped-by formula, carrying the rest through live" do
+        prices[:tier] = proc{|r| r[:value_score] >= 1 ? 'good' : 'poor'}
+        member = prices.group_by(:value_score).find(1)
+        _(member.derived_dimensions).must_include :tier
+        _(member.derived_dimensions).wont_include :value_score
+        _(member.values(:tier)).must_equal ['good', 'good']
+      end
+
+      it "raises for a parameterised formula it cannot materialise" do
+        prices[:sma] = proc{|row, namo, field, period| 0}
+        _(proc{prices.group_by(:sma)}).must_raise ArgumentError
+      end
+    end
+
+    context "a nil-valued grouping dimension" do
+      let(:sector_data) do
+        [
+          {symbol: 'BHP', sector: 'Mining'},
+          {symbol: 'RIO', sector: 'Mining'},
+          {symbol: 'XYZ', sector: nil}
+        ]
+      end
+      let(:stocks) { Namo.new(sector_data) }
+
+      it "produces a nil-named member holding the nil-valued rows" do
+        collection = stocks.group_by(:sector)
+        nil_member = collection.members.find{|m| m.name.nil?}
+        _(nil_member).wont_be_nil
+        _(nil_member.values(:symbol)).must_equal ['XYZ']
+      end
+
+      it "drops no rows and still round-trips" do
+        _(stocks.group_by(:sector).as_detail(:sector)).must_equal stocks
+      end
+    end
+
+    context "consistency with assembly" do
+      it "produces a Collection on which summary and detail behave as on an assembled one" do
+        collection = prices.group_by(:symbol)
+        _(collection.summary(:close, reducer: :sum).values(:member)).must_equal ['BHP', 'RIO', 'CBA']
+        _(collection.detail.values(:close)).must_equal [42.5, 43.0, 118.3, 100.0]
+      end
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.20.0
 platform: ruby
 authors:
 - thoran