% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ValidationK.R
\name{plot_validation_metrics}
\alias{plot_validation_metrics}
\title{Plot validation metrics across candidate numbers of clusters}
\usage{
plot_validation_metrics(
  validation_table,
  metrics = c("pac", "silhouette_mean", "ari_mean_between_imputations",
    "ari_consensus_mean", "calinski_harabasz_mean", "davies_bouldin_mean", "dunn_index",
    "score")
)
}
\arguments{
\item{validation_table}{A \code{data.frame} as returned by
\code{\link{validate_clustering}} or \code{$scores_table} from
\code{\link{choose_best_clustering}}. Must contain a column \code{k}
and at least one of the requested metric columns.}

\item{metrics}{A character vector specifying which metrics to plot.
Only metrics present in \code{validation_table} are plotted; others
are silently ignored. Default includes all standard metrics plus
\code{score}:
\code{"pac"}, \code{"silhouette_mean"},
\code{"ari_mean_between_imputations"}, \code{"ari_consensus_mean"},
\code{"calinski_harabasz_mean"}, \code{"davies_bouldin_mean"},
\code{"dunn_index"}, and \code{"score"}.}
}
\value{
Invisibly returns \code{NULL}. The function is called for its
side effect of producing a plot.
}
\description{
Produces a multi-panel line plot displaying one or more clustering
validation metrics as a function of the number of clusters \code{k},
as computed by \code{\link{validate_clustering}} and optionally extended
with a \code{score} column by \code{\link{choose_best_clustering}}. For
each metric, the optimal value is highlighted in red.
}
\details{
The number of panels is determined automatically from the number of
available metrics using \code{ceiling(sqrt(n))} rows and
\code{ceiling(n / nrow)} columns, producing a layout as square as
possible.

The direction of optimality is accounted for when highlighting the best
value: lower is better for \code{pac}, \code{davies_bouldin_mean}, and
\code{score}; higher is better for all remaining metrics. The optimal
point for each metric is highlighted in red.

Original graphical parameters are restored on exit via
\code{\link[graphics]{par}}.

When \code{score} is present (i.e., \code{validation_table} comes from
\code{\link{choose_best_clustering}}), the panel for \code{score} shows
the overall weighted rank aggregation - the \code{k} with the lowest
score is the recommended solution.
}
\examples{
# ------------------------------------------------------------
# Example 1: Validation metrics with simulated data
# ------------------------------------------------------------
val_table <- data.frame(
  k                            = 2:4,
  pac                          = c(0.15, 0.08, 0.20),
  silhouette_mean              = c(0.42, 0.61, 0.38),
  ari_mean_between_imputations = c(0.80, 0.91, 0.75),
  ari_consensus_mean           = c(0.82, 0.93, 0.77),
  calinski_harabasz_mean       = c(120,  198,  105),
  davies_bouldin_mean          = c(0.85, 0.54, 0.97),
  dunn_index                   = c(0.30, 0.48, 0.27)
)

# Plot all metrics
plot_validation_metrics(val_table)

# Plot only stability metrics
plot_validation_metrics(val_table,
                        metrics = c("pac",
                                    "ari_mean_between_imputations",
                                    "ari_consensus_mean"))
\donttest{
# ------------------------------------------------------------
# Example 2: metrics validation with mice
# ------------------------------------------------------------

if (requireNamespace("mice", quietly = TRUE)) {

set.seed(123)
imp    <- mice::mice(mice::nhanes, m = 5, printFlag = FALSE)
mild   <- as_mild_list(imp)
parts  <- cluster_imputations(mild, method = "ward.D2", k = 2:5)
cons   <- consensus_clustering(parts)
val    <- validate_clustering(parts, cons)

# Plot all available metrics (no score column yet)
plot_validation_metrics(val)

# Include score column from choose_best_clustering
best <- choose_best_clustering(val, cons)
plot_validation_metrics(best)

# Plot only stability metrics
plot_validation_metrics(val,
                        metrics = c("pac",
                                    "ari_mean_between_imputations",
                                    "ari_consensus_mean"))
}
}

}
\seealso{
\code{\link{validate_clustering}}, \code{\link{choose_best_clustering}},
\code{\link{plot_consensus_dendrogram}}, \code{\link{plot_consensus_matrix}}
}
