sdtw: Soft-DTW distance

View source: R/DISTANCES-sdtw.R

sdtwR Documentation

Soft-DTW distance


Soft-DTW distance measure as proposed in Cuturi and Blondel (2017).


sdtw(x, y, gamma = 0.01, ..., error.check = TRUE)


x, y

Time series. Multivariate series must have time spanning the rows and variables spanning the columns.


Positive regularization parameter, with lower values resulting in less smoothing.


Currently ignored.


Logical indicating whether the function should try to detect inconsistencies and give more informative errors messages. Also used internally to avoid repeating checks.


Unlike other distances, soft-DTW can return negative values, and sdtw(x, x) is not always equal to zero. Like DTW, soft-DTW does not fulfill the triangle inequality, but it is always symmetric.


The Soft DTW distance.

Proxy version

The version registered with dist is custom (loop = FALSE in pr_DB). The custom function handles multi-threaded parallelization directly (with RcppParallel). It uses all available threads by default (see RcppParallel::defaultNumThreads()), but this can be changed by the user with RcppParallel::setThreadOptions().

An exception to the above is when it is called within a foreach parallel loop made by dtwclust. If the parallel workers do not have the number of threads explicitly specified, this function will default to 1 thread per worker. See the parallelization vignette for more information (browseVignettes("dtwclust")).

It also includes symmetric optimizations to calculate only half a distance matrix when appropriate—only one list of series should be provided in x. If you want to avoid this optimization, call dist by giving the same list of series in both x and y.


Cuturi, M., & Blondel, M. (2017). Soft-DTW: a Differentiable Loss Function for Time-Series. arXiv preprint arXiv:1703.01541.

dtwclust documentation built on March 7, 2023, 7:49 p.m.