% 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}{\code{"full"} (default) also runs the element-wise CV
(\code{sigma.ecv}); \code{"fast"} skips it (the plot then shows only
r.squared and eff.rank, and the recommended rank falls back to the
R-squared elbow).}

\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.
The \code{effective.rank} column gives the effective rank
(\eqn{\exp} of the Shannon entropy of the explained-variance
distribution \eqn{p_k = \mathrm{var}(B_{k\cdot}) / \sum_j \mathrm{var}(B_{j\cdot})},
in \eqn{[1, Q]}); when it plateaus well below the nominal
\code{rank}, the extra factors are not carrying additional
coefficient variance, which suggests an over-specified rank.
The \code{effective.rank.ratio} column is \code{effective.rank /
  rank} in \eqn{[0, 1]} (the utilization fraction plotted as
\code{eff.rank} when \code{plot = TRUE}); a peak marks the rank
at which the latent factors carry the most evenly distributed
variance.}
}
\description{
\code{nmfkc.rank} provides diagnostic criteria for selecting the rank (\eqn{Q})
in NMF with kernel covariates. Three rank-selection measures are computed
(R-squared, the effective rank, and the element-wise CV error), and results
can be visualized in a plot. Sample-clustering quality (silhouette / CPCC /
dist.cor) is no longer part of rank selection; use \code{\link{nmf.cluster.criteria}}
on a fitted model for those.

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{
Roy, O., & Vetterli, M. (2007).  The effective rank: A measure of
effective dimensionality.  \emph{Proc. 15th European Signal Processing
Conf. (EUSIPCO)}, 606--610.  (\code{effective.rank})
Wold, S. (1978).  Cross-validatory estimation of the number of
components in factor and principal components models.
\emph{Technometrics}, 20(4), 397--405.
\doi{10.1080/00401706.1978.10489693}  (\code{sigma.ecv})
}
\seealso{
\code{\link{nmfkc}},
\code{\link{nmfkc.ecv}} (element-wise CV, used internally),
\code{\link{nmfkc.bicv}} (block bi-cross-validation),
\code{\link{nmfkc.consensus}} (stability) and
\code{\link{nmfkc.ard}} (Bayesian ARD) for alternative rank criteria.
}
