sdtw_cent: Centroid calculation based on soft-DTW

In dtwclust: Time Series Clustering Along with Optimizations for the Dynamic Time Warping Distance

Centroid calculation based on soft-DTW

Description

Soft-DTW centroid function as proposed in Cuturi and Blondel (2017).

Usage

sdtw_cent(
  series,
  centroid = NULL,
  gamma = 0.01,
  weights = rep(1, length(series)),
  ...,
  error.check = TRUE,
  opts = list(algorithm = "NLOPT_LD_LBFGS", maxeval = 20L)
)

Arguments

series	A matrix or data frame where each row is a time series, or a list where each element is a time series. Multivariate series should be provided as a list of matrices where time spans the rows and the variables span the columns of each matrix.
centroid	Optionally, a time series to use as reference. Defaults to a random series of series if NULL. For multivariate series, this should be a matrix with the same characteristics as the matrices in series.
gamma	Positive regularization parameter, with lower values resulting in less smoothing.
weights	A vector of weights for each element of series.
...	Further arguments for the optimization backend (except opts for nloptr, control for optim, and ... for both).
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.
opts	List of options to pass to nloptr or stats::optim()'s control. The defaults in the function's formals are for nloptr, but the value will be adjusted for optim if needed.

Details

This function can delegate the optimization to the nloptr package. For that to happen, you must load it with either base::library() or base::loadNamespace(). If the aforementioned is not fulfilled, the function will delegate to stats::optim().

Value

The resulting centroid, with the optimization results as attributes (except for the returned centroid).

Parallel Computing

Please note that running tasks in parallel does not guarantee faster computations. The overhead introduced is sometimes too large, and it's better to run tasks sequentially.

This function uses the RcppParallel package for parallelization. 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 this function 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")).

For unknown reasons, this function has returned different results (in the order of 1e-6) when using multi-threading in x64 Windows installations in comparison to other environments (using nloptr v1.0.4). Consider limiting the number of threads if you run into reproducibility problems.

References

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.