namo 0.19.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35ca3cdc2c06b2da96ad636fa5ac1a593204a335ea93ff3994fc8bf187629aa5
-  data.tar.gz: 29639054075323f96fd0b6fe76bd733265ea155949965ec552c13ea30995efb8
+  metadata.gz: 07d3c62244d72800b8f533d4618c8f51b4161338c37dc439ad26f67557a7315f
+  data.tar.gz: 7b8c6c808068b97555bb8f98a1d1ecb55a399e16fc51e475b61f13cbad4f0cef
 SHA512:
-  metadata.gz: 8e0be2ae49cd9cc493e580174b3edf8ac874592b45bd3de08ab1b5db3e7a83daa6d6f9c8efb97089b1653d61a92248a0ec7de60c7ab26beef98c0e9b3fab7a0f
-  data.tar.gz: 49a00bf247a8e286ee45e8619253d36ae8f77d2def369d377d5c46fa8c9ebad734513333d23472d9b8c074800f49a42292458505ad34281466079a73096e33aa
+  metadata.gz: 58db7e089c9a6be6e9d050a549cf5df98983227d3a3d218d0d5f61ee2684009a1af5f4069cb16376fe8211425060fe2b1d609fb5b6770236726782fa57a35b20
+  data.tar.gz: a4327a3484ffc1b30755ed38f94c2e432f0d6e338f5348a75b854c1cdebcfedebab4a742441d5e542c832d4a0aa517dc67a51f8b926462f2c0ab4ecad4a990d8

data/CHANGELOG

@@ -1,6 +1,66 @@
 CHANGELOG
 _________
 
+20260625
+0.21.0: + Namo::Formulae; @formulae: /Hash/Namo::Formulae/. Behaviour-preserving: no new capability, just an object for the formula collection to accrete behaviour onto later, mirroring the 0.1.0 extraction of Row.
+
+1. + lib/Namo/Formulae.rb: + Namo::Formulae, a thin class wrapping a Hash @store.
+   Responds to exactly the subset of Hash that lib/namo.rb and Row send the formula
+   collection: [], []=, keys, key?, empty?, each, delete, merge, reject, dup; includes
+   Enumerable (each yields [name, callable] pairs, giving map/select/etc. for free).
+   Three deliberate choices: to_h returns a copy (@store.dup) so callers cannot mutate
+   internals; ==/eql?/hash are names-only (keys.sort), matching Namo's own formula
+   equality where two sets with the same names but different proc objects are equivalent;
+   merge/reject/dup return a Formulae, not a Hash.
+2. ~ lib/namo.rb: + the require; initialize now normalises the incoming formulae to a
+   Formulae (Formulae.new(formulae) unless already one). This is the single behavioural
+   seam — every existing internal construction passes a Hash and is wrapped, while
+   operator results that now pass a Formulae (merge/dup return Formulae) pass through.
+   No other call site changed: each sends a message Formulae answers.
+3. ~ test/namo_test.rb: the two assertions comparing the public #formulae accessor to a
+   literal {} now assert emptiness (must_be_empty). The accessor returns a Formulae, not a
+   Hash; the formula set being empty is the unchanged behaviour these tests pin. + two
+   construction tests pinning the normalisation seam: a Hash given by keyword is wrapped in
+   a Formulae, and a Formulae given by keyword passes through unchanged (same object).
+4. + test/Namo/Formulae_test.rb: + unit test pinning the three deliberate choices (to_h
+   copy, names-only ==/eql?/hash, the Hash-compatible surface plus Enumerable map/select).
+5. ~ Namo::VERSION: /0.20.0/0.21.0/
+
+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/Formulae.rb

@@ -0,0 +1,71 @@
+# Namo/Formulae.rb
+# Namo::Formulae
+
+class Namo
+  class Formulae
+    include Enumerable
+
+    def [](name)
+      @store[name]
+    end
+
+    def []=(name, callable)
+      @store[name] = callable
+    end
+
+    def keys
+      @store.keys
+    end
+
+    def key?(name)
+      @store.key?(name)
+    end
+
+    def empty?
+      @store.empty?
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+      @store.each(&block)
+    end
+
+    def delete(name)
+      @store.delete(name)
+    end
+
+    def merge(other)
+      self.class.new(@store.merge(other.to_h))
+    end
+
+    def reject(&block)
+      self.class.new(@store.reject(&block))
+    end
+
+    def dup
+      self.class.new(@store.dup)
+    end
+
+    def to_h
+      @store.dup
+    end
+
+    def ==(other)
+      other.is_a?(Formulae) && keys.sort == other.keys.sort
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def hash
+      keys.sort.hash
+    end
+
+    private
+
+    def initialize(store = {})
+      @store = store
+    end
+  end
+end

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.19.0'
+  VERSION = '0.21.0'
 end

data/lib/namo.rb

@@ -2,6 +2,7 @@
 # Namo
 
 require_relative './Namo/NegatedDimension'
+require_relative './Namo/Formulae'
 require_relative './Namo/Row'
 require_relative './Namo/Collection'
 require_relative './Namo/Enumerable'
@@ -235,7 +236,7 @@ class Namo
 
   def initialize(positional_data = nil, data: [], formulae: {}, name: nil)
     @data = positional_data || data
-    @formulae = formulae
+    @formulae = formulae.is_a?(Formulae) ? formulae : Formulae.new(formulae)
     @name = name
   end
 

data/test/Namo/Formulae_test.rb

@@ -0,0 +1,163 @@
+require 'minitest/autorun'
+require 'minitest-spec-context'
+
+require_relative '../../lib/namo'
+
+describe Namo::Formulae do
+  let(:revenue) do
+    proc{|r| r[:price] * r[:quantity]}
+  end
+
+  let(:cost) do
+    proc{|r| r[:quantity] * 4.0}
+  end
+
+  let(:formulae) do
+    Namo::Formulae.new({revenue: revenue})
+  end
+
+  describe "#[]" do
+    it "returns the callable stored under a name" do
+      _(formulae[:revenue]).must_be_same_as revenue
+    end
+
+    it "returns nil for an absent name" do
+      _(formulae[:missing]).must_be_nil
+    end
+  end
+
+  describe "#[]=" do
+    it "stores a callable under a name" do
+      formulae[:cost] = cost
+      _(formulae[:cost]).must_be_same_as cost
+    end
+  end
+
+  describe "#keys" do
+    it "returns the stored names" do
+      _(formulae.keys).must_equal [:revenue]
+    end
+  end
+
+  describe "#key?" do
+    it "is true for a stored name" do
+      _(formulae.key?(:revenue)).must_equal true
+    end
+
+    it "is false for an absent name" do
+      _(formulae.key?(:missing)).must_equal false
+    end
+  end
+
+  describe "#empty?" do
+    it "is true with no formulae" do
+      _(Namo::Formulae.new).must_be_empty
+    end
+
+    it "is false with formulae" do
+      _(formulae.empty?).must_equal false
+    end
+  end
+
+  describe "#each" do
+    it "yields name/callable pairs" do
+      yielded = {}
+      formulae.each{|name, callable| yielded[name] = callable}
+      _(yielded).must_equal({revenue: revenue})
+    end
+
+    it "returns an enumerator with no block" do
+      _(formulae.each).must_be_kind_of Enumerator
+    end
+  end
+
+  describe "#delete" do
+    it "removes a name" do
+      formulae.delete(:revenue)
+      _(formulae.key?(:revenue)).must_equal false
+    end
+  end
+
+  describe "#merge" do
+    it "returns a Formulae combining both sets" do
+      merged = formulae.merge(Namo::Formulae.new({cost: cost}))
+      _(merged).must_be_kind_of Namo::Formulae
+      _(merged.keys.sort).must_equal [:cost, :revenue]
+    end
+
+    it "lets the argument win on a name conflict" do
+      other = proc{|r| 0}
+      merged = formulae.merge(Namo::Formulae.new({revenue: other}))
+      _(merged[:revenue]).must_be_same_as other
+    end
+
+    it "does not mutate the receiver" do
+      formulae.merge(Namo::Formulae.new({cost: cost}))
+      _(formulae.keys).must_equal [:revenue]
+    end
+  end
+
+  describe "#reject" do
+    it "returns a Formulae without the rejected names" do
+      formulae[:cost] = cost
+      rejected = formulae.reject{|name, _| name == :cost}
+      _(rejected).must_be_kind_of Namo::Formulae
+      _(rejected.keys).must_equal [:revenue]
+    end
+  end
+
+  describe "#dup" do
+    it "returns an independent Formulae" do
+      copy = formulae.dup
+      copy[:cost] = cost
+      _(formulae.key?(:cost)).must_equal false
+    end
+  end
+
+  describe "#to_h" do
+    it "returns a copy, not the live store" do
+      hash = formulae.to_h
+      hash[:cost] = cost
+      _(formulae.key?(:cost)).must_equal false
+    end
+  end
+
+  describe "Enumerable" do
+    it "supports map over name/callable pairs" do
+      _(formulae.map{|name, _| name}).must_equal [:revenue]
+    end
+
+    it "supports select returning name/callable pairs" do
+      formulae[:cost] = cost
+      _(formulae.select{|name, _| name == :cost}).must_equal [[:cost, cost]]
+    end
+  end
+
+  describe "value semantics" do
+    it "is == when names match, regardless of proc objects" do
+      _(Namo::Formulae.new({revenue: revenue})).must_equal Namo::Formulae.new({revenue: proc{|r| 0}})
+    end
+
+    it "is not == when names differ" do
+      _(formulae).wont_equal Namo::Formulae.new({cost: cost})
+    end
+
+    it "is not == to a bare Hash" do
+      _(formulae).wont_equal({revenue: revenue})
+    end
+
+    it "is eql? on matching names with differing procs" do
+      _(Namo::Formulae.new({revenue: revenue}).eql?(Namo::Formulae.new({revenue: proc{|r| 0}}))).must_equal true
+    end
+
+    it "hashes equal on matching names with differing procs" do
+      _(Namo::Formulae.new({revenue: revenue}).hash).must_equal Namo::Formulae.new({revenue: proc{|r| 0}}).hash
+    end
+  end
+
+  describe "constructor" do
+    it "defaults to an empty store" do
+      _(Namo::Formulae.new.keys).must_equal []
+    end
+  end
+end

data/test/namo_test.rb

@@ -47,7 +47,7 @@ describe Namo do
     it "produces an empty Namo with no arguments" do
       namo = Namo.new
       _(namo.data).must_equal []
-      _(namo.formulae).must_equal({})
+      _(namo.formulae).must_be_empty
     end
 
     it "accepts keyword formulae with no data" do
@@ -56,6 +56,17 @@ describe Namo do
       _(namo.derived_dimensions).must_equal [:y]
     end
 
+    it "wraps keyword formulae given as a Hash in a Formulae" do
+      namo = Namo.new(formulae: {y: proc{|r| r[:x] * 2}})
+      _(namo.formulae).must_be_kind_of Namo::Formulae
+      _(namo.formulae.keys).must_equal [:y]
+    end
+
+    it "passes keyword formulae already given as a Formulae through unchanged" do
+      formulae = Namo::Formulae.new({y: proc{|r| r[:x] * 2}})
+      _(Namo.new(formulae: formulae).formulae).must_be_same_as formulae
+    end
+
     it "honours an explicit empty positional array over the nil sentinel" do
       _(Namo.new([]).data).must_equal []
     end
@@ -1010,7 +1021,7 @@ describe Namo do
         prices[:sma] = sma
         projected = prices[:sma]
         _(projected.to_a).must_equal [{sma: 10.0}, {sma: 15.0}, {sma: 20.0}]
-        _(projected.formulae).must_equal({})
+        _(projected.formulae).must_be_empty
       end
 
       it "returns an instance of self's class" do
@@ -2573,4 +2584,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.21.0
 platform: ruby
 authors:
 - thoran
@@ -66,6 +66,7 @@ files:
 - Rakefile
 - lib/Namo/Collection.rb
 - lib/Namo/Enumerable.rb
+- lib/Namo/Formulae.rb
 - lib/Namo/NegatedDimension.rb
 - lib/Namo/Row.rb
 - lib/Namo/VERSION.rb
@@ -73,6 +74,7 @@ files:
 - lib/namo.rb
 - namo.gemspec
 - test/Namo/Collection_test.rb
+- test/Namo/Formulae_test.rb
 - test/Namo/NegatedDimension_test.rb
 - test/Namo/Row_test.rb
 - test/Symbol_test.rb
@@ -95,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.14
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Named dimensional data for Ruby.
 test_files: []