R: Class definition for 'tsclustFamily'

tsclustFamily-class {dtwclust} | R Documentation

## Class definition for `tsclustFamily`

### Description

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

### Details

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.

### Slots

`dist`

  The function to calculate the distance matrices.

`allcent`

  The function to calculate centroids on each iteration.

`cluster`

  The function used to assign a series to a cluster.

`preproc`

  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.

  - If the distance was registered in proxy::pr_DB with `loop = TRUE`, the bigmemory package is available, and more than one parallel worker is detected, the computation will be in parallel (using multi-processing with `foreach::foreach()`), otherwise it will be sequential with `proxy::dist()`.

- 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 symmetric, parallel case mentioned above makes chunks for parallel workers, but they are not perfectly balanced, so some workers might finish before the others. You must load or attach the bigmemory package for this to take place; see `base::library()` or `base::loadNamespace()`.

### 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()`.

### Note

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()`.

### Examples

    ## Not run:
    data(uciCT)
    # 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))
    fam@dist(CharTraj[1L:5L])

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

    ## End(Not run)

[Package dtwclust version 5.5.7 Index]