% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Coassignment.R
\name{consensus_clustering}
\alias{consensus_clustering}
\title{Build a consensus partition from multiple imputation clustering results}
\usage{
consensus_clustering(
  partitions,
  k = NULL,
  cluster_method = "ward.D2",
  consensus_method = c("classic", "weighted_ari")
)
}
\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}} when \code{k} is a vector.}

\item{k}{An integer specifying the number of consensus clusters. Required
when \code{partitions} is a flat list of vectors (single-k input).
Ignored when \code{partitions} is a list-of-lists with names following
the pattern \code{"k2"}, \code{"k3"}, etc., as \code{k} is inferred
automatically from the names.}

\item{cluster_method}{A character string specifying the agglomeration
method passed to \code{\link[stats]{hclust}} for the consensus stage.
Accepted values are \code{"ward.D"}, \code{"ward.D2"}, \code{"single"},
\code{"complete"}, \code{"average"}, \code{"centroid"}, \code{"median"},
and \code{"mcquitty"}. Default is \code{"ward.D2"}.}

\item{consensus_method}{A character string specifying how the
co-assignment matrix is built. Options are:
\itemize{
\item \code{"classic"}: unweighted co-assignment; all partitions
contribute equally.
\item \code{"weighted_ari"}: partitions are weighted by their
pairwise ARI centrality, so more consistent partitions
contribute more to the consensus. Requires \pkg{mclust}.
}
Default is \code{"classic"}.}
}
\value{
\itemize{
\item If \code{partitions} is a flat list (single \code{k}): a named
list with the following elements:
\itemize{
\item \code{consensus_method}: character string with the method used.
\item \code{k}: integer, number of clusters requested.
\item \code{consensus}: integer vector of consensus cluster labels,
one per observation.
\item \code{coassignment}: numeric matrix of size \eqn{n \times n}
with co-assignment probabilities between 0 and 1.
\item \code{hclust}: the \code{hclust} object from the consensus
stage.
\item \code{weights}: named numeric vector of partition weights.
}
\item If \code{partitions} is a list-of-lists (multiple \code{k}):
a named list where each element corresponds to one value of
\code{k} and contains the structure described above.
}
}
\description{
Constructs a consensus clustering solution from a collection of partitions
obtained across multiple imputed datasets (as produced by
\code{\link{cluster_imputations}}). The function builds a co-assignment
matrix reflecting how frequently each pair of observations is assigned to
the same cluster, and derives the final consensus partition via hierarchical
clustering on the resulting dissimilarity. Supports both a single value of
\code{k} and a range of values.
}
\details{
The co-assignment matrix \eqn{C} is defined such that \eqn{C_{ij}}
represents the weighted proportion of partitions in which observations
\eqn{i} and \eqn{j} are assigned to the same cluster. The final
dissimilarity is computed as \eqn{1 - C} and passed to
\code{\link[stats]{hclust}}.

When \code{consensus_method = "weighted_ari"}, the weight of each
partition is proportional to its mean ARI against all other partitions,
reflecting its centrality within the ensemble. Negative centrality values
are floored at zero. If all centralities are zero, the function falls back
to equal weights with a warning.
}
\examples{
# ------------------------------------------------------------
# Example 1: Basic consensus clustering
# ------------------------------------------------------------
set.seed(123)
# simulate 3 partitions
partitions <- list(
  imp1 = sample(1:2, 10, replace = TRUE),
  imp2 = sample(1:2, 10, replace = TRUE),
  imp3 = sample(1:2, 10, replace = TRUE)
)

# Classic consensus
cons <- consensus_clustering(partitions, k = 2)
str(cons)

\donttest{
# ------------------------------------------------------------
# Example 2: consensus method with mice
# ------------------------------------------------------------
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 = 3)

  # -------------------------------------------------------------
  # Single k, classic consensus
  # -------------------------------------------------------------
  cons <- consensus_clustering(parts, k = 3)

  # -------------------------------------------------------------
  # Single k, ARI-weighted consensus
 # -------------------------------------------------------------
  if (requireNamespace("mclust", quietly = TRUE)) {
    cons_w <- consensus_clustering(parts, k = 3,
                                  consensus_method = "weighted_ari")
}
  # -------------------------------------------------------------
  # Multiple k values
  # -------------------------------------------------------------
  parts_multi <- cluster_imputations(mild, method = "ward.D2", k = 2:4)
  cons_multi  <- consensus_clustering(parts_multi)
}
}

}
\references{
Monti, S., Tamayo, P., Mesirov, J., & Golub, T. (2003).
Consensus clustering: A resampling-based method for class discovery
and visualization of gene expression microarray data.
\emph{Machine Learning}, \strong{52}(1-2), 91-118.
\doi{10.1023/A:1023949509487}

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