twe_distance

twe_distance(x: ndarray, y: ndarray, window: float | None = None, nu: float = 0.001, lmbda: float = 1.0, itakura_max_slope: float | None = None) → float

Compute the TWE distance between two time series.

Proposed in [1], the Time Warp Edit (TWE) distance is a distance method for time series matching with time ‘elasticity’. For two series, possibly of unequal length, \(\mathbf{x}=\{x_1,x_2,\ldots,x_n\}\) and \(\mathbf{y}=\{y_1,y_2, \ldots,y_m\}\) TWE works by iterating over series lengths $n$ and $m$ to find the cost matrix $D$ as follows.

\[\begin{split}match &= D_{i-1,j-1}+ d({x_{i},y_{j}})+d({x_{i-1},y_{j-1}}) +2\nu(|i-j|) \\ delete &= D_{i-1,j}+d(x_{i},x_{i-1}) + \lambda+\nu \\ insert &= D_{i,j-1}+d(y_{j},y_{j-1}) + \lambda+\nu \\ D_{i,j} &= min(match,insert, delete)\end{split}\]

Where \(\nu\) and \(\lambda\) are parameters and $d$ is a pointwise distance function. The TWE distance is then the final value, $D(n,m)$. TWE combines warping and edit distance. Warping is controlled by the stiffness parameter \(\nu\) (called nu). Stiffness enforces a multiplicative penalty on the distance between matched points in a way that is similar to weighted DTW, where $nu = 0$ gives no warping penalty. The edit penalty, \(\lambda\) (called lmbda), is applied to both the delete and insert operations to penalise moving off the diagonal.

TWE is a metric.

Parameters:

xnp.ndarray

First time series, either univariate, shape (n_timepoints,), or multivariate, shape (n_channels, n_timepoints).

ynp.ndarray

Second time series, either univariate, shape (n_timepoints,), or multivariate, shape (n_channels, n_timepoints).

windowint, default=None

Window size. If None, the window size is set to the length of the shortest time series.

nufloat, default=0.001

A non-negative constant called the stiffness, which penalises moves off the diagonal Must be > 0.

lmbdafloat, default=1.0

A constant penalty for insert or delete operations. Must be >= 1.0.

itakura_max_slopefloat, default=None

Maximum slope as a proportion of the number of time points used to create Itakura parallelogram on the bounding matrix. Must be between 0. and 1.

Returns:

float

TWE distance between x and y.

Raises:

ValueError

If x and y are not 1D or 2D arrays.

References

[1]

Marteau, P.; F. (2009). Time Warp Edit Distance with Stiffness Adjustment

for Time Series Matching. IEEE Transactions on Pattern Analysis and Machine Intelligence. 31 (2): 306–318.

Examples

>>> import numpy as np
>>> from aeon.distances import twe_distance
>>> x = np.array([[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]])
>>> y = np.array([[11, 12, 13, 14, 15, 16, 17, 18, 19, 20]])
>>> twe_distance(x, y)
46.017999999999994