namo 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35ca3cdc2c06b2da96ad636fa5ac1a593204a335ea93ff3994fc8bf187629aa5
-  data.tar.gz: 29639054075323f96fd0b6fe76bd733265ea155949965ec552c13ea30995efb8
+  metadata.gz: ae1731b55ec8d0de8dedfb35fc643f6fb6a68e72bb3464c4139242c1bc6bb91e
+  data.tar.gz: 161a1842a4daf8a4365a8420600f2824f5f15fd2ea3951e18d00d811eec22010
 SHA512:
-  metadata.gz: 8e0be2ae49cd9cc493e580174b3edf8ac874592b45bd3de08ab1b5db3e7a83daa6d6f9c8efb97089b1653d61a92248a0ec7de60c7ab26beef98c0e9b3fab7a0f
-  data.tar.gz: 49a00bf247a8e286ee45e8619253d36ae8f77d2def369d377d5c46fa8c9ebad734513333d23472d9b8c074800f49a42292458505ad34281466079a73096e33aa
+  metadata.gz: 4a563c97ca83b91e578375af09e533f633d2ed2d6bca1152297d3bf4b24dc60c5f25a5679e0e87023e3031f5019b3c32e825f35f23b75b0259cee6fb765a02b5
+  data.tar.gz: 140f9b808a8f406ca1ca16611ab776544c332830353f1d9dba58d4cf3578ff746d2ff7788671fd9eda0c082d6cc3f1457f29ee38473d88ec2c1f0aa457a0dace

data/CHANGELOG

@@ -1,6 +1,41 @@
 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.
 

data/README.md

@@ -1040,9 +1040,34 @@ gt.values(:weight)                         # => [200, 80, 150, 60, ...]   (line
 
 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.19.0'
+  VERSION = '0.20.0'
 end

data/test/namo_test.rb

@@ -2573,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.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - thoran