dtwrb 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a69f04b76a452056c2749e7f695a8d9adcb3f1469e4f672ff2f9a5f95c7ab116
+  data.tar.gz: 0bc45f0c9b9947b6be08ec1c26fb318d6e6a18c47ef2c789a60d869c5889a709
+SHA512:
+  metadata.gz: 2d93d6b736d7655571db2a0af148d7f35e5b74d26bb79d3313542c3ef2d31f15e01b522b961d32500e259bb636cefa3cea3e7cc0c43b1b88686f955460554b5f
+  data.tar.gz: 3bd0dcd7d9c90ee8280f031f6621b5e8d220b79af807e766e2077c8bb94d1b64fc36a115a92d8d9490c59eda14e152b0709ac0568ef63aed2436d2c831a01105

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 1.0.0 — 2026-08-01
+
+Initial public release.
+
+- DTW alignment with the Sakoe–Chiba band constraint (`DTW::Aligner`, `DTW::Bands`)
+- Local distances: Euclidean, Manhattan, Chebyshev, cosine (`DTW::Metrics`)
+- DTW Barycenter Averaging with median or mean aggregation (`DTW::BarycenterAveraging`)
+- Approximate medoid selection over a uniform subsample (`DTW::Medoid`)
+- Linear resampling of frame sequences (`DTW::Resampler`)
+- Median, mean, MAD, and Bessel-corrected standard deviation (`DTW::Statistics`)
+- Scalar and multivariate sequences accepted interchangeably (`DTW::Sequence`, `DTW::Sample`)
+- RBS signatures under `sig/`

data/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2026 Den Patin <hi@dpat.in>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

data/README.md

@@ -0,0 +1,212 @@
+# dtwrb
+
+Dynamic Time Warping (DTW), DTW Barycenter Averaging (DBA), and robust dispersion estimation for
+numeric sequences. Pure Ruby, no runtime dependencies.
+
+Extracted from [taiwancards](https://github.com/taiwancards/taiwancards), where it drives acoustic
+pronunciation scoring.
+
+## The problem
+
+Point-to-point comparison — Euclidean distance between samples at equal indices — assumes that two
+sequences have the same length and the same phase. Repeated observations of one process violate
+both assumptions: two utterances of the same syllable, two executions of the same gesture, and two
+runs of the same machine cycle differ in duration and in local timing.
+
+DTW drops the assumption. It computes the minimum-cost monotone, continuous alignment between two
+sequences, letting either one stretch or compress locally. DBA lifts the idea from comparison to
+estimation: given many variable-length observations of one process, it returns a single prototype
+sequence in the DTW sense.
+
+## Install
+
+```ruby
+gem "dtwrb"
+```
+
+## Alignment
+
+Accumulated cost follows the standard recurrence with the symmetric step pattern
+`{(1,1), (1,0), (0,1)}`:
+
+```text
+D(i, j) = d(a_i, b_j) + min{ D(i-1, j), D(i, j-1), D(i-1, j-1) }
+```
+
+`d` is the local distance between two frames. `Alignment#cost` is `D(n, m)`. `Alignment#distance`
+divides it by the number of path cells, which removes the bias that longer warping paths accumulate
+more terms.
+
+```ruby
+require "dtwrb"
+
+a = [0.0, 1.0, 2.0, 3.0, 4.0]
+b = [0.0, 0.0, 1.0, 2.0, 3.0, 4.0, 4.0]
+
+DTW.distance(a, b)
+# => 0.0
+
+DTW.align(a, b).path
+# => [[0, 0], [0, 1], [1, 2], [2, 3], [3, 4], [4, 5], [4, 6]]
+```
+
+`b` is `a` with its first and last frame repeated. Euclidean comparison cannot even be formed here,
+since the lengths differ; DTW reports exact identity and returns the path that proves it.
+
+A sequence is either scalar (`[0.0, 1.0, ...]`) or multivariate (`[[0.0, 9.0], [1.0, 8.0], ...]`).
+Scalar input is read as one-dimensional frames and yields scalar output.
+
+## Barycenter averaging
+
+`DTW::BarycenterAveraging` implements DBA (Petitjean, Ketterlin & Gançarski, 2011):
+
+1. initialize the prototype from the medoid of the sample, resampled to the requested length;
+2. align every observation to the prototype;
+3. for each prototype frame and coordinate, aggregate the observation frames that the warping paths
+   associated with it;
+4. repeat until the mean absolute update falls below `tolerance`.
+
+The default aggregator is the **median**, not the arithmetic mean of the original formulation. Its
+breakdown point is 50%, so a minority of corrupt observations cannot displace the prototype.
+Dispersion is reported per frame and coordinate as the median absolute deviation scaled by 1.4826,
+a consistent estimator of σ under normality.
+
+```ruby
+observations = [
+  [0.0, 1.0, 2.1, 3.0, 4.0],
+  [0.0, 0.0, 1.2, 2.0, 3.1, 4.0],
+  [0.0, 0.9, 2.0, 2.0, 2.9, 4.2],
+  [0.1, 1.1, 2.0, 3.2, 4.0]
+]
+
+prototype = DTW.barycenter(observations, length: 5)
+
+prototype.center      # => [0.0, 1.05, 2.0, 3.05, 4.0]
+prototype.dispersion  # => [0.0, 0.148, 0.0, 0.148, 0.0]
+prototype.count       # => 4
+prototype.length      # => 5
+```
+
+Length defaults to the rounded mean length of the sample. The classic mean-based formulation is one
+argument away:
+
+```ruby
+DTW.barycenter(observations, length: 5, aggregator: :mean).center
+# => [0.02, 1.05, 2.02, 3.05, 4.05]
+```
+
+## Medoid
+
+The medoid is the observation with the smallest total DTW distance to all others — the most central
+real sequence, as opposed to a synthetic one. Exact selection costs O(k²) alignments, so candidates
+are drawn as a uniform subsample of size `sample_size` (12 by default). Selection is deterministic;
+no pseudo-random number generator is used anywhere in this library.
+
+```ruby
+DTW.medoid(observations)
+# => [0.0, 0.0, 1.2, 2.0, 3.1, 4.0]
+```
+
+## Local distances
+
+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 |
+
+```ruby
+DTW.distance(a, b, metric: :manhattan)
+DTW.distance(a, b, metric: ->(x, y) { (x.first - y.first).abs })
+```
+
+## Global constraint
+
+The Sakoe–Chiba band (Sakoe & Chiba, 1978) restricts the alignment to cells with `|i − j| ≤ r`,
+which bounds the admissible warping and reduces the cost matrix to a diagonal strip:
+
+```text
+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.
+
+| 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` |
+
+Narrowing the band can only raise the accumulated cost, never lower it.
+
+## Statistics and resampling
+
+```ruby
+DTW::Statistics.median([5.0, 1.0, 3.0])                                      # => 3.0
+DTW::Statistics.median_absolute_deviation([10.0, 11.0, 12.0, 13.0, 1000.0])  # => 1.4826
+DTW::Statistics.standard_deviation([2.0, 4.0, 4.0, 4.0, 5.0])                # => 1.0954451150103321
+
+DTW::Resampler.call([[0.0], [10.0]], 3)                                      # => [[0.0], [5.0], [10.0]]
+```
+
+## In practice
+
+[taiwancards](https://github.com/taiwancards/taiwancards) teaches Taiwanese Mandarin and scores
+learner recordings against native templates. The library is used at two stages.
+
+**Template construction, offline.** For every syllable-and-tone key the corpus pipeline gathers
+recordings from many speakers. Speaking rate differs, so the MFCC matrices (13 coefficients per
+frame) and the F0 tone contours arrive at different lengths. `DTW.barycenter` reduces each set to
+one prototype — 12 frames for MFCC, 16 for the tone contour — plus the per-frame dispersion that
+becomes the tolerance band.
+
+**Scoring, online.** A learner utterance is framed into its own MFCC matrix. `DTW.distance` to the
+prototype center gives a rate-invariant timbre score, so a slow speaker is not penalized for being
+slow. The stored dispersion turns that raw distance into a z-score, so syllables whose realization
+is naturally variable do not raise false alarms.
+
+Field recordings contain clipped, truncated, and mislabeled tokens. Median aggregation keeps such a
+minority from dragging the prototype away from the actual articulation target — the property that
+motivated the robust default.
+
+Speech is one instance of the general case. Anything sampled as a variable-rate numeric sequence —
+gesture traces, biosignals, machine cycles, pen trajectories — poses the same alignment and
+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) |
+
+`n` and `m` are sequence lengths, `D` the frame dimension, `r` the band radius, `s` the medoid
+sample size, `L` the prototype length.
+
+## Design
+
+Strategies are injected, never hard-coded: the local distance (`DTW::Metrics`), the global
+constraint (`DTW::Bands`), the central-tendency aggregator, and the dispersion estimator
+(`DTW::Statistics`). `DTW::Aligner`, `DTW::Medoid`, and `DTW::BarycenterAveraging` are immutable and
+reusable; build them once when aligning many pairs.
+
+```ruby
+aligner = DTW::Aligner.new(metric: :cosine, band: 0.1)
+averaging = DTW::BarycenterAveraging.new(aligner: aligner, aggregator: :mean, iterations: 10)
+
+averaging.call(observations, length: 32)
+```
+
+`DTW::Alignment`, `DTW::Barycenter`, and `DTW::Sample` are `Data` value objects: frozen, compared by
+value, copied with `#with`.
+
+## License
+
+WTFPL — see [LICENSE](LICENSE).

data/lib/dtwrb/aligner.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module DTW
+  class Aligner
+    attr_reader :metric, :band
+
+    def initialize(metric: Metrics::DEFAULT, band: Bands::DEFAULT)
+      @metric = Metrics.resolve(metric)
+      @band = Bands.resolve(band)
+      freeze
+    end
+
+    def align(sequence_a, sequence_b)
+      frames_a = Sequence.vectorize(sequence_a)
+      frames_b = Sequence.vectorize(sequence_b)
+      return Alignment::UNDEFINED if frames_a.empty? || frames_b.empty?
+
+      grid = accumulate(frames_a, frames_b)
+      Alignment.new(
+        path: backtrack(grid, frames_a.length, frames_b.length),
+        cost: grid[frames_a.length][frames_b.length]
+      )
+    end
+
+    def distance(sequence_a, sequence_b) = align(sequence_a, sequence_b).distance
+
+    private
+
+    def accumulate(frames_a, frames_b)
+      rows = frames_a.length
+      columns = frames_b.length
+      radius = @band.radius(rows, columns)
+      grid = Array.new(rows + 1) { Array.new(columns + 1, Float::INFINITY) }
+      grid[0][0] = 0.0
+
+      row_index = 1
+      while row_index <= rows
+        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
+
+        while column_index <= last_column
+          best = previous_row[column_index]
+          left = row[column_index - 1]
+          best = left if left < best
+          diagonal = previous_row[column_index - 1]
+          best = diagonal if diagonal < best
+          row[column_index] = @metric.call(frame, frames_b[column_index - 1]) + best
+          column_index += 1
+        end
+
+        row_index += 1
+      end
+
+      grid
+    end
+
+    def backtrack(grid, rows, columns)
+      path = []
+      row_index = rows
+      column_index = columns
+
+      while row_index.positive? && column_index.positive?
+        path << [row_index - 1, column_index - 1]
+        diagonal = grid[row_index - 1][column_index - 1]
+        upper = grid[row_index - 1][column_index]
+        left = grid[row_index][column_index - 1]
+
+        if diagonal <= upper && diagonal <= left
+          row_index -= 1
+          column_index -= 1
+        elsif upper <= left
+          row_index -= 1
+        else
+          column_index -= 1
+        end
+      end
+
+      path.reverse!
+      path.freeze
+    end
+  end
+end

data/lib/dtwrb/alignment.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module DTW
+  Alignment = Data.define(:path, :cost) do
+    def steps = path.length
+
+    def distance = steps.zero? ? cost : cost / steps
+
+    def undefined? = path.empty?
+
+    def to_a = path
+  end
+
+  Alignment::UNDEFINED = Alignment.new(path: [].freeze, cost: Float::INFINITY)
+end

data/lib/dtwrb/bands.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module DTW
+  module Bands
+    SakoeChiba = 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
+
+      # The |n - m| + 1 term keeps at least one path feasible when the lengths differ widely.
+      def radius(length_a, length_b)
+        [(ratio * [length_a, length_b].max).ceil, (length_a - length_b).abs + 1].max
+      end
+    end
+
+    module Unconstrained
+      def self.radius(length_a, length_b) = [length_a, length_b].max
+    end
+
+    # Admits warping of up to a quarter of the longer sequence, the usual setting for speech.
+    DEFAULT_RATIO = 0.25
+
+    DEFAULT = SakoeChiba.new(ratio: DEFAULT_RATIO)
+
+    module_function
+
+    def resolve(band)
+      case band
+      when Numeric
+        SakoeChiba.new(ratio: band)
+      when nil, :unconstrained
+        Unconstrained
+      when :sakoe_chiba
+        DEFAULT
+      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"
+        )
+      end
+    end
+  end
+end

data/lib/dtwrb/barycenter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module DTW
+  Barycenter = Data.define(:center, :dispersion, :count) do
+    def length = center.length
+
+    def dimension
+      frame = center.first
+      frame.is_a?(Array) ? frame.length : 1
+    end
+
+    def scalar? = !center.first.is_a?(Array)
+  end
+end

data/lib/dtwrb/barycenter_averaging.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module DTW
+  class BarycenterAveraging
+    # DBA converges within a few refinement passes; further passes rarely move the prototype.
+    DEFAULT_ITERATIONS = 4
+
+    # Mean absolute update per coordinate below which the prototype counts as settled.
+    DEFAULT_TOLERANCE = 1e-4
+
+    attr_reader :aligner, :iterations, :tolerance
+
+    def initialize(
+      aligner: Aligner.new,
+      aggregator: :median,
+      dispersion: :median_absolute_deviation,
+      iterations: DEFAULT_ITERATIONS,
+      tolerance: DEFAULT_TOLERANCE,
+      sample_size: Medoid::DEFAULT_SAMPLE_SIZE
+    )
+      @aligner = aligner
+      @aggregator = Statistics.resolve(aggregator)
+      @dispersion = Statistics.resolve(dispersion)
+      @iterations = Integer(iterations)
+      @tolerance = Float(tolerance)
+      @medoid = Medoid.new(aligner: aligner, sample_size: sample_size)
+
+      raise ArgumentError, "iterations must be non-negative, got #{@iterations}" if @iterations.negative?
+      raise ArgumentError, "tolerance must be non-negative, got #{@tolerance}" if @tolerance.negative?
+
+      freeze
+    end
+
+    def call(sequences, length: nil)
+      sample = Sample.of(sequences)
+      width = Integer(length || sample.mean_length)
+      raise ArgumentError, "barycenter length must be positive, got #{width}" unless width.positive?
+
+      center = refine(Resampler.call(@medoid.call(sample.sequences), width), sample)
+      spread = summarize(associate(center, sample), @dispersion) { 0.0 }
+
+      build(center, spread, sample)
+    end
+
+    private
+
+    def refine(center, sample)
+      @iterations.times do
+        updated = summarize(associate(center, sample), @aggregator) { |index, axis| center[index][axis] }
+        settled = converged?(center, updated)
+        center = updated
+        break if settled
+      end
+
+      center
+    end
+
+    def associate(center, sample)
+      dimension = sample.dimension
+      associations = Array.new(center.length) { Array.new(dimension) { [] } }
+
+      sample.sequences.each do |frames|
+        @aligner.align(center, frames).path.each do |center_index, frame_index|
+          frame = frames[frame_index]
+          axis = 0
+          while axis < dimension
+            associations[center_index][axis] << frame[axis]
+            axis += 1
+          end
+        end
+      end
+
+      associations
+    end
+
+    def summarize(associations, estimator)
+      associations.each_with_index.map do |axes, index|
+        axes.each_with_index.map do |values, axis|
+          values.empty? ? yield(index, axis) : estimator.call(values)
+        end
+      end
+    end
+
+    def converged?(previous, current)
+      total = 0.0
+      previous.each_with_index do |frame, index|
+        frame.each_with_index { |value, axis| total += (value - current[index][axis]).abs }
+      end
+
+      (total / (previous.length * previous.first.length)) < @tolerance
+    end
+
+    def build(center, spread, sample)
+      return Barycenter.new(center: center, dispersion: spread, count: sample.count) unless sample.scalar?
+
+      Barycenter.new(
+        center: Sequence.scalarize(center),
+        dispersion: Sequence.scalarize(spread),
+        count: sample.count
+      )
+    end
+  end
+end

data/lib/dtwrb/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module DTW
+  Error = Class.new(StandardError)
+
+  InvalidSequenceError = Class.new(Error)
+
+  DimensionMismatchError = Class.new(Error)
+
+  EmptyInputError = Class.new(Error)
+
+  UnknownStrategyError = Class.new(Error)
+end

data/lib/dtwrb/medoid.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module DTW
+  class Medoid
+    # Exact selection costs O(k^2) alignments, so candidates are capped at a uniform subsample.
+    DEFAULT_SAMPLE_SIZE = 12
+
+    attr_reader :aligner, :sample_size
+
+    def initialize(aligner: Aligner.new, sample_size: DEFAULT_SAMPLE_SIZE)
+      @aligner = aligner
+      @sample_size = Integer(sample_size)
+      raise ArgumentError, "sample size must be positive, got #{@sample_size}" unless @sample_size.positive?
+
+      freeze
+    end
+
+    def call(sequences)
+      candidates = subsample(Sequence.compact(sequences))
+      costs = accumulated_costs(candidates)
+
+      candidates[costs.index(costs.min)]
+    end
+
+    private
+
+    def subsample(candidates)
+      return candidates if candidates.length <= @sample_size
+
+      count = candidates.length
+      Array.new(@sample_size) { |index| candidates[index * count / @sample_size] }
+    end
+
+    def accumulated_costs(candidates)
+      costs = Array.new(candidates.length, 0.0)
+
+      candidates.each_with_index do |candidate, index|
+        ((index + 1)...candidates.length).each do |other|
+          separation = @aligner.distance(candidate, candidates[other])
+          costs[index] += separation
+          costs[other] += separation
+        end
+      end
+
+      costs
+    end
+  end
+end

data/lib/dtwrb/metrics.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module DTW
+  module Metrics
+    module_function
+
+    def assert_conformable!(left, right)
+      return if left.length == right.length
+
+      raise(
+        DimensionMismatchError,
+        "local distance requires equal dimensions, got #{left.length} and #{right.length}"
+      )
+    end
+
+    module Euclidean
+      def self.call(left, right)
+        Metrics.assert_conformable!(left, right)
+
+        total = 0.0
+        axis = 0
+        while axis < left.length
+          difference = left[axis] - right[axis]
+          total += difference * difference
+          axis += 1
+        end
+
+        Math.sqrt(total)
+      end
+    end
+
+    module Manhattan
+      def self.call(left, right)
+        Metrics.assert_conformable!(left, right)
+
+        total = 0.0
+        axis = 0
+        while axis < left.length
+          total += (left[axis] - right[axis]).abs
+          axis += 1
+        end
+
+        total
+      end
+    end
+
+    module Chebyshev
+      def self.call(left, right)
+        Metrics.assert_conformable!(left, right)
+
+        largest = 0.0
+        axis = 0
+        while axis < left.length
+          difference = (left[axis] - right[axis]).abs
+          largest = difference if difference > largest
+          axis += 1
+        end
+
+        largest.to_f
+      end
+    end
+
+    module Cosine
+      def self.call(left, right)
+        Metrics.assert_conformable!(left, right)
+
+        product = 0.0
+        left_norm = 0.0
+        right_norm = 0.0
+        axis = 0
+        while axis < left.length
+          product += left[axis] * right[axis]
+          left_norm += left[axis] * left[axis]
+          right_norm += right[axis] * right[axis]
+          axis += 1
+        end
+
+        return 0.0 if left_norm.zero? && right_norm.zero?
+        return 1.0 if left_norm.zero? || right_norm.zero?
+
+        1.0 - (product / Math.sqrt(left_norm * right_norm))
+      end
+    end
+
+    REGISTRY = {
+      euclidean: Euclidean,
+      manhattan: Manhattan,
+      chebyshev: Chebyshev,
+      cosine: Cosine
+    }.freeze
+
+    DEFAULT = Euclidean
+
+    def resolve(metric) = Resolver.call(metric, REGISTRY, "metric")
+  end
+end

data/lib/dtwrb/resampler.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module DTW
+  module Resampler
+    module_function
+
+    def call(frames, length)
+      raise ArgumentError, "resample length must be positive, got #{length}" unless length.positive?
+      return [] if frames.empty?
+      return Array.new(length) { frames.first.map(&:to_f) } if frames.length == 1 || length == 1
+
+      last = frames.length - 1
+
+      Array.new(length) do |index|
+        position = index.to_f * last / (length - 1)
+        lower = position.floor
+        upper = [lower + 1, last].min
+        interpolate(frames[lower], frames[upper], position - lower)
+      end
+    end
+
+    def interpolate(from, to, fraction)
+      Array.new(from.length) { |axis| (from[axis] * (1.0 - fraction)) + (to[axis] * fraction) }
+    end
+  end
+end

data/lib/dtwrb/resolver.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module DTW
+  module Resolver
+    module_function
+
+    def call(value, registry, kind)
+      return value if value.respond_to?(:call)
+
+      registry.fetch(value) do
+        raise(
+          UnknownStrategyError,
+          "unknown #{kind} #{value.inspect}: expected one of #{registry.keys.join(", ")} " \
+            "or an object responding to #call"
+        )
+      end
+    end
+  end
+end

data/lib/dtwrb/sample.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DTW
+  Sample = Data.define(:sequences, :dimension, :scalar) do
+    def self.of(sequences)
+      usable = Sequence.compact(sequences)
+      collection = usable.map { |sequence| Sequence.vectorize(sequence) }
+
+      new(
+        sequences: collection,
+        dimension: Sequence.assert_uniform_dimension!(collection),
+        scalar: usable.all? { |sequence| Sequence.scalar?(sequence) }
+      )
+    end
+
+    def count = sequences.length
+
+    def scalar? = scalar
+
+    def mean_length = [(sequences.sum(&:length).to_f / count).round, 1].max
+  end
+end

data/lib/dtwrb/sequence.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module DTW
+  module Sequence
+    module_function
+
+    def usable?(sequence) = sequence.is_a?(Array) && !sequence.empty?
+
+    def scalar?(sequence) = usable?(sequence) && sequence.first.is_a?(Numeric)
+
+    def vectorize(sequence)
+      raise InvalidSequenceError, "expected an Array of frames, got #{sequence.class}" unless sequence.is_a?(Array)
+
+      scalar?(sequence) ? sequence.map { |value| [value] } : sequence
+    end
+
+    def scalarize(frames) = frames.map(&:first)
+
+    def compact(sequences)
+      usable = Array(sequences).select { |sequence| usable?(sequence) }
+      raise EmptyInputError, "expected at least one non-empty sequence, got none" if usable.empty?
+
+      usable
+    end
+
+    def dimension_of(frames)
+      frame = frames.first
+      raise InvalidSequenceError, "expected a vector frame, got #{frame.class}" unless frame.is_a?(Array)
+
+      frame.length
+    end
+
+    def assert_uniform_dimension!(collection)
+      dimension = dimension_of(collection.first)
+
+      collection.each do |frames|
+        frames.each do |frame|
+          next if frame.is_a?(Array) && frame.length == dimension
+
+          raise DimensionMismatchError, "all frames must share dimension #{dimension}, got #{frame.inspect}"
+        end
+      end
+
+      dimension
+    end
+  end
+end

data/lib/dtwrb/statistics.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module DTW
+  module Statistics
+    # 1 / Phi^-1(3/4). Scaling the median absolute deviation by it makes the
+    # statistic a consistent estimator of sigma for normally distributed data.
+    NORMAL_CONSISTENCY_SCALE = 1.4826
+
+    module_function
+
+    def median(values)
+      return nil if values.empty?
+
+      sorted = values.sort
+      middle = sorted.length / 2
+      sorted.length.odd? ? sorted[middle].to_f : 0.5 * (sorted[middle - 1] + sorted[middle])
+    end
+
+    def mean(values)
+      return nil if values.empty?
+
+      values.sum(0.0) / values.length
+    end
+
+    def median_absolute_deviation(values)
+      return 0.0 if values.length < 2
+
+      center = median(values)
+      NORMAL_CONSISTENCY_SCALE * median(values.map { |value| (value - center).abs })
+    end
+
+    def standard_deviation(values)
+      return 0.0 if values.length < 2
+
+      center = mean(values)
+      Math.sqrt(values.sum(0.0) { |value| (value - center) ** 2 } / (values.length - 1))
+    end
+
+    ESTIMATORS = {
+      median: method(:median),
+      mean: method(:mean),
+      median_absolute_deviation: method(:median_absolute_deviation),
+      mad: method(:median_absolute_deviation),
+      standard_deviation: method(:standard_deviation)
+    }.freeze
+
+    def resolve(estimator) = Resolver.call(estimator, ESTIMATORS, "estimator")
+  end
+end

data/lib/dtwrb/version.rb

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

data/lib/dtwrb.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "dtwrb/version"
+require_relative "dtwrb/errors"
+require_relative "dtwrb/resolver"
+require_relative "dtwrb/sequence"
+require_relative "dtwrb/sample"
+require_relative "dtwrb/statistics"
+require_relative "dtwrb/metrics"
+require_relative "dtwrb/bands"
+require_relative "dtwrb/alignment"
+require_relative "dtwrb/aligner"
+require_relative "dtwrb/resampler"
+require_relative "dtwrb/medoid"
+require_relative "dtwrb/barycenter"
+require_relative "dtwrb/barycenter_averaging"
+
+module DTW
+  module_function
+
+  def align(sequence_a, sequence_b, metric: Metrics::DEFAULT, band: Bands::DEFAULT)
+    Aligner.new(metric: metric, band: band).align(sequence_a, sequence_b)
+  end
+
+  def distance(sequence_a, sequence_b, metric: Metrics::DEFAULT, band: Bands::DEFAULT)
+    Aligner.new(metric: metric, band: band).distance(sequence_a, sequence_b)
+  end
+
+  def medoid(sequences, metric: Metrics::DEFAULT, band: Bands::DEFAULT, sample_size: Medoid::DEFAULT_SAMPLE_SIZE)
+    Medoid.new(aligner: Aligner.new(metric: metric, band: band), sample_size: sample_size).call(sequences)
+  end
+
+  def barycenter(sequences, length: nil, metric: Metrics::DEFAULT, band: Bands::DEFAULT, **options)
+    averaging = BarycenterAveraging.new(aligner: Aligner.new(metric: metric, band: band), **options)
+    averaging.call(sequences, length: length)
+  end
+end

data/sig/dtwrb.rbs

@@ -0,0 +1,199 @@
+module DTW
+  VERSION: String
+
+  type frame = ::Array[::Numeric]
+  type frames = ::Array[frame]
+  type sequence = ::Array[untyped]
+  type cell = [::Integer, ::Integer]
+
+  interface _Metric
+    def call: (frame, frame) -> ::Float
+  end
+
+  interface _Band
+    def radius: (::Integer, ::Integer) -> ::Integer
+  end
+
+  interface _Estimator
+    def call: (::Array[::Numeric]) -> ::Numeric?
+  end
+
+  type metric = _Metric | ::Symbol
+  type band = _Band | ::Symbol | ::Numeric | nil
+  type estimator = _Estimator | ::Symbol
+
+  class Error < ::StandardError
+  end
+
+  class InvalidSequenceError < Error
+  end
+
+  class DimensionMismatchError < Error
+  end
+
+  class EmptyInputError < Error
+  end
+
+  class UnknownStrategyError < Error
+  end
+
+  def self.align: (sequence, sequence, ?metric: metric, ?band: band) -> Alignment
+  def self.distance: (sequence, sequence, ?metric: metric, ?band: band) -> ::Float
+  def self.medoid: (::Array[untyped], ?metric: metric, ?band: band, ?sample_size: ::Integer) -> sequence
+  def self.barycenter: (::Array[untyped], ?length: ::Integer?, ?metric: metric, ?band: band, **untyped) -> Barycenter
+
+  module Resolver
+    def self.call: (untyped, ::Hash[::Symbol, untyped], ::String) -> untyped
+  end
+
+  module Sequence
+    def self.usable?: (untyped) -> bool
+    def self.scalar?: (untyped) -> bool
+    def self.vectorize: (sequence) -> frames
+    def self.scalarize: (frames) -> ::Array[::Numeric]
+    def self.compact: (untyped) -> ::Array[sequence]
+    def self.dimension_of: (frames) -> ::Integer
+    def self.assert_uniform_dimension!: (::Array[frames]) -> ::Integer
+  end
+
+  class Sample
+    attr_reader sequences: ::Array[frames]
+    attr_reader dimension: ::Integer
+    attr_reader scalar: bool
+
+    def self.of: (::Array[untyped]) -> Sample
+    def self.new: (sequences: ::Array[frames], dimension: ::Integer, scalar: bool) -> Sample
+    def count: () -> ::Integer
+    def scalar?: () -> bool
+    def mean_length: () -> ::Integer
+    def with: (**untyped) -> Sample
+    def to_h: () -> ::Hash[::Symbol, untyped]
+  end
+
+  module Statistics
+    NORMAL_CONSISTENCY_SCALE: ::Float
+    ESTIMATORS: ::Hash[::Symbol, _Estimator]
+
+    def self.median: (::Array[::Numeric]) -> ::Float?
+    def self.mean: (::Array[::Numeric]) -> ::Float?
+    def self.median_absolute_deviation: (::Array[::Numeric]) -> ::Float
+    def self.standard_deviation: (::Array[::Numeric]) -> ::Float
+    def self.resolve: (estimator) -> _Estimator
+  end
+
+  module Metrics
+    REGISTRY: ::Hash[::Symbol, _Metric]
+    DEFAULT: _Metric
+
+    def self.assert_conformable!: (frame, frame) -> void
+    def self.resolve: (metric) -> _Metric
+
+    module Euclidean
+      def self.call: (frame, frame) -> ::Float
+    end
+
+    module Manhattan
+      def self.call: (frame, frame) -> ::Float
+    end
+
+    module Chebyshev
+      def self.call: (frame, frame) -> ::Float
+    end
+
+    module Cosine
+      def self.call: (frame, frame) -> ::Float
+    end
+  end
+
+  module Bands
+    DEFAULT_RATIO: ::Float
+    DEFAULT: SakoeChiba
+
+    def self.resolve: (band) -> _Band
+
+    class SakoeChiba
+      attr_reader ratio: ::Float
+
+      def self.new: (ratio: ::Numeric) -> SakoeChiba
+      def radius: (::Integer, ::Integer) -> ::Integer
+      def with: (**untyped) -> SakoeChiba
+      def to_h: () -> ::Hash[::Symbol, untyped]
+    end
+
+    module Unconstrained
+      def self.radius: (::Integer, ::Integer) -> ::Integer
+    end
+  end
+
+  class Alignment
+    attr_reader path: ::Array[cell]
+    attr_reader cost: ::Float
+
+    UNDEFINED: Alignment
+
+    def self.new: (path: ::Array[cell], cost: ::Float) -> Alignment
+    def steps: () -> ::Integer
+    def distance: () -> ::Float
+    def undefined?: () -> bool
+    def to_a: () -> ::Array[cell]
+    def with: (**untyped) -> Alignment
+    def to_h: () -> ::Hash[::Symbol, untyped]
+  end
+
+  class Aligner
+    attr_reader metric: _Metric
+    attr_reader band: _Band
+
+    def initialize: (?metric: metric, ?band: band) -> void
+    def align: (sequence, sequence) -> Alignment
+    def distance: (sequence, sequence) -> ::Float
+  end
+
+  module Resampler
+    def self.call: (frames, ::Integer) -> frames
+    def self.interpolate: (frame, frame, ::Float) -> frame
+  end
+
+  class Medoid
+    DEFAULT_SAMPLE_SIZE: ::Integer
+
+    attr_reader aligner: Aligner
+    attr_reader sample_size: ::Integer
+
+    def initialize: (?aligner: Aligner, ?sample_size: ::Integer) -> void
+    def call: (::Array[untyped]) -> sequence
+  end
+
+  class Barycenter
+    attr_reader center: ::Array[untyped]
+    attr_reader dispersion: ::Array[untyped]
+    attr_reader count: ::Integer
+
+    def self.new: (center: ::Array[untyped], dispersion: ::Array[untyped], count: ::Integer) -> Barycenter
+    def length: () -> ::Integer
+    def dimension: () -> ::Integer
+    def scalar?: () -> bool
+    def with: (**untyped) -> Barycenter
+    def to_h: () -> ::Hash[::Symbol, untyped]
+  end
+
+  class BarycenterAveraging
+    DEFAULT_ITERATIONS: ::Integer
+    DEFAULT_TOLERANCE: ::Float
+
+    attr_reader aligner: Aligner
+    attr_reader iterations: ::Integer
+    attr_reader tolerance: ::Float
+
+    def initialize: (
+      ?aligner: Aligner,
+      ?aggregator: estimator,
+      ?dispersion: estimator,
+      ?iterations: ::Integer,
+      ?tolerance: ::Numeric,
+      ?sample_size: ::Integer
+    ) -> void
+
+    def call: (::Array[untyped], ?length: ::Integer?) -> Barycenter
+  end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: dtwrb
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Den Patin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+- !ruby/object:Gem::Dependency
+  name: rbs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: Elastic alignment of numeric time series under Dynamic Time Warping with
+  a Sakoe-Chiba band constraint, DTW Barycenter Averaging (DBA) for computing a prototype
+  sequence from a set of variable-length observations, approximate medoid selection,
+  linear resampling and robust dispersion estimation via the median absolute deviation.
+  Pure Ruby, no dependencies. Pluggable local distance (Euclidean, Manhattan, Chebyshev,
+  cosine) and central-tendency estimator (median, arithmetic mean).
+email: hi@dpat.in
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/dtwrb.rb
+- lib/dtwrb/aligner.rb
+- lib/dtwrb/alignment.rb
+- lib/dtwrb/bands.rb
+- lib/dtwrb/barycenter.rb
+- lib/dtwrb/barycenter_averaging.rb
+- lib/dtwrb/errors.rb
+- lib/dtwrb/medoid.rb
+- lib/dtwrb/metrics.rb
+- lib/dtwrb/resampler.rb
+- lib/dtwrb/resolver.rb
+- lib/dtwrb/sample.rb
+- lib/dtwrb/sequence.rb
+- lib/dtwrb/statistics.rb
+- lib/dtwrb/version.rb
+- sig/dtwrb.rbs
+homepage: https://github.com/taiwancards/dtwrb
+licenses:
+- WTFPL
+metadata:
+  source_code_uri: https://github.com/taiwancards/dtwrb
+  changelog_uri: https://github.com/taiwancards/dtwrb/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/taiwancards/dtwrb/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Dynamic Time Warping, DBA barycenter averaging and robust dispersion for
+  numeric sequences
+test_files: []