twe_pairwise_distance

twe_pairwise_distance(X: ndarray | list[ndarray], y: ndarray | list[ndarray] | None = None, window: float | None = None, nu: float = 0.001, lmbda: float = 1.0, itakura_max_slope: float | None = None) → ndarray

Compute the TWE pairwise distance between a set of time series.

Parameters:

Xnp.ndarray or List of np.ndarray

A collection of time series instances of shape (n_cases, n_timepoints) or (n_cases, n_channels, n_timepoints).

ynp.ndarray or List of np.ndarray or None, default=None

A single series or a collection of time series of shape (m_timepoints,) or (m_cases, m_timepoints) or (m_cases, m_channels, m_timepoints). If None, then the twe pairwise distance between the instances of X is calculated.

windowfloat, default=None

The window to use for the bounding matrix. If None, no bounding matrix is used.

nufloat, default=0.001

A non-negative constant which characterizes the stiffness of the elastic twe method. Must be > 0.

lmbdafloat, default=1.0

A constant penalty that punishes the editing efforts. 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:

np.ndarray (n_cases, n_cases)

twe pairwise matrix between the instances of X.

Raises:

ValueError

If X is not 2D or 3D array when only passing X. If X and y are not 1D, 2D or 3D arrays when passing both X and y.

Examples

>>> import numpy as np
>>> from aeon.distances import twe_pairwise_distance
>>> # Distance between each time series in a collection of time series
>>> X = np.array([[[1, 2, 3]],[[4, 5, 6]], [[7, 8, 9]]])
>>> twe_pairwise_distance(X)
array([[ 0.   , 11.004, 14.004],
       [11.004,  0.   , 11.004],
       [14.004, 11.004,  0.   ]])

>>> # Distance between two collections of time series
>>> X = np.array([[[1, 2, 3]],[[4, 5, 6]], [[7, 8, 9]]])
>>> y = np.array([[[11, 12, 13]],[[14, 15, 16]], [[17, 18, 19]]])
>>> twe_pairwise_distance(X, y)
array([[18.004, 21.004, 24.004],
       [15.004, 18.004, 21.004],
       [12.004, 15.004, 18.004]])

>>> X = np.array([[[1, 2, 3]],[[4, 5, 6]], [[7, 8, 9]]])
>>> y_univariate = np.array([11, 12, 13])
>>> twe_pairwise_distance(X, y_univariate)
array([[18.004],
       [15.004],
       [12.004]])

>>> # Distance between each TS in a collection of unequal-length time series
>>> X = [np.array([1, 2, 3]), np.array([4, 5, 6, 7]), np.array([8, 9, 10, 11, 12])]
>>> twe_pairwise_distance(X)
array([[ 0.   , 13.005, 19.006],
       [13.005,  0.   , 18.007],
       [19.006, 18.007,  0.   ]])