% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfkc.R
\name{nmfkc.rank}
\alias{nmfkc.rank}
\title{Rank selection diagnostics with graphical output}
\usage{
nmfkc.rank(Y, A = NULL, rank = 1:2, detail = "full", plot = TRUE, data, ...)
}
\arguments{
\item{Y}{Observation matrix, or a formula (see \code{\link{nmfkc}} for Formula Mode).}

\item{A}{Covariate matrix. If \code{NULL}, the identity matrix is used.
Ignored when \code{Y} is a formula.}

\item{rank}{A vector of candidate ranks to be evaluated.}

\item{detail}{Level of criterion computation: \code{"full"} (default) computes
all criteria including ECV; \code{"fast"} skips ECV and distance-based criteria.}

\item{plot}{Logical. If \code{TRUE} (default), draws a plot of the diagnostic criteria.}

\item{data}{A data frame (required when \code{Y} is a formula with column names).}

\item{...}{Additional arguments passed to \code{\link{nmfkc}} and \code{\link{nmfkc.ecv}}.
\itemize{
\item \code{Q}: (Deprecated) Alias for \code{rank}.
\item \code{save.time}: (Deprecated) \code{TRUE} maps to \code{detail = "fast"}.
}}
}
\value{
A list containing:
\item{rank.best}{The estimated optimal rank. Prioritizes ECV minimum if available, otherwise R-squared Elbow.}
\item{criteria}{A data frame containing diagnostic metrics for each rank.}
}
\description{
\code{nmfkc.rank} provides diagnostic criteria for selecting the rank (\eqn{Q})
in NMF with kernel covariates. Several model selection measures are computed
(e.g., R-squared, silhouette, CPCC, ARI), and results can be visualized in a plot.

By default (\code{save.time = FALSE}), this function also computes the
Element-wise Cross-Validation error (Wold's CV Sigma) using \code{\link{nmfkc.ecv}}.

The plot explicitly marks the "BEST" rank based on two criteria:
\enumerate{
\item \strong{Elbow Method (Red)}: Based on the curvature of the R-squared values (always computed if Q > 2).
\item \strong{Min RMSE (Blue)}: Based on the minimum Element-wise CV Sigma (only if \code{detail="full"}).
}
}
\examples{
# Example.
Y <- t(iris[,-5])
# Full run (default)
nmfkc.rank(Y, rank=1:4)
# Fast run (skip ECV)
nmfkc.rank(Y, rank=1:4, detail="fast")
}
\references{
Brunet, J.P., Tamayo, P., Golub, T.R., Mesirov, J.P. (2004).
Metagenes and molecular pattern discovery using matrix factorization.
\emph{Proc. Natl. Acad. Sci. USA}, 101, 4164–4169.
\doi{10.1073/pnas.0308531101}
Punera, K., & Ghosh, J. (2008).
Consensus-based ensembles of soft clusterings.
\emph{Applied Artificial Intelligence}, 22(7–8), 780–810.
\doi{10.1080/08839510802170546}
}
\seealso{
\code{\link{nmfkc}}, \code{\link{nmfkc.ecv}}
}
