# dtw_pairwise_distance¶

dtw_pairwise_distance(X: , y: = None, window: = None, itakura_max_slope: = None) [source]

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

By default, this takes a collection of $$n$$ time series $$X$$ and returns a matrix $$D$$ where $$D_{i,j}$$ is the DTW distance between the $$i^{th}$$ and the $$j^{th}$$ series in $$X$$. If $$X$$ is 2 dimensional, it is assumed to be a collection of univariate series with shape (n_cases, n_timepoints). If it is 3 dimensional, it is assumed to be shape (n_cases, n_channels, n_timepoints).

This function has an optional argument, $$y$$, to allow calculation of the distance matrix between $$X$$ and one or more series stored in $$y$$. If $$y$$ is 1 dimensional, we assume it is a single univariate series and the distance matrix returned is shape (n_cases,1). If it is 2D, we assume it is a collection of univariate series with shape (m_cases, m_timepoints) and the distance (n_cases,m_cases). If it is 3 dimensional, it is assumed to be shape (m_cases, m_channels, m_timepoints).

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 dtw pairwise distance between the instances of X is calculated.

windowfloat or None, default=None

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

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

DTW pairwise matrix between the instances of X of shape (n_cases, n_cases) or between X and y of shape (n_cases, n_cases).

Raises:
ValueError

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

Examples

>>> import numpy as np
>>> from aeon.distances import dtw_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]]])
>>> dtw_pairwise_distance(X)
array([[  0.,  26., 108.],
[ 26.,   0.,  26.],
[108.,  26.,   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]]])
>>> dtw_pairwise_distance(X, y)
array([[300., 507., 768.],
[147., 300., 507.],
[ 48., 147., 300.]])

>>> X = np.array([[[1, 2, 3]],[[4, 5, 6]], [[7, 8, 9]]])
>>> y_univariate = np.array([11, 12, 13])
>>> dtw_pairwise_distance(X, y_univariate)
array([[300.],
[147.],
[ 48.]])

>>> # 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])]
>>> dtw_pairwise_distance(X)
array([[  0.,  42., 292.],
[ 42.,   0.,  83.],
[292.,  83.,   0.]])