Cyclical time-Constrained Clustering

Function cyclo.hclust performs cyclical-time-constrained agglomerative clustering from a multivariate dissimilarity matrix. The function piggy-backs largely on function constr.hclust by P. Legendre and G. Guénard, from package adespatial, the user is strongly advised to check the corresponding documentation as well as documentation from hclust, the more general R function for hierarchical clustering.

cyclo.hclust(
  d,
  method = "ward.D2",
  time,
  cycle.duration,
  cyclic.link.tolerance = cycle.duration/10
)

Arguments

d: a class dist dissimilarity matrix.
method: the agglomeration method to be used (parsed to constr.hclust).
time: a vector indicating the linear time corresponding to objects in d.
cycle.duration: a number indicating the duration of one cycle. Must be in the same units as time.
cyclic.link.tolerance: a number indicating how far in cyclic time a link can reach (see details). Defaults to cycle.duration/10.

Value

cyclo.hclust returns an object of class cyclo.hclust. It is a modified version of the output of function constr.hclust containing additional information on linear and cyclical time used in the other functions of package CycloClust.

Details

Function cyclo.hclust uses the parameters time, cycle.duration, and cyclic.link.tolerance to compute a list of edges connecting observation along linear time AND cyclical time (for instance with a multi-annual time-series, connecting January of year 1 to January of year 2 etc.). This list of edges is then transferred to function constr.hclust as its link parameter. All the clustering is carried by constr.hclust and users are strongly advised to check the associated documentation for clustering methods.

The links generated by cyclo.hclust can be divided in two categories. First, linear-time links simply link points contiguous in time (as in classic chronological clustering). Second, cyclical-time links are established: For each point, the function establishes a link with the point closest in cyclical time (within the margin of cyclic.link.tolerance) on the next cycle. For irregular sampling or in case of missing data, this implies that some cyclical-time links may not be established. This may be alleviated by increasing cyclic.link.tolerance but this implies a deformation of the cyclical constraint.

References

Guénard, G. and P. Legendre. 2022. Hierarchical clustering with contiguity constraint in R. Journal of Statistical Software 103(7): 1-26 (https://doi.org/10.18637/jss.v103.i07)

Author

Nicolas Djeghri, UBO

Examples