cdist_soft_dtw

tslearn.metrics.cdist_soft_dtw(dataset1, dataset2=None, gamma=1.0, global_constraint=None, sakoe_chiba_radius=None, itakura_max_slope=None, n_jobs=None, verbose=0, be=None)

Compute cross-similarity matrix using Soft-DTW metric.

Soft-DTW was originally presented in [1] and is discussed in more details in our user-guide page on DTW and its variants.

Soft-DTW is computed as:

\[\text{soft-DTW}_{\gamma}(X, Y) = \min_{\pi}{}^\gamma \sum_{(i, j) \in \pi} \|X_i, Y_j\|^2\]

where \(\min^\gamma\) is the soft-min operator of parameter \(\gamma\).

In the limit case \(\gamma = 0\), \(\min^\gamma\) reduces to a hard-min operator and soft-DTW is defined as the square of the DTW similarity measure.

Parameters:

dataset1array-like, shape=(n_ts1, sz1, d) or (n_ts1, sz1) or (sz1,)

A dataset of time series. If shape is (n_ts1, sz1), the dataset is composed of univariate time series. If shape is (sz1,), the dataset is composed of a unique univariate time series.

dataset2None or array-like, shape=(n_ts2, sz2, d) or (n_ts2, sz2) or (sz2,) (default: None)

Another dataset of time series. If None, self-similarity of dataset1 is returned. If shape is (n_ts2, sz2), the dataset is composed of univariate time series. If shape is (sz2,), the dataset is composed of a unique univariate time series.

gammafloat (default 1.)

Gamma parameter for Soft-DTW.

global_constraint{“itakura”, “sakoe_chiba”} or None (default: None)

Global constraint to restrict admissible paths for DTW.

sakoe_chiba_radiusint or None (default: None)

Radius to be used for Sakoe-Chiba band global constraint. The Sakoe-Chiba radius corresponds to the parameter \(\delta\) mentioned in [1], it controls how far in time we can go in order to match a given point from one time series to a point in another time series. If None and global_constraint is set to “sakoe_chiba”, a radius of 1 is used. If both sakoe_chiba_radius and itakura_max_slope are set, global_constraint is used to infer which constraint to use among the two. In this case, if global_constraint corresponds to no global constraint, a RuntimeWarning is raised and no global constraint is used.

itakura_max_slopefloat or None (default: None)

Maximum slope for the Itakura parallelogram constraint. If None and global_constraint is set to “itakura”, a maximum slope of 2. is used. If both sakoe_chiba_radius and itakura_max_slope are set, global_constraint is used to infer which constraint to use among the two. In this case, if global_constraint corresponds to no global constraint, a RuntimeWarning is raised and no global constraint is used.

n_jobsint or None, optional (default=None)

The number of jobs to run in parallel. None means 1 unless in a joblib.parallel_backend context. -1 means using all processors. See scikit-learns’ Glossary for more details.

verboseint, optional (default=0)

The verbosity level: if non zero, progress messages are printed. Above 50, the output is sent to stdout. The frequency of the messages increases with the verbosity level. If it more than 10, all iterations are reported. Glossary for more details.

beBackend object or string or None (default: None)

Backend. If be is an instance of the class NumPyBackend or the string “numpy”, the NumPy backend is used. If be is an instance of the class PyTorchBackend or the string “pytorch”, the PyTorch backend is used. If be is None, the backend is determined by the input arrays. See our dedicated user-guide page for more information.

Returns:

array-like, shape=(n_ts1, n_ts2)

Cross-similarity matrix.

See also

soft_dtw

Computes the similarity score for Soft-DTW

soft_dtw_normalized

Computes the normalized similarity score for Soft-DTW

soft_dtw_alignment

Computes both the similarity score and the alignment matrix and for Soft-DTW

cdist_soft_dtw_normalized

Cross similarity matrix between time series datasets using a normalized version of Soft-DTW

References

[1] (1,2)

M. Cuturi, M. Blondel “Soft-DTW: a Differentiable Loss Function for Time-Series,” ICML 2017.

Examples

>>> cdist_soft_dtw([[1, 2, 2, 3], [1., 2., 3., 4.]], gamma=.01)
array([[-0.01098612,  1.        ],
       [ 1.        ,  0.        ]])
>>> cdist_soft_dtw([[1, 2, 2, 3], [1., 2., 3., 4.]],
...                [[1, 2, 2, 3], [1., 2., 3., 4.]], gamma=.01)
array([[-0.01098612,  1.        ],
       [ 1.        ,  0.        ]])

The PyTorch backend can be used to compute gradients:

>>> import torch
>>> dataset1 = torch.tensor([[[1.0], [2.0], [3.0]], [[1.0], [2.0], [3.0]]], requires_grad=True)
>>> dataset2 = torch.tensor([[[3.0], [4.0], [-3.0]], [[3.0], [4.0], [-3.0]]])
>>> sim_mat = cdist_soft_dtw(dataset1, dataset2, gamma=1.0)
>>> print(sim_mat)
tensor([[41.1876, 41.1876],
        [41.1876, 41.1876]], dtype=torch.float64, grad_fn=<ViewBackward0>)
>>> sim = sim_mat[0, 0]
>>> sim.backward()
>>> print(dataset1.grad)
tensor([[[-4.0001],
         [-2.2852],
         [10.1643]],

        [[ 0.0000],
         [ 0.0000],
         [ 0.0000]]])