dtaidistance.dtw_ndim

Dynamic Time Warping (DTW) for N-dimensional series.

All the functionality in this subpackage is also available in the dtw subpackage with argument use_ndim=True.

author:

Wannes Meert

copyright:

Copyright 2017-2024 KU Leuven, DTAI Research Group.

license:

Apache License, Version 2.0, see LICENSE for details.

dtaidistance.dtw_ndim.distance(s1, s2, window=None, max_dist=None, max_step=None, max_length_diff=None, penalty=None, psi=None, use_c=False, use_pruning=False, only_ub=False, inner_dist='squared euclidean')

(Dependent) Dynamic Time Warping using multidimensional sequences.

Assumes the first dimension to be the sequence item index, and the second dimension to be the series index (thus timestep).

Example:

s1 = np.array([[0, 0],
               [0, 1],
               [2, 1],
               [0, 1],
               [0, 0]], dtype=np.double)
s2 = np.array([[0, 0],
               [2, 1],
               [0, 1],
               [0, .5],
               [0, 0]], dtype=np.double)
d = distance(s1, s2)

See dtaidistance.dtw.distance() for parameters.

This method returns the dependent DTW (DTW_D) [1] distance between two n-dimensional sequences. If you want to compute the independent DTW (DTW_I) distance, use the 1-dimensional version:

dtw_i = 0
for dim in range(ndim):
    dtw_i += dtw.distance(s1[:,dim], dtw.distance(s2[:,dim])

Note: If you are using the C-optimized code, the above snippet will trigger a copy operation to guarantee the arrays to be C-ordered and will thus create time and memory overhead. This can be avoided by storing the dimensions as separate arrays or by flipping the array dimensions and use dtw.distance(s1[dim,:], dtw.distance(s2[dim,:]).

[1] M. Shokoohi-Yekta, B. Hu, H. Jin, J. Wang, and E. Keogh. Generalizing dtw to the multi-dimensional case requires an adaptive approach. Data Mining and Knowledge Discovery, 31:1–31, 2016.

dtaidistance.dtw_ndim.distance_fast(s1, s2, window=None, max_dist=None, max_step=None, max_length_diff=None, penalty=None, psi=None, use_pruning=False, only_ub=False, inner_dist='squared euclidean')

Fast C version of distance().

Note: the series are expected to be arrays of the type double. Thus numpy.array([[1,1],[2,2],[3,3]], dtype=numpy.double)

dtaidistance.dtw_ndim.distance_matrix(s, ndim=None, max_dist=None, use_pruning=False, max_length_diff=None, window=None, max_step=None, penalty=None, psi=None, block=None, compact=False, parallel=False, use_c=False, use_mp=False, show_progress=False, only_triu=False, inner_dist='squared euclidean')

Distance matrix for all n-dimensional sequences in s.

This method returns the dependent DTW (DTW_D) [1] distance between two n-dimensional sequences. If you want to compute the independent DTW (DTW_I) distance, use the 1-dimensional version and sum the distance matrices:

dtw_i = dtw.distance_matrix(series_sep_dim[0])
for dim in range(1, ndim):
    dtw_i += dtw.distance_matrix(series_sep_dim(dim)

Where series_sep_dim is a datastructure that returns a list of the sequences that represents the i-th dimension of each sequence in s.

Parameters:
  • s – Iterable of series

  • window – see distance()

  • max_dist – see distance()

  • max_step – see distance()

  • max_length_diff – see distance()

  • penalty – see distance()

  • psi – see distance()

  • block – Only compute block in matrix. Expects tuple with begin and end, e.g. ((0,10),(20,25)) will only compare rows 0:10 with rows 20:25.

  • compact – Return the distance matrix as an array representing the upper triangular matrix.

  • parallel – Use parallel operations

  • use_c – Use c compiled Python functions

  • use_mp – Use Multiprocessing for parallel operations (not OpenMP)

  • show_progress – Show progress using the tqdm library. This is only supported for the pure Python version (thus not the C-based implementations).

  • only_triu – Only fill the upper triangle

Returns:

The distance matrix or the condensed distance matrix if the compact argument is true

[1] M. Shokoohi-Yekta, B. Hu, H. Jin, J. Wang, and E. Keogh. Generalizing dtw to the multi-dimensional case requires an adaptive approach. Data Mining and Knowledge Discovery, 31:1–31, 2016.

dtaidistance.dtw_ndim.distance_matrix_fast(s, ndim=None, max_dist=None, max_length_diff=None, window=None, max_step=None, penalty=None, psi=None, block=None, compact=False, parallel=True, only_triu=False, inner_dist='squared euclidean')

Fast C version of distance_matrix().

dtaidistance.dtw_ndim.ub_euclidean(s1, s2, inner_dist='squared euclidean')

Euclidean (dependent) distance between two n-dimensional sequences. Supports different lengths.

If the two series differ in length, compare the last element of the shortest series to the remaining elements in the longer series.

Parameters:
  • s1 – Sequence of numbers, 1st dimension is sequence, 2nd dimension is n-dimensional value vector.

  • s2 – Sequence of numbers, 1st dimension is sequence, 2nd dimension is n-dimensional value vector.

Returns:

Euclidean distance

dtaidistance.dtw_ndim.warping_path(from_s, to_s, **kwargs)

Compute warping path between two sequences.

dtaidistance.dtw_ndim.warping_paths(*args, **kwargs)

Dynamic Time Warping (keep full matrix) using multidimensional sequences.

See dtaidistance.dtw.warping_paths() for parameters.

dtaidistance.dtw_ndim.warping_paths_fast(*args, **kwargs)

Dynamic Time Warping (keep full matrix) using multidimensional sequences.

See dtaidistance.dtw.warping_paths() for parameters.