tsclustFamily-class: Class definition for 'tsclustFamily'

tsclustFamily-classR Documentation

Class definition for tsclustFamily


Formal S4 class with a family of functions used in tsclust().


The custom implementations also handle parallelization.

Since the distance function makes use of proxy, it also supports any extra proxy::dist() parameters in ....

The prototype includes the cluster function for partitional methods, as well as a pass-through preproc function. The initializer expects a control from tsclust-controls. See more below.



The function to calculate the distance matrices.


The function to calculate centroids on each iteration.


The function used to assign a series to a cluster.


The function used to preprocess the data (relevant for stats::predict()).

Distance function

The family's dist() function works like proxy::dist() but supports parallelization and optimized symmetric calculations. If you like, you can use the function more or less directly, but provide a control argument when creating the family (see examples). However, bear in mind the following considerations.

  • The second argument is called centroids (inconsistent with proxy::dist()).

  • If control$distmat is not NULL, the function will try to subset it.

  • If control$symmetric is TRUE, centroids is NULL, and there is no argument pairwise that is TRUE, only half the distance matrix will be computed.

  • The function always returns a crossdist matrix.

Note that all distances implemented as part of dtwclust have custom proxy loops that use multi-threading independently of foreach, so see their respective documentation to see what optimizations apply to each one.

For distances not included in dtwclust, the computation can be in parallel using multi-processing with foreach::foreach(). If you install and load or attach (see base::library() or base::loadNamespace()) the bigmemory package, the function will take advantage of said package when all of the following conditions are met, reducing the overhead of data copying across processes:

  • control$symmetric is TRUE

  • centroids is NULL

  • pairwise is FALSE or NULL

  • The distance was registered in proxy::pr_DB with loop = TRUE

  • A parallel backend with more than 1 worker has been registered with foreach

This symmetric, parallel case makes chunks for parallel workers, but they are not perfectly balanced, so some workers might finish before the others.

Centroid function

The default partitional allcent() function is a closure with the implementations of the included centroids. The ones for DBA(), shape_extraction() and sdtw_cent() can use multi-process parallelization with foreach::foreach(). Its formal arguments are described in the Centroid Calculation section from tsclust().


This class is meant to group together the relevant functions, but they are not linked with each other automatically. In other words, neither dist nor allcent apply preproc. They essentially don't know of each other's existence.

See Also

dtw_basic(), dtw_lb(), gak(), lb_improved(), lb_keogh(), sbd(), sdtw().


## Not run: 
# See "GAK" documentation
fam <- new("tsclustFamily", dist = "gak")

# This is done with symmetric optimizations, regardless of control$symmetric
crossdist <- fam@dist(CharTraj, window.size = 18L)

# This is done without symmetric optimizations, regardless of control$symmetric
crossdist <- fam@dist(CharTraj, CharTraj, window.size = 18L)

# For non-dtwclust distances, symmetric optimizations only apply
# with an appropriate control AND a single data argument:
fam <- new("tsclustFamily", dist = "dtw",
           control = partitional_control(symmetric = TRUE))

# If you want the fuzzy family, use fuzzy = TRUE
ffam <- new("tsclustFamily", control = fuzzy_control(), fuzzy = TRUE)

## End(Not run)

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