namo 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86f572755292e2bac9808f09adb3169cec06066a5687ec2ea6bd9354f97d592a
-  data.tar.gz: edafcc183a1a9e5fb1212bb66a8b6906b94bf8e37a7375d3f9d304e5632ddba3
+  metadata.gz: 7adbe8192367d3c4207f7b27ff0b6a8a13f5243b42a4e4f18a6fbc35ef6439be
+  data.tar.gz: cda1e8b3d8fc042b4457efc0bc7846d5a416a5eda670d140824a4f8ad193a0f2
 SHA512:
-  metadata.gz: 2b2fad7c20e6cc9909b6d770a94627a071626de5cec9b402074ccda919295781dd18c38411604e5d0adf3d2f5e80833de830be37892a8e0a5cea5323bcef1a66
-  data.tar.gz: d0e9d4ae5bbe7a4dfc217614f0fb1442750313e9db734b622b831b15873e1ce6a3a5d2e91b01c450ab795476f00b94e29aae12be0dea4aad3d37e46369b5628e
+  metadata.gz: 60d639f243fc7bf306576b69ac646be388571b343330e5636f7c862519169cbaca3a36beb1cfccf16462b7e65b4735ca1b38e948db693c094c3636507531ebd4
+  data.tar.gz: 5898c9f8b7d9196481a964826cee97a8f1a962916f818604fa4ea647c1b59d5b05e17ea0ac5a578c6cd2a7d499100d95a10344029e7b6abd5bce70a41efc9b1f

data/CHANGELOG

@@ -1,6 +1,19 @@
 CHANGELOG
 _________
 
+20260521
+0.9.0: + composition operators: equi-join (*), Cartesian product (**), decomposition (/)
+
+1. + Namo#*: Equi-join on shared data dimensions. Inner-join semantics — unmatched rows from both sides are dropped. Raises ArgumentError ("no shared dimensions, need to have shared dimensions") when operands have no overlap. Preserves duplicates multiplicatively. Formulae merge with self winning on conflict.
+2. + Namo#**: Cartesian product of two Namos with disjoint data dimensions. Raises ArgumentError ("dimensions in common, need no common dimensions") when any dimension is shared. Output has left.length * right.length rows. Formulae merge with self winning on conflict.
+3. + Namo#/: Decomposition. Removes from self the dimensions that are also in other (the intersection), then dedupes the projected rows. No precondition — total on Namo × Namo. When self and other share no dimensions, the operator is a no-op. Formulae carry through from self. (a ** b) / b == a exactly; (a * b) / b loses dimensions shared between a and b.
+4. + Namo#raise_unless_shared_data_dimensions, Namo#raise_unless_disjoint_data_dimensions: Private precondition helpers for #* and #** respectively.
+5. ~ test/namo_test.rb: + #* tests (single/multi-dimension join, inner-join symmetry, multiplicative duplicates, formulae merging, error cases). + #** tests (Cartesian product, output sizing, dimension overlap error). + #/ tests (intersection removal, dedupe of collided rows, no-op on disjoint operands, idempotence). + Composition round-trip tests for the ** case (exact identity) and the * case (lossy on shared dimensions).
+6. ~ README.md: + Composition section (*), + Cartesian product section (**), + Decomposition section (/) including the combining-vs-projecting rationale for /'s no-precondition design. Placed after Symmetric Difference and before Equality.
+7. ~ ROADMAP.md: Promote 0.9.0 from upcoming to shipped under "Current state: 0.9.0"; revise Summary to include composition in the operator vocabulary and point "next phase" at 0.10.0+.
+8. ~ COMPARISON.md: /planned (0.9.0)/shipped (0.9.0)/ for Equi-join, Cartesian product, and Decomposition. + Paragraph in the Decomposition entry on the combining-vs-projecting distinction. Date bumped to 20260521.
+9. ~ Namo::VERSION: /0.8.0/0.9.0/
+
 20260521
 0.8.0: + proc and regex-based selection
 

data/README.md

@@ -319,6 +319,124 @@ set_a ^ set_b
 
 The dimensions must match; different dimensions raise an `ArgumentError`. Formulae merge from both sides; the left-hand side's formulae take precedence on conflict.
 
+### Composition
+
+`*` is the equi-join operator. It pairs rows from two Namos where coordinates match on every shared dimension, like an inner join on the shared dimension names:
+
+```ruby
+ohlcv = Namo.new([
+  {symbol: 'BHP', date: '2025-01-01', close: 42.5},
+  {symbol: 'RIO', date: '2025-01-01', close: 118.3}
+])
+
+fundamentals = Namo.new([
+  {symbol: 'BHP', pe: 14.5},
+  {symbol: 'RIO', pe: 9.2}
+])
+
+ohlcv * fundamentals
+# => #<Namo [
+#   {symbol: 'BHP', date: '2025-01-01', close: 42.5, pe: 14.5},
+#   {symbol: 'RIO', date: '2025-01-01', close: 118.3, pe: 9.2}
+# ]>
+```
+
+Inner-join semantics: unmatched rows from either side are dropped. Output dimensions are `self.data_dimensions` followed by `other.data_dimensions` exclusive to other. Duplicates on shared coordinates are preserved multiplicatively — output multiplicity is the product of input multiplicities on each matching key.
+
+The two Namos must have at least one shared data dimension. No overlap raises an `ArgumentError` — the asymmetry with `**` is deliberate, and falling through to a Cartesian product would silently turn a logic error into a large pile of nonsense rows. Formulae merge from both sides; the left-hand side wins on conflict.
+
+### Cartesian product
+
+`**` is the Cartesian product. Every row from the left paired with every row from the right:
+
+```ruby
+products = Namo.new([{product: 'Widget'}, {product: 'Gadget'}])
+quarters = Namo.new([{quarter: 'Q1'}, {quarter: 'Q2'}])
+
+products ** quarters
+# => #<Namo [
+#   {product: 'Widget', quarter: 'Q1'},
+#   {product: 'Widget', quarter: 'Q2'},
+#   {product: 'Gadget', quarter: 'Q1'},
+#   {product: 'Gadget', quarter: 'Q2'}
+# ]>
+```
+
+Output has `self.data.length * other.data.length` rows. Output dimensions are `self.data_dimensions + other.data_dimensions`, in operand order. Duplicates are preserved multiplicatively.
+
+The two Namos must have **no** shared data dimensions — the precondition is the mirror image of `*`. Any overlap raises an `ArgumentError`; allowing it would produce rows with the same dimension named twice. Formulae merge from both sides; the left-hand side wins on conflict.
+
+The visual relationship is intentional: `*` is the filtered version, `**` is the explosive version — more sigil, more output.
+
+### Decomposition
+
+`/` removes from the left Namo the dimensions that are also in the right, then dedupes the projected rows. It's the inverse of `*` and `**`:
+
+```ruby
+combined = Namo.new([
+  {symbol: 'BHP', date: '2025-01-01', close: 42.5, pe: 14.5},
+  {symbol: 'RIO', date: '2025-01-01', close: 118.3, pe: 9.2}
+])
+
+fundamentals = Namo.new([
+  {symbol: 'BHP', pe: 14.5},
+  {symbol: 'RIO', pe: 9.2}
+])
+
+combined / fundamentals
+# => #<Namo [
+#   {date: '2025-01-01', close: 42.5},
+#   {date: '2025-01-01', close: 118.3}
+# ]>
+```
+
+The intersection of dimensions — here `:symbol` and `:pe` — is removed. Everything else stays. The projected rows are deduplicated, so `/` answers "what's left when these dimensions are factored out?" rather than "what rows survive a column drop?". Formulae carry through from the left-hand side.
+
+`/` has no precondition. When the two Namos share no dimensions, the intersection is empty, nothing is removed, and `self / other` returns a Namo equal to self:
+
+```ruby
+shipments = Namo.new([{order_id: 1, weight: 10}])
+weather = Namo.new([{date: '2025-01-01', temperature: 22}])
+
+shipments / weather
+# => #<Namo [{order_id: 1, weight: 10}]> — equal to shipments
+```
+
+The round-trip identity holds for the `**` case exactly:
+
+```ruby
+a = Namo.new([{symbol: 'BHP'}, {symbol: 'RIO'}])
+b = Namo.new([{quarter: 'Q1'}, {quarter: 'Q2'}])
+
+(a ** b) / b == a
+# => true
+```
+
+For `*`, the round-trip is lossy on the dimensions that were shared between the operands:
+
+```ruby
+a = Namo.new([{symbol: 'BHP', close: 42.5}, {symbol: 'RIO', close: 118.3}])
+b = Namo.new([{symbol: 'BHP', pe: 14.5}, {symbol: 'RIO', pe: 9.2}])
+
+(a * b) / b
+# => #<Namo [{close: 42.5}, {close: 118.3}]>
+# Equal to a[-:symbol]. :symbol was shared and is lost.
+```
+
+The asymmetry is inherent: `/` operates only on the two values it receives and can't distinguish "shared dimension that belonged to both" from "exclusive dimension that belonged only to the right". Removing the intersection is the only rule expressible from the operands alone, and it gives clean recovery from `**` and well-defined (if lossy) recovery from `*`.
+
+#### Why `/` is loose
+
+`*` and `**` raise when their preconditions are violated — combining unrelated Namos has no natural answer, and silently producing arbitrary output would turn a logic error into a large pile of nonsense rows. `/` is different: it's a projecting operator, not a combining one, and projecting away nothing returns the original. The no-precondition rule isn't a fallback; it's the structurally correct result.
+
+This earns `/` three properties a strict version would lose:
+
+- **Identity test.** `combined / other == combined` exactly when the two have no shared dimensions — answers "are these Namos dimensionally independent?" without explicit introspection. Same shape as `a & b == a` answering subset from 0.6.0.
+- **Idempotence.** `(c / b) / b == c / b`. Once `b`'s dimensions are removed, removing them again does nothing.
+- **Pipeline composition.** A processing step that applies `/ separator` can run over any Namo regardless of whether the separator's dimensions apply. Uninvolved Namos pass through unchanged; involved Namos get stripped. The pipeline doesn't need to special-case applicability.
+
+This is the same pattern that makes `Array#-` useful with arrays that aren't subsets: `[1, 2, 3] - [9] == [1, 2, 3]`, not an error. The no-op-on-non-applicable behaviour lets the operator compose into pipelines that don't know in advance whether the operation applies.
+
 ### Equality
 
 Comparison on Namos is **multiset-theoretic on rows**: row order is ignored (it's an accident of ingestion, not data), but row multiplicities count (they *are* data). The same stance carries across the equality, pattern-match, and subset/superset operators below.

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
 end

data/lib/namo.rb

@@ -110,6 +110,42 @@ class Namo
     self.class.new((@data - other.data) + (other.data - @data), formulae: other.formulae.merge(@formulae))
   end
 
+  def *(other)
+    raise_unless_namo(other)
+    raise_unless_shared_data_dimensions(other)
+    shared = data_dimensions & other.data_dimensions
+    combined_data = []
+    @data.each do |left_row|
+      other.data.each do |right_row|
+        if shared.all?{|dim| left_row[dim] == right_row[dim]}
+          combined_data << left_row.merge(right_row)
+        end
+      end
+    end
+    self.class.new(combined_data, formulae: other.formulae.merge(@formulae))
+  end
+
+  def **(other)
+    raise_unless_namo(other)
+    raise_unless_disjoint_data_dimensions(other)
+    combined_data = []
+    @data.each do |left_row|
+      other.data.each do |right_row|
+        combined_data << left_row.merge(right_row)
+      end
+    end
+    self.class.new(combined_data, formulae: other.formulae.merge(@formulae))
+  end
+
+  def /(other)
+    raise_unless_namo(other)
+    kept = data_dimensions - other.data_dimensions
+    projected = @data.map do |row|
+      kept.each_with_object({}){|dim, hash| hash[dim] = row[dim]}
+    end
+    self.class.new(projected.uniq, formulae: @formulae.dup)
+  end
+
   def ==(other)
     return false unless other.is_a?(Namo)
     canonical_data == other.canonical_data
@@ -201,6 +237,18 @@ class Namo
     end
   end
 
+  def raise_unless_shared_data_dimensions(other)
+    if (data_dimensions & other.data_dimensions).empty?
+      raise ArgumentError, "no shared dimensions, need to have shared dimensions: #{data_dimensions} vs #{other.data_dimensions}"
+    end
+  end
+
+  def raise_unless_disjoint_data_dimensions(other)
+    if (data_dimensions & other.data_dimensions).any?
+      raise ArgumentError, "dimensions in common, need no common dimensions: #{data_dimensions} vs #{other.data_dimensions}"
+    end
+  end
+
   def initialize(data = nil, formulae: {})
     @data = data
     @formulae = formulae

data/test/namo_test.rb

@@ -710,6 +710,288 @@ describe Namo do
     end
   end
 
+  describe "#*" do
+    let(:ohlcv) do
+      Namo.new([
+        {symbol: 'BHP', date: '2025-01-01', close: 42.5},
+        {symbol: 'RIO', date: '2025-01-01', close: 118.3}
+      ])
+    end
+
+    let(:fundamentals) do
+      Namo.new([
+        {symbol: 'BHP', pe: 14.5},
+        {symbol: 'RIO', pe: 9.2}
+      ])
+    end
+
+    it "joins on a single shared dimension" do
+      result = ohlcv * fundamentals
+      _(result.to_a).must_equal [
+        {symbol: 'BHP', date: '2025-01-01', close: 42.5, pe: 14.5},
+        {symbol: 'RIO', date: '2025-01-01', close: 118.3, pe: 9.2}
+      ]
+    end
+
+    it "joins on multiple shared dimensions" do
+      a = Namo.new([
+        {symbol: 'BHP', date: '2025-01-01', close: 42.5},
+        {symbol: 'BHP', date: '2025-01-02', close: 43.0}
+      ])
+      b = Namo.new([
+        {symbol: 'BHP', date: '2025-01-01', volume: 1000},
+        {symbol: 'BHP', date: '2025-01-02', volume: 1500}
+      ])
+      result = a * b
+      _(result.to_a).must_equal [
+        {symbol: 'BHP', date: '2025-01-01', close: 42.5, volume: 1000},
+        {symbol: 'BHP', date: '2025-01-02', close: 43.0, volume: 1500}
+      ]
+    end
+
+    it "preserves non-shared dimensions from both sides" do
+      result = ohlcv * fundamentals
+      _(result.dimensions).must_equal [:symbol, :date, :close, :pe]
+    end
+
+    it "drops unmatched rows from both sides (inner-join symmetry)" do
+      left = Namo.new([
+        {symbol: 'BHP', close: 42.5},
+        {symbol: 'CBA', close: 100.0}
+      ])
+      right = Namo.new([
+        {symbol: 'BHP', pe: 14.5},
+        {symbol: 'RIO', pe: 9.2}
+      ])
+      result = left * right
+      _(result.to_a).must_equal [{symbol: 'BHP', close: 42.5, pe: 14.5}]
+    end
+
+    it "produces multiplicative duplicates when inputs have duplicates on shared dimensions" do
+      left = Namo.new([
+        {symbol: 'BHP', close: 42.5},
+        {symbol: 'BHP', close: 43.0}
+      ])
+      right = Namo.new([
+        {symbol: 'BHP', pe: 14.5},
+        {symbol: 'BHP', pe: 14.7}
+      ])
+      result = left * right
+      _(result.to_a.length).must_equal 4
+      _(result.to_a).must_equal [
+        {symbol: 'BHP', close: 42.5, pe: 14.5},
+        {symbol: 'BHP', close: 42.5, pe: 14.7},
+        {symbol: 'BHP', close: 43.0, pe: 14.5},
+        {symbol: 'BHP', close: 43.0, pe: 14.7}
+      ]
+    end
+
+    it "carries formulae through from self" do
+      ohlcv[:label] = proc{|r| "#{r[:symbol]}-self"}
+      result = ohlcv * fundamentals
+      _(result.map{|row| row[:label]}).must_equal ['BHP-self', 'RIO-self']
+    end
+
+    it "merges formulae from other" do
+      fundamentals[:flag] = proc{|r| "pe=#{r[:pe]}"}
+      result = ohlcv * fundamentals
+      _(result.map{|row| row[:flag]}).must_equal ['pe=14.5', 'pe=9.2']
+    end
+
+    it "prefers self's formulae on conflict" do
+      ohlcv[:label] = proc{|r| "self: #{r[:symbol]}"}
+      fundamentals[:label] = proc{|r| "other: #{r[:symbol]}"}
+      result = ohlcv * fundamentals
+      _(result.map{|row| row[:label]}).must_equal ['self: BHP', 'self: RIO']
+    end
+
+    it "raises ArgumentError when there are no shared dimensions" do
+      a = Namo.new([{symbol: 'BHP'}])
+      b = Namo.new([{quarter: 'Q1'}])
+      err = _ { a * b }.must_raise ArgumentError
+      _(err.message).must_match(/no shared dimensions, need to have shared dimensions/)
+    end
+
+    it "raises TypeError on a non-Namo operand" do
+      _ { ohlcv * [{symbol: 'BHP'}] }.must_raise TypeError
+    end
+
+    it "returns an instance of self's class" do
+      subclass = Class.new(Namo)
+      a = subclass.new([{symbol: 'BHP', close: 42.5}])
+      b = Namo.new([{symbol: 'BHP', pe: 14.5}])
+      _((a * b).class).must_equal subclass
+    end
+  end
+
+  describe "#**" do
+    let(:products) do
+      Namo.new([{product: 'Widget'}, {product: 'Gadget'}])
+    end
+
+    let(:quarters) do
+      Namo.new([{quarter: 'Q1'}, {quarter: 'Q2'}])
+    end
+
+    it "Cartesian-products two disjoint Namos" do
+      result = products ** quarters
+      _(result.to_a).must_equal [
+        {product: 'Widget', quarter: 'Q1'},
+        {product: 'Widget', quarter: 'Q2'},
+        {product: 'Gadget', quarter: 'Q1'},
+        {product: 'Gadget', quarter: 'Q2'}
+      ]
+    end
+
+    it "has self.data.length * other.data.length rows" do
+      a = Namo.new([{x: 1}, {x: 2}, {x: 3}])
+      b = Namo.new([{y: 'a'}, {y: 'b'}])
+      _((a ** b).to_a.length).must_equal 6
+    end
+
+    it "output dimensions are self.data_dimensions + other.data_dimensions" do
+      result = products ** quarters
+      _(result.dimensions).must_equal [:product, :quarter]
+    end
+
+    it "preserves duplicates on either side multiplicatively" do
+      a = Namo.new([{x: 1}, {x: 1}])
+      b = Namo.new([{y: 'a'}, {y: 'a'}])
+      result = a ** b
+      _(result.to_a.length).must_equal 4
+    end
+
+    it "carries formulae through from self" do
+      products[:label] = proc{|r| "self: #{r[:product]}"}
+      result = products ** quarters
+      _(result.map{|row| row[:label]}).must_equal [
+        'self: Widget', 'self: Widget', 'self: Gadget', 'self: Gadget'
+      ]
+    end
+
+    it "merges formulae from other" do
+      quarters[:flag] = proc{|r| "q=#{r[:quarter]}"}
+      result = products ** quarters
+      _(result.map{|row| row[:flag]}).must_equal ['q=Q1', 'q=Q2', 'q=Q1', 'q=Q2']
+    end
+
+    it "prefers self's formulae on conflict" do
+      products[:label] = proc{|r| "self: #{r[:product]}"}
+      quarters[:label] = proc{|r| "other: #{r[:quarter]}"}
+      result = products ** quarters
+      _(result.map{|row| row[:label]}).must_equal [
+        'self: Widget', 'self: Widget', 'self: Gadget', 'self: Gadget'
+      ]
+    end
+
+    it "raises ArgumentError when any dimension is shared" do
+      a = Namo.new([{symbol: 'BHP', close: 42.5}])
+      b = Namo.new([{symbol: 'RIO', pe: 14.5}])
+      err = _ { a ** b }.must_raise ArgumentError
+      _(err.message).must_match(/dimensions in common, need no common dimensions/)
+    end
+
+    it "raises TypeError on a non-Namo operand" do
+      _ { products ** [{quarter: 'Q1'}] }.must_raise TypeError
+    end
+
+    it "returns an instance of self's class" do
+      subclass = Class.new(Namo)
+      a = subclass.new([{product: 'Widget'}])
+      b = Namo.new([{quarter: 'Q1'}])
+      _((a ** b).class).must_equal subclass
+    end
+  end
+
+  describe "#/" do
+    let(:combined) do
+      Namo.new([
+        {symbol: 'BHP', date: '2025-01-01', close: 42.5, pe: 14.5},
+        {symbol: 'RIO', date: '2025-01-01', close: 118.3, pe: 9.2}
+      ])
+    end
+
+    let(:fundamentals) do
+      Namo.new([
+        {symbol: 'BHP', pe: 14.5},
+        {symbol: 'RIO', pe: 9.2}
+      ])
+    end
+
+    it "removes dimensions present in both self and other (the intersection)" do
+      result = combined / fundamentals
+      _(result.dimensions).must_equal [:date, :close]
+    end
+
+    it "preserves dimensions exclusive to self" do
+      result = combined / fundamentals
+      _(result.to_a).must_equal [
+        {date: '2025-01-01', close: 42.5},
+        {date: '2025-01-01', close: 118.3}
+      ]
+    end
+
+    it "dedupes rows that collide after projection" do
+      a = Namo.new([
+        {symbol: 'BHP', close: 42.5},
+        {symbol: 'RIO', close: 42.5}
+      ])
+      b = Namo.new([{symbol: 'X'}])
+      result = a / b
+      _(result.to_a).must_equal [{close: 42.5}]
+    end
+
+    it "carries formulae through from self" do
+      combined[:label] = proc{|r| "row: #{r[:close]}"}
+      result = combined / fundamentals
+      _(result.map{|row| row[:label]}).must_equal ['row: 42.5', 'row: 118.3']
+    end
+
+    it "is a no-op when self and other share no dimensions" do
+      shipments = Namo.new([{order_id: 1, weight: 10}])
+      weather = Namo.new([{date: '2025-01-01', temperature: 22}])
+      _(shipments / weather).must_equal shipments
+    end
+
+    it "ignores dimensions present in other but not in self" do
+      a = Namo.new([{symbol: 'BHP', close: 42.5}])
+      b = Namo.new([{symbol: 'BHP', pe: 14.5, sector: 'Mining'}])
+      result = a / b
+      _(result.dimensions).must_equal [:close]
+    end
+
+    it "is idempotent" do
+      first = combined / fundamentals
+      second = first / fundamentals
+      _(second).must_equal first
+    end
+
+    it "raises TypeError on a non-Namo operand" do
+      _ { combined / [{symbol: 'BHP'}] }.must_raise TypeError
+    end
+
+    it "returns an instance of self's class" do
+      subclass = Class.new(Namo)
+      a = subclass.new([{symbol: 'BHP', close: 42.5}])
+      b = Namo.new([{symbol: 'BHP', pe: 14.5}])
+      _((a / b).class).must_equal subclass
+    end
+  end
+
+  describe "composition round-trip" do
+    it "satisfies (a ** b) / b == a for disjoint a and b" do
+      a = Namo.new([{symbol: 'BHP'}, {symbol: 'RIO'}])
+      b = Namo.new([{quarter: 'Q1'}, {quarter: 'Q2'}])
+      _((a ** b) / b).must_equal a
+    end
+
+    it "satisfies (a * b) / b == a[-:shared] for a and b with shared dimensions (shared dimensions lost)" do
+      a = Namo.new([{symbol: 'BHP', close: 42.5}, {symbol: 'RIO', close: 118.3}])
+      b = Namo.new([{symbol: 'BHP', pe: 14.5}, {symbol: 'RIO', pe: 9.2}])
+      _((a * b) / b).must_equal Namo.new([{close: 42.5}, {close: 118.3}])
+    end
+  end
+
   describe "#==" do
     it "is true for same data, same order" do
       a = Namo.new([{x: 1}, {x: 2}])

metadata

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