ferro-ta/docs/guides/dtw.md

Dynamic Time Warping

ferro-ta ships three DTW entry points. Pick the one that matches your workload — the distance-only path is measurably faster than the one that reconstructs the warping path, and BATCH_DTW parallelises over rows.

Quick reference

Function	Returns	When to use
DTW_DISTANCE(a, b, window=None)	float	You only need the distance. Fastest.
DTW(a, b, window=None)	(float, ndarray[N, 2])	You need the alignment path for plotting or downstream analysis.
BATCH_DTW(matrix, reference, window=None)	ndarray[N]	You have N candidate series and one reference; uses rayon.

Distance convention

ferro-ta's DTW uses squared-Euclidean local cost accumulated along the optimal path, with a single sqrt() applied at the end. This matches dtaidistance.dtw.distance() to within floating-point tolerance (parity tests assert numerical agreement, not bitwise identity). Example:

>>> import ferro_ta as fta
>>> fta.DTW_DISTANCE([0.0, 1.0, 2.0], [1.0, 2.0, 3.0])
1.4142135623730951  # == sqrt(2), same as dtaidistance

If you are migrating from a library that uses absolute-difference local cost without the final sqrt (e.g. fastdtw's default), your numbers will not line up. That is a choice ferro-ta made for parity with the scientific-Python ecosystem.

Window constraint (Sakoe-Chiba band)

Passing window=w constrains the DP to cells where |i - j| < w. This turns the O(n·m) cost into O(n·w), which is typically a 5–20× speedup for realistic w. A narrower band can only increase the distance, so window= is safe to use whenever your series are roughly aligned.

# Unconstrained
fta.DTW_DISTANCE(a, b)

# Constrained: warping may shift up to 5 positions
fta.DTW_DISTANCE(a, b, window=5)

Batch usage

BATCH_DTW compares each row of a 2-D matrix against one reference series, in parallel:

import numpy as np
import ferro_ta as fta

reference = np.random.random(500)
candidates = np.random.random((1000, 500))

distances = fta.BATCH_DTW(candidates, reference, window=20)
nearest = int(np.argmin(distances))

Parallelism is via rayon; no thread-pool configuration is needed on the Python side. For the sequence lengths ferro-ta targets (thousands of bars, hundreds to low thousands of candidates), batch-parallel classic DTW beats FastDTW-style approximations.

Edge cases

• Empty input: raises FerroTAInputError.
• NaN in input: propagates to the output (matches IEEE 754). Call ferro_ta.core.exceptions.check_finite() first if you want to fail loudly instead.
• Different-length series: fully supported. The path array length is bounded by max(n, m) <= len(path) <= n + m - 1.

See also

• tests/unit/indicators/test_statistic.py — parity tests against dtaidistance.