sdtw: Soft-DTW distance

View source: R/DISTANCES-sdtw.R

sdtwR Documentation

Soft-DTW distance

Description

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

Usage

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

Arguments

x, y

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

gamma

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

...

Currently ignored.

error.check

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

Details

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.

Value

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.

References

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


dtwclust documentation built on Sept. 24, 2022, 5:05 p.m.