adtw_distance

adtw_distance(x: ndarray, y: ndarray, window: float | None = None, itakura_max_slope: float | None = None, warp_penalty: float = 1.0) → float

Compute the ADTW distance between two time series.

Amercing Dynamic Time Warping (ADTW) [1] is a variant of DTW that uses a explicit warping penalty to encourage or discourage warping. The warping penalty is a constant value that is added to the cost of warping. A high value will encourage the algorithm to warp less and if the value is low warping is more likely.

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).

windowfloat or None, default=None

The window to use for the bounding matrix. If None, no bounding matrix is used. window is a percentage deviation, so if window = 0.1 then 10% of the series length is the max warping allowed.

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.0 and 1.0

warp_penalty: float, default=1.0

Penalty for warping. A high value will mean less warping.

Returns:

float

ADTW distance between x and y, minimum value 0.

Raises:

ValueError

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

References

[1]

Matthieu Herrmann, Geoffrey I. Webb: Amercing: An intuitive and effective

constraint for dynamic time warping, Pattern Recognition, Volume 137, 2023.

Examples

>>> import numpy as np
>>> from aeon.distances import adtw_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])
>>> adtw_distance(x, y) # 1D series
783.0
>>> x = np.array([[1, 2, 3, 4, 5], [6, 7, 8, 9, 10], [0, 1, 0, 2, 0]])
>>> y = np.array([[11, 12, 13, 14],[7, 8, 9, 20],[1, 3, 4, 5]] )
>>> adtw_distance(x, y) # 2D series with 3 channels, unequal length
565.0