% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils_cluster_hclust_optimizer.R
\name{utils_cluster_hclust_optimizer}
\alias{utils_cluster_hclust_optimizer}
\title{Optimize the Silhouette Width of Hierarchical Clustering Solutions}
\usage{
utils_cluster_hclust_optimizer(d = NULL, method = NULL)
}
\arguments{
\item{d}{(required, matrix) distance matrix typically resulting from \code{\link[=distantia_matrix]{distantia_matrix()}}, but any other square matrix should work. Default: NULL}

\item{method}{(optional, character string) argument of \code{\link[stats:hclust]{stats::hclust()}} defining the agglomerative method. One of: "ward.D", "ward.D2", "single", "complete", "average" (= UPGMA), "mcquitty" (= WPGMA), "median" (= WPGMC), or "centroid" (= UPGMC). Unambiguous abbreviations are accepted as well.

This function supports parallelization via \code{\link[future:plan]{future::plan()}} and progress bars provided by the package \href{https://CRAN.R-project.org/package=progressr}{progressr}.}
}
\value{
data frame
}
\description{
Performs a parallelized grid search to find the number of clusters maximizing the overall silhouette width of the clustering solution (see \code{\link[=utils_cluster_silhouette]{utils_cluster_silhouette()}}). When \code{method = NULL}, the optimization also includes all methods available in \code{\link[stats:hclust]{stats::hclust()}} in the grid search. This function supports parallelization via \code{\link[future:plan]{future::plan()}} and a progress bar generated by the \code{progressr} package (see Examples).
}
\examples{

#weekly covid prevalence
#in 10 California counties
#aggregated by month
tsl <- tsl_initialize(
  x = covid_prevalence,
  name_column = "name",
  time_column = "time"
) |>
  tsl_subset(
    names = 1:10
  ) |>
  tsl_aggregate(
    new_time = "months",
    fun = max
  )

if(interactive()){
  #plotting first three time series
  tsl_plot(
    tsl = tsl_subset(
      tsl = tsl,
      names = 1:3
    ),
    guide_columns = 3
  )
}

#compute dissimilarity matrix
psi_matrix <- distantia(
  tsl = tsl,
  lock_step = TRUE
) |>
  distantia_matrix()

#optimize hierarchical clustering
hclust_optimization <- utils_cluster_hclust_optimizer(
  d = psi_matrix
)

#best solution in first row
head(hclust_optimization)

}
\seealso{
Other distantia_support:
\code{\link[=distantia_aggregate]{distantia_aggregate()}},
\code{\link[=distantia_boxplot]{distantia_boxplot()}},
\code{\link[=distantia_cluster_hclust]{distantia_cluster_hclust()}},
\code{\link[=distantia_cluster_kmeans]{distantia_cluster_kmeans()}},
\code{\link[=distantia_matrix]{distantia_matrix()}},
\code{\link[=distantia_model_frame]{distantia_model_frame()}},
\code{\link[=distantia_spatial]{distantia_spatial()}},
\code{\link[=distantia_stats]{distantia_stats()}},
\code{\link[=distantia_time_delay]{distantia_time_delay()}},
\code{\link[=utils_block_size]{utils_block_size()}},
\code{\link[=utils_cluster_kmeans_optimizer]{utils_cluster_kmeans_optimizer()}},
\code{\link[=utils_cluster_silhouette]{utils_cluster_silhouette()}}
}
\concept{distantia_support}
