This is an implementation of the k-means alignment algorithm originally described in Sangalli et al. (2010), with improvements as proposed in Vantini (2012).
kma(
x,
y = NULL,
n_clusters = 1L,
seeds = NULL,
seeding_strategy = c("kmeans++", "exhaustive-kmeans++", "exhaustive", "hclust"),
warping_class = c("affine", "dilation", "none", "shift", "srsf"),
centroid_type = "mean",
metric = c("l2", "pearson"),
cluster_on_phase = FALSE,
use_verbose = TRUE,
warping_options = c(0.15, 0.15),
maximum_number_of_iterations = 100L,
number_of_threads = 1L,
parallel_method = 0L,
distance_relative_tolerance = 0.001,
use_fence = FALSE,
check_total_dissimilarity = TRUE,
compute_overall_center = FALSE,
add_silhouettes = TRUE,
expand_domain = TRUE
)An object of class caps.
A numeric vector of length \(M\) or a numeric matrix of shape
\(N \times M\) or an object of class funData::funData. If a numeric
vector or matrix, it specifies the grid(s) of size \(M\) on which each of
the \(N\) curves have been observed. If an object of class
funData::funData, it contains the whole functional data set and the y
argument is not used.
Either a numeric matrix of shape \(N \times M\) or a numeric array
of shape \(N \times L \times M\) or an object of class fda::fd. If a
numeric matrix or array, it specifies the \(N\)-sample of
\(L\)-dimensional curves observed on grids of size \(M\). If an object
of class fda::fd, it contains all the necessary information about the
functional data set to be able to evaluate it on user-defined grids.
An integer value specifying the number of clusters.
Defaults to 1L.
An integer value or vector specifying the indices of the initial
centroids. If an integer vector, it is interpreted as the indices of the
intial centroids and should therefore be of length n_clusters. If an
integer value, it is interpreted as the index of the first initial centroid
and subsequent centroids are chosen according to the k-means++ strategy. It
can be NULL in which case the argument seeding_strategy is used to
automatically provide suitable indices. Defaults to NULL.
A character string specifying the strategy for
choosing the initial centroids in case the argument seeds is set to
NULL. Choices are
"kmeans++",
"exhaustive-kmeans++" which performs an exhaustive search over the choice
of the first centroid, "exhaustive" which tries on all combinations of
initial centroids or "hclust" which first performs hierarchical
clustering using Ward's linkage criterion to identify initial centroids.
Defaults to "kmeans++", which is the fastest strategy.
A string specifying the warping class Choices are
"affine", "dilation", "none", "shift" or "srsf". Defaults to
"affine". The SRSF class is the only class which is boundary-preserving.
A string specifying the type of centroid to compute.
Choices are "mean", "medoid", "lowess" or "poly". Defaults to
"mean". If LOWESS appproximation is chosen, the user can append an
integer between 0 and 100 as in "lowess20". This number will be used as
the smoother span. This gives the proportion of points in the plot which
influence the smooth at each value. Larger values give more smoothness. The
default value is 10%. If polynomial approximation is chosen, the user can
append an positive integer as in "poly3". This number will be used as the
degree of the polynomial model. The default value is 4L.
A string specifying the metric used to compare curves. Choices
are "l2" or "pearson". Defaults to "l2". Used only when
warping_class != "srsf". For the boundary-preserving warping class, the
L2 distance between the SRSFs of the original curves is used.
A boolean specifying whether clustering should be
based on phase variation or amplitude variation. Defaults to FALSE which
implies amplitude variation.
A boolean specifying whether the algorithm should output
details of the steps to the console. Defaults to TRUE.
A numeric vector supplied as a helper to the chosen
warping_class to decide on warping parameter bounds. This is used only
when warping_class != "srsf".
An integer specifying the maximum number
of iterations before the algorithm stops if no other convergence criterion
was met. Defaults to 100L.
An integer value specifying the number of threads
used for parallelization. Defaults to 1L. This is used only when
warping_class != "srsf".
An integer value specifying the type of desired
parallelization for template computation, If 0L, templates are computed
in parallel. If 1L, parallelization occurs within a single template
computation (only for the medoid method as of now). Defaults to 0L. This
is used only when warping_class != "srsf".
A numeric value specifying a relative
tolerance on the distance update between two iterations. If all
observations have not sufficiently improved in that sense, the algorithm
stops. Defaults to 1e-3. This is used only when warping_class != "srsf".
A boolean specifying whether the fence algorithm should be
used to robustify the algorithm against outliers. Defaults to FALSE. This
is used only when warping_class != "srsf".
A boolean specifying whether an additional
stopping criterion based on improvement of the total dissimilarity should
be used. Defaults to TRUE. This is used only when warping_class != "srsf".
A boolean specifying whether the overall center
should be also computed. Defaults to FALSE. This is used only when
warping_class != "srsf".
A boolean specifying whether silhouette values should
be computed for each observation for internal validation of the clustering
structure. Defaults to TRUE.
A boolean specifying how to define the within-cluster
common grids. When set to FALSE, the intersection of the individual
domains is used. When set to TRUE, the union is used and mean imputation
is performed to fill in the missing values. Defaults to TRUE.
#----------------------------------
# Extracts 15 out of the 30 simulated curves in `simulated30_sub` data set
idx <- c(1:5, 11:15, 21:25)
x <- fdacluster::simulated30$x[idx, ]
y <- fdacluster::simulated30$y[idx, , ]
#----------------------------------
# Runs a k-means clustering with affine alignment, searching for 2 clusters
res <- kma(
x,
y,
n_clusters = 2,
seeds = c(1, 11),
warping_class = "affine",
centroid_type = "medoid",
metric = "pearson"
)
Run the code above in your browser using DataLab