% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cluster_choice.R
\name{cluster_choice}
\alias{cluster_choice}
\title{Cluster Choice -- sweep k, dissimilarity and method}
\usage{
cluster_choice(
  data,
  k = 2:5,
  dissimilarity = "hamming",
  method = "ward.D2",
  ...
)
}
\arguments{
\item{data}{Sequence data (data frame or matrix) -- forwarded to
\code{\link{build_clusters}}.}

\item{k}{Integer vector of cluster counts to sweep. Default
\code{2:5}. Each value must be >= 2 and <= n - 1.}

\item{dissimilarity}{Character vector of dissimilarity metrics. Use
\code{"all"} to expand to every supported metric:
\code{c("hamming", "osa", "lv", "dl", "lcs", "qgram", "cosine",}
\code{"jaccard", "jw")}. Default \code{"hamming"}.}

\item{method}{Character vector of clustering algorithms. Use
\code{"all"} to expand to every supported method:
\code{c("pam", "ward.D2", "ward.D", "complete", "average", "single",}
\code{"mcquitty", "median", "centroid")}. Default \code{"ward.D2"}.}

\item{...}{Other arguments forwarded to
\code{\link{build_clusters}} (\code{weighted}, \code{lambda},
\code{q}, \code{p}, \code{seed}, \code{na_syms}, \code{covariates}).
Note: \code{weighted = TRUE} only works with
\code{dissimilarity = "hamming"} and is rejected up-front when
sweeping mixed dissimilarities.}
}
\value{
A \code{cluster_choice} object (a data.frame subclass) with
one row per (k, dissimilarity, method) combination and columns:
\describe{
\item{k, dissimilarity, method}{The configuration for that row.}
\item{silhouette}{Overall average silhouette width (from
\code{cluster::silhouette}, computed inside
\code{\link{build_clusters}}).}
\item{mean_within_dist}{Size-weighted mean of within-cluster
distances, in the units of the row's dissimilarity.}
\item{min_size, max_size, size_ratio}{Cluster-size balance bounds
and their ratio (\code{max / min}).}
}
}
\description{
One-call sweep across any combination of k, dissimilarity metric, and
clustering algorithm for distance-based sequence clustering. Mirrors
\code{\link{compare_mmm}} for model-based clustering: returns a data
frame with one row per swept configuration, a \code{best} marker on
the silhouette-max row in the print method, and a \code{plot()} that
adapts to the swept axes.
}
\examples{
seqs <- data.frame(V1 = sample(c("A","B","C"), 40, TRUE),
                   V2 = sample(c("A","B","C"), 40, TRUE))
cluster_choice(seqs, k = 2:4)
\donttest{
# Sweep dissimilarities at fixed k
cluster_choice(seqs, k = 3, dissimilarity = c("hamming", "lcs", "jaccard"))

# Full grid of k x dissimilarity
cluster_choice(seqs, k = 2:4, dissimilarity = c("hamming", "lcs"))

# "all" sentinel
cluster_choice(seqs, k = 3, dissimilarity = "all")
}
}
\seealso{
\code{\link{build_clusters}}, \code{\link{compare_mmm}} for
the model-based equivalent, \code{\link{cluster_diagnostics}} for
the post-fit diagnostic surface on a single clustering.
}
