R: Centroid calculation based on soft-DTW

sdtw_cent {dtwclust} | R Documentation

## 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.

[Package dtwclust version 5.5.7 Index]