% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Validation.R
\name{validate_clustering}
\alias{validate_clustering}
\title{Validate consensus clustering results across multiple imputed datasets}
\usage{
validate_clustering(
  partitions,
  consensus_results,
  pac_lower = 0.1,
  pac_upper = 0.9
)
}
\arguments{
\item{partitions}{A list of cluster assignment vectors (one per imputed
dataset) for a single \code{k}, or a named list of such lists (one per
\code{k} value, named \code{"k2"}, \code{"k3"}, etc.) as returned by
\code{\link{cluster_imputations}}.}

\item{consensus_results}{A list as returned by
\code{\link{consensus_clustering}}, either for a single \code{k} or
for multiple \code{k} values. Must contain at least \code{$consensus}
and \code{$coassignment} for each \code{k}.}

\item{pac_lower}{A numeric value between 0 and 1 specifying the lower
bound of the ambiguous assignment region for the PAC metric. Default
is \code{0.1}.}

\item{pac_upper}{A numeric value between 0 and 1 specifying the upper
bound of the ambiguous assignment region for the PAC metric. Default
is \code{0.9}.}
}
\value{
A \code{data.frame} with one row per evaluated \code{k} and the
following columns:
\itemize{
\item \code{k}: number of clusters evaluated.
\item \code{pac}: Proportion of Ambiguous Clusterings. Lower values
indicate a more stable consensus. Computed from the upper
triangle of the co-assignment matrix.
\item \code{silhouette_mean}: mean silhouette width computed on the
consensus dissimilarity \eqn{1 - C}. Higher values indicate
better-defined clusters.
\item \code{ari_mean_between_imputations}: mean pairwise Adjusted
Rand Index (ARI) across all pairs of imputed partitions.
Higher values indicate greater clustering stability.
\item \code{ari_consensus_mean}: mean ARI between the consensus
partition and each individual imputed partition. Higher values
indicate that the consensus is representative of the ensemble.
\item \code{calinski_harabasz_mean}: Calinski-Harabasz index computed
via \code{fpc::cluster.stats()}. Higher values indicate more
compact and well-separated clusters.
\item \code{davies_bouldin_mean}: Davies-Bouldin index computed using
a medoid-based approach on the consensus dissimilarity. Lower
values indicate better cluster separation.
\item \code{dunn_index}: Dunn index computed via
\code{fpc::cluster.stats()}. Higher values indicate better
cluster compactness and separation.
}
}
\description{
Computes a comprehensive set of internal and stability validation metrics
for consensus clustering results obtained from multiple imputed datasets.
All internal metrics are computed on the consensus dissimilarity matrix
\eqn{1 - C}, where \eqn{C} is the co-assignment matrix, making the
function robust to numeric, categorical, and mixed data types. Supports
both single-k and multi-k evaluation.
}
\details{
All internal validation metrics (silhouette, Calinski-Harabasz,
Davies-Bouldin, Dunn) are computed exclusively on the consensus
dissimilarity matrix \eqn{1 - C} rather than on the original feature
space. This design choice ensures compatibility with any data type and
avoids recomputing distances from the raw imputed datasets.

The Davies-Bouldin index is computed using a custom medoid-based
implementation derived from the consensus dissimilarity, as no standard
R implementation accepts a precomputed dissimilarity matrix directly.

Helper functions prefixed with a dot (e.g., \code{.pac_from_coassignment},
\code{.mean_silhouette_from_diss}) are internal and not exported.
}
\examples{
# ------------------------------------------------------------
# Example 1: Basic validation with simulated partitions
# ------------------------------------------------------------
set.seed(123)

# Simulate partitions (3 imputations, k = 2)
parts <- list(
  imp1 = sample(1:2, 20, replace = TRUE),
  imp2 = sample(1:2, 20, replace = TRUE),
  imp3 = sample(1:2, 20, replace = TRUE)
)

cons <- consensus_clustering(parts, k = 2)
val  <- validate_clustering(parts, cons)

print(val)

\donttest{
# ------------------------------------------------------------
# Example 2: Full pipeline with mice (multiple k)
# ------------------------------------------------------------
if (requireNamespace("mice", quietly = TRUE)) {

  set.seed(123)

  imp  <- mice::mice(mice::nhanes, m = 3, printFlag = FALSE)
  mild <- as_mild_list(imp)

  parts <- cluster_imputations(mild, method = "ward.D2", k = 2:3)
  cons  <- consensus_clustering(parts)

  val <- validate_clustering(parts, cons)

  print(val)
}
}

}
\references{
Senbabaoglu, Y., Michailidis, G., & Li, J. Z. (2014).
Critical limitations of consensus clustering in class discovery.
\emph{Scientific Reports}, \strong{4}, 6207.
\doi{10.1038/srep06207}

Rousseeuw, P. J. (1987).
Silhouettes: A graphical aid to the interpretation and validation
of cluster analysis.
\emph{Journal of Computational and Applied Mathematics}, \strong{20}, 53-65.
\doi{10.1016/0377-0427(87)90125-7}

Calinski, T., & Harabasz, J. (1974).
A dendrite method for cluster analysis.
\emph{Communications in Statistics}, \strong{3}, 1-27.
\doi{10.1080/03610927408827101}

Davies, D. L., & Bouldin, D. W. (1979).
A cluster separation measure.
\emph{IEEE Transactions on Pattern Analysis and Machine Intelligence},
\strong{PAMI-1}, 224-227.
\doi{10.1109/TPAMI.1979.4766909}

Dunn, J. C. (1974).
Well-separated clusters and optimal fuzzy partitions.
\emph{Journal of Cybernetics}, \strong{4}, 95-104.
\doi{10.1080/01969727408546059}

Hubert, L., & Arabie, P. (1985).
Comparing partitions.
\emph{Journal of Classification}, \strong{2}, 193-218.
\doi{10.1007/BF01908075}
}
\seealso{
\code{\link{consensus_clustering}}, \code{\link{choose_best_clustering}}
}
