dtwrb 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a69f04b76a452056c2749e7f695a8d9adcb3f1469e4f672ff2f9a5f95c7ab116
-  data.tar.gz: 0bc45f0c9b9947b6be08ec1c26fb318d6e6a18c47ef2c789a60d869c5889a709
+  metadata.gz: 46ff5e2b8f1059ffe352f4499f9858ca31a6503ac3f63c1ab17f79615be514a1
+  data.tar.gz: 6de49d664f809e686bd47902a4485162bcaef6ccc991814503af2dc7ee19bcd2
 SHA512:
-  metadata.gz: 2d93d6b736d7655571db2a0af148d7f35e5b74d26bb79d3313542c3ef2d31f15e01b522b961d32500e259bb636cefa3cea3e7cc0c43b1b88686f955460554b5f
-  data.tar.gz: 3bd0dcd7d9c90ee8280f031f6621b5e8d220b79af807e766e2077c8bb94d1b64fc36a115a92d8d9490c59eda14e152b0709ac0568ef63aed2436d2c831a01105
+  metadata.gz: 9a9397d37e53c60dcaff865ba61e6acce1e1f1bdd93b7455d001f0755546078d68df1c45f5b8d80246472741df30ce2953fe9efef27ca27372b1ac6315fd9094
+  data.tar.gz: 9813d307282cffda759a1178cabb2062f7f55705be0bee415abda0e63d089e18a01fb436b3394a235bb63d659db24aed9620a1867e54a565606275d5cd89bda8

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.1.0 — 2026-08-22
+
+- `DTW::Bands::Slanted`: a global constraint that follows the diagonal of the rectangle, so the
+  radius keeps constraining the path when the sequences differ in length. The literal Sakoe–Chiba
+  band widens to `|n − m| + 1` in that case and stops bounding the warping; on a `40 × 140` pair a
+  ratio of `0.25` asks for 35 cells either side but gets 101. Reachable as `:slanted`.
+- Bands may now expose `#bounds(i, n, m) -> [Integer, Integer]` for per-row limits. `#radius` alone
+  is still enough, and `DTW::Bands::SakoeChiba` is unchanged.
+
 ## 1.0.0 — 2026-08-01
 
 Initial public release.

data/README.md

@@ -111,12 +111,12 @@ DTW.medoid(observations)
 
 Any object that responds to `#call(frame_a, frame_b) -> Float` is accepted.
 
-| Name | Definition | Notes |
-| --- | --- | --- |
-| `:euclidean` | L² | default |
-| `:manhattan` | L¹ | less sensitive to one deviant coordinate |
-| `:chebyshev` | L∞ | worst-coordinate deviation |
-| `:cosine` | 1 − cos θ, range [0, 2] | scale-invariant; compares direction only |
+| Name         | Definition              | Notes                                    |
+| ------------ | ----------------------- | ---------------------------------------- |
+| `:euclidean` | L²                      | default                                  |
+| `:manhattan` | L¹                      | less sensitive to one deviant coordinate |
+| `:chebyshev` | L∞                      | worst-coordinate deviation               |
+| `:cosine`    | 1 − cos θ, range [0, 2] | scale-invariant; compares direction only |
 
 ```ruby
 DTW.distance(a, b, metric: :manhattan)
@@ -132,18 +132,37 @@ which bounds the admissible warping and reduces the cost matrix to a diagonal st
 r = max( ⌈ratio · max(n, m)⌉, |n − m| + 1 )
 ```
 
-The second term guarantees that at least one path stays feasible, including for sequences of very
-unequal length.
+The second term guarantees that at least one path stays feasible. It also means that the band
+stops constraining once the lengths diverge: at `n = 40, m = 140` the radius is at least 101
+whatever ratio is asked for, because the strip must reach the far corner from the main diagonal.
 
-| Value | Meaning |
-| --- | --- |
-| `0.25` | default ratio |
-| any `Numeric` | Sakoe–Chiba band with that ratio |
-| `:unconstrained` | full cost matrix |
-| custom | any object that responds to `#radius(n, m) -> Integer` |
+The slanted band removes that limitation by following the diagonal of the rectangle rather than
+the main diagonal, so the radius keeps its meaning at any length ratio:
+
+```text
+centre(i) = 1 + (i − 1) · (m − 1) / (n − 1),   |j − centre(i)| ≤ r
+r         = max( ⌈ratio · max(n, m)⌉, ⌈½ · (m − 1) / (n − 1)⌉, 1 )
+```
+
+The second term is half a step of the diagonal, below which consecutive rows no longer overlap
+and no path exists. On the same `40 × 140` pair a ratio of `0.25` gives `r = 35` instead of `101`.
+
+| Value            | Meaning                                                                                                     |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- |
+| `0.25`           | default ratio                                                                                               |
+| any `Numeric`    | Sakoe–Chiba band with that ratio                                                                            |
+| `:sakoe_chiba`   | Sakoe–Chiba band at the default ratio                                                                       |
+| `:slanted`       | slanted band at the default ratio                                                                           |
+| `:unconstrained` | full cost matrix                                                                                            |
+| custom           | any object that responds to `#radius(n, m) -> Integer`, optionally `#bounds(i, n, m) -> [Integer, Integer]` |
 
 Narrowing the band can only raise the accumulated cost, never lower it.
 
+```ruby
+DTW::Bands::SakoeChiba.new(ratio: 0.25).radius(40, 140)                      # => 101
+DTW::Bands::Slanted.new(ratio: 0.25).radius(40, 140)                         # => 35
+```
+
 ## Statistics and resampling
 
 ```ruby
@@ -180,12 +199,12 @@ prototyping problem.
 
 ## Complexity
 
-| Operation | Time | Memory |
-| --- | --- | --- |
-| Unconstrained alignment | O(n·m·D) | O(n·m) |
-| Banded alignment | O(r·max(n, m)·D) | O(n·m) |
-| Medoid over k sequences | O(min(k, s)²) alignments | O(min(k, s)) |
-| Barycenter, I iterations | O((I + 1)·k·n·m·D) | O(n·m + L·D·k) |
+| Operation                | Time                     | Memory         |
+| ------------------------ | ------------------------ | -------------- |
+| Unconstrained alignment  | O(n·m·D)                 | O(n·m)         |
+| Banded alignment         | O(r·max(n, m)·D)         | O(n·m)         |
+| Medoid over k sequences  | O(min(k, s)²) alignments | O(min(k, s))   |
+| Barycenter, I iterations | O((I + 1)·k·n·m·D)       | O(n·m + L·D·k) |
 
 `n` and `m` are sequence lengths, `D` the frame dimension, `r` the band radius, `s` the medoid
 sample size, `L` the prototype length.

data/lib/dtwrb/aligner.rb

@@ -29,7 +29,7 @@ module DTW
     def accumulate(frames_a, frames_b)
       rows = frames_a.length
       columns = frames_b.length
-      radius = @band.radius(rows, columns)
+      limits = window(rows, columns)
       grid = Array.new(rows + 1) { Array.new(columns + 1, Float::INFINITY) }
       grid[0][0] = 0.0
 
@@ -38,8 +38,9 @@ module DTW
         frame = frames_a[row_index - 1]
         row = grid[row_index]
         previous_row = grid[row_index - 1]
-        column_index = [1, row_index - radius].max
-        last_column = [columns, row_index + radius].min
+        first, last = limits[row_index]
+        column_index = first
+        last_column = last
 
         while column_index <= last_column
           best = previous_row[column_index]
@@ -57,6 +58,18 @@ module DTW
       grid
     end
 
+    def window(rows, columns)
+      if @band.respond_to?(:bounds)
+        Array.new(rows + 1) do |row|
+          first, last = @band.bounds(row, rows, columns)
+          [[1, first].max, [columns, last].min]
+        end
+      else
+        radius = @band.radius(rows, columns)
+        Array.new(rows + 1) { |row| [[1, row - radius].max, [columns, row + radius].min] }
+      end
+    end
+
     def backtrack(grid, rows, columns)
       path = []
       row_index = rows

data/lib/dtwrb/bands.rb

@@ -14,10 +14,47 @@ module DTW
       def radius(length_a, length_b)
         [(ratio * [length_a, length_b].max).ceil, (length_a - length_b).abs + 1].max
       end
+
+      def bounds(row, rows, columns)
+        width = radius(rows, columns)
+        [row - width, row + width]
+      end
+    end
+
+    # The band follows the diagonal of the rectangle, so the radius keeps constraining
+    # the path when the two sequences differ in length.
+    Slanted = Data.define(:ratio) do
+      def initialize(ratio:)
+        width = Float(ratio)
+        raise ArgumentError, "band ratio must be non-negative, got #{width}" if width.negative?
+
+        super(ratio: width)
+      end
+
+      def radius(rows, columns)
+        [(ratio * [rows, columns].max).ceil, reachable(rows, columns)].max
+      end
+
+      def bounds(row, rows, columns)
+        return [1, columns] if rows < 2 || columns < 2
+
+        width = radius(rows, columns)
+        centre = 1.0 + ((row - 1) * (columns - 1).fdiv(rows - 1))
+        [(centre - width).ceil, (centre + width).floor]
+      end
+
+      # Half a step of the diagonal, below which consecutive rows no longer overlap.
+      def reachable(rows, columns)
+        return 1 if rows < 2 || columns < 2
+
+        [((columns - 1).fdiv(rows - 1) / 2).ceil, 1].max
+      end
     end
 
     module Unconstrained
       def self.radius(length_a, length_b) = [length_a, length_b].max
+
+      def self.bounds(_row, _rows, columns) = [1, columns]
     end
 
     # Admits warping of up to a quarter of the longer sequence, the usual setting for speech.
@@ -25,6 +62,8 @@ module DTW
 
     DEFAULT = SakoeChiba.new(ratio: DEFAULT_RATIO)
 
+    SLANTED = Slanted.new(ratio: DEFAULT_RATIO)
+
     module_function
 
     def resolve(band)
@@ -35,13 +74,15 @@ module DTW
         Unconstrained
       when :sakoe_chiba
         DEFAULT
+      when :slanted
+        SLANTED
       else
         return band if band.respond_to?(:radius)
 
         raise(
           UnknownStrategyError,
           "unknown band #{band.inspect}: expected a numeric Sakoe-Chiba ratio, :sakoe_chiba, " \
-            ":unconstrained or an object responding to #radius"
+            ":slanted, :unconstrained or an object responding to #radius"
         )
       end
     end

data/lib/dtwrb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DTW
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/sig/dtwrb.rbs

@@ -108,6 +108,7 @@ module DTW
   module Bands
     DEFAULT_RATIO: ::Float
     DEFAULT: SakoeChiba
+    SLANTED: Slanted
 
     def self.resolve: (band) -> _Band
 
@@ -116,12 +117,25 @@ module DTW
 
       def self.new: (ratio: ::Numeric) -> SakoeChiba
       def radius: (::Integer, ::Integer) -> ::Integer
+      def bounds: (::Integer, ::Integer, ::Integer) -> [::Integer, ::Integer]
       def with: (**untyped) -> SakoeChiba
       def to_h: () -> ::Hash[::Symbol, untyped]
     end
 
+    class Slanted
+      attr_reader ratio: ::Float
+
+      def self.new: (ratio: ::Numeric) -> Slanted
+      def radius: (::Integer, ::Integer) -> ::Integer
+      def bounds: (::Integer, ::Integer, ::Integer) -> [::Integer, ::Integer]
+      def reachable: (::Integer, ::Integer) -> ::Integer
+      def with: (**untyped) -> Slanted
+      def to_h: () -> ::Hash[::Symbol, untyped]
+    end
+
     module Unconstrained
       def self.radius: (::Integer, ::Integer) -> ::Integer
+      def self.bounds: (::Integer, ::Integer, ::Integer) -> [::Integer, ::Integer]
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dtwrb
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Den Patin
@@ -103,7 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Dynamic Time Warping, DBA barycenter averaging and robust dispersion for
   numeric sequences