tslearn.metrics.cdist_soft_dtw_normalized¶
- tslearn.metrics.cdist_soft_dtw_normalized(dataset1, dataset2=None, gamma=1.0, be=None, compute_with_backend=False)[source]¶
Compute cross-similarity matrix using a normalized version of the 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.
This normalized version is defined as:
\[\text{norm-soft-DTW}_{\gamma}(X, Y) = \text{soft-DTW}_{\gamma}(X, Y) - \frac{1}{2} \left(\text{soft-DTW}_{\gamma}(X, X) + \text{soft-DTW}_{\gamma}(Y, Y)\right)\]and ensures that all returned values are positive and that \(\text{norm-soft-DTW}_{\gamma}(X, X) = 0\).
- 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.
- beBackend object or string or 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.
- compute_with_backendbool, default=False
This parameter has no influence when the NumPy backend is used. When a backend different from NumPy is used (cf parameter be): If True, the computation is done with the corresponding backend. If False, a conversion to the NumPy backend can be used to accelerate the computation.
- Returns:
- array-like, shape=(n_ts1, n_ts2)
Cross-similarity matrix.
See also
soft_dtw
Compute Soft-DTW
cdist_soft_dtw
Cross similarity matrix between time series datasets using the unnormalized version of Soft-DTW
References
[1]M. Cuturi, M. Blondel “Soft-DTW: a Differentiable Loss Function for Time-Series,” ICML 2017.
Examples
>>> time_series = np.random.randn(10, 15, 1) >>> np.alltrue(cdist_soft_dtw_normalized(time_series) >= 0.) True >>> time_series2 = np.random.randn(4, 15, 1) >>> np.alltrue(cdist_soft_dtw_normalized(time_series, time_series2) >= 0.) True
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_normalized(dataset1, dataset2, gamma=1.0, be="pytorch", compute_with_backend=True) >>> print(sim_mat) tensor([[42.0586, 42.0586], [42.0586, 42.0586]], grad_fn=<AddBackward0>) >>> sim = sim_mat[0, 0] >>> sim.backward() >>> print(dataset1.grad) tensor([[[-3.5249], [-2.2852], [ 9.6891]], [[ 0.0000], [ 0.0000], [ 0.0000]]])