% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfkc.consensus.R
\name{nmfkc.consensus}
\alias{nmfkc.consensus}
\title{Consensus-clustering rank selection for NMF (Brunet 2004)}
\usage{
nmfkc.consensus(
  Y,
  A = NULL,
  rank = 2:4,
  nrun = 30,
  keep.consensus = FALSE,
  ...
)
}
\arguments{
\item{Y}{Observation matrix (\eqn{P \times N}), non-negative.}

\item{A}{Optional covariate matrix passed to \code{\link{nmfkc}}.}

\item{rank}{Integer vector of ranks to evaluate (\eqn{\ge 2}).}

\item{nrun}{Number of random-initialization runs per rank (default 30).}

\item{keep.consensus}{Logical; if \code{TRUE} also return the list of
consensus matrices (one \eqn{N \times N} matrix per rank).}

\item{...}{Advanced options, rarely needed (defaults in parentheses):
\code{seed} (\code{123}, base seed; run \eqn{r} of rank index \eqn{i} uses
\code{seed + 1000 * i + r}) and \code{pac.range} (\code{c(0.1, 0.9)}, the
ambiguous interval \eqn{(u_1, u_2)} for the PAC measure).  Any other
arguments are passed to \code{\link{nmfkc}} (e.g.\ \code{maxit});
\code{X.init} is forced to \code{"runif"}.}
}
\value{
An object of class \code{"nmfkc.consensus"} (a list) with:
\item{cophenetic}{Cophenetic correlation coefficient for each rank.}
\item{dispersion}{Dispersion coefficient (\eqn{[0, 1]}) for each rank.}
\item{pac}{Proportion of Ambiguous Clustering (\eqn{[0, 1]}, lower is
better) for each rank.}
\item{rank}{The evaluated rank vector.}
\item{nrun}{Number of runs per rank.}
\item{consensus}{List of consensus matrices, or \code{NULL}.}
It has \code{\link{print.nmfkc.consensus}} and
\code{\link{plot.nmfkc.consensus}} (\code{type = "criteria"} /
\code{"heatmap"}) methods.
}
\description{
The bioinformatics-standard stability approach to choosing the NMF rank.
A lightweight engine like \code{\link{nmfkc.ecv}} / \code{\link{nmfkc.bicv}}:
it returns one stability score per rank and nothing more.

For each rank, NMF is run \code{nrun} times from different random
initializations (\code{X.init = "runif"}).  Each run gives a hard
clustering of the samples (the column \eqn{\arg\max} of the coefficient
matrix).  Averaging the \eqn{N \times N} connectivity matrices (1 if two
samples share a cluster) over the runs yields the \strong{consensus
matrix}; its crispness measures how reproducible the clustering is.  Two
summaries are reported per rank:
\itemize{
\item \code{cophenetic}: the cophenetic correlation coefficient (CPCC)
of the consensus matrix (Brunet et al. 2004).  Close to 1 = stable.
\item \code{dispersion}: the Kim & Park (2007) dispersion
\eqn{\frac{1}{N^2}\sum_{ij} 4 (C_{ij} - 1/2)^2 \in [0, 1]}; 1 when
every consensus entry is exactly 0 or 1 (perfectly crisp).
\item \code{pac}: the Proportion of Ambiguous Clustering
(Senbabaoglu et al. 2014) -- the fraction of off-diagonal consensus
entries falling in the ambiguous interval \code{pac.range}
(default \eqn{(0.1, 0.9)}).  \strong{Lower is better} (less
ambiguity); a more sensitive readout than \code{cophenetic}, which
tends to saturate.
}
Unlike the cross-validation engines (where the rank \emph{minimizes} the
error), here a good rank \strong{maximizes} stability, or is the largest
rank before it drops.
}
\examples{
\donttest{
Y <- t(as.matrix(iris[, 1:4]))
cs <- nmfkc.consensus(Y, rank = 2:5, nrun = 20, keep.consensus = TRUE)
cs                       # stability table per rank
plot(cs)                 # type = "criteria": stability curves
plot(cs, type = "heatmap")            # all ranks, n2mfrow grid
plot(cs, type = "heatmap", rank = 3)  # one rank, with labels
}
}
\references{
Brunet, J.-P., Tamayo, P., Golub, T. R., Mesirov, J. P. (2004).
Metagenes and molecular pattern discovery using matrix factorization.
\emph{PNAS} 101(12):4164--4169. \doi{10.1073/pnas.0308531101}.
Kim, H., Park, H. (2007).  Sparse non-negative matrix factorizations
\dots \emph{Bioinformatics} 23(12):1495--1502.
Senbabaoglu, Y., Michailidis, G., Li, J. Z. (2014).  Critical
limitations of consensus clustering in class discovery.
\emph{Sci. Rep.} 4:6207. \doi{10.1038/srep06207}.
}
\seealso{
\code{\link{nmfkc.rank}}, \code{\link{nmfkc.ecv}},
\code{\link{nmfkc.bicv}}, \code{\link{nmfkc.ard}},
\code{\link{nmf.cluster.criteria}}
}
