% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfkc.R
\name{nmfkc.ecv}
\alias{nmfkc.ecv}
\title{Perform Element-wise Cross-Validation (Wold's CV)}
\usage{
nmfkc.ecv(Y, A = NULL, rank = 1:3, data, ...)
}
\arguments{
\item{Y}{Observation matrix, or a formula (see \code{\link{nmfkc}} for Formula Mode).}

\item{A}{Covariate matrix. Ignored when \code{Y} is a formula.}

\item{rank}{Vector of ranks to evaluate (e.g., 1:5). For backward compatibility,
\code{Q} is accepted via \code{...}.}

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

\item{...}{Additional arguments passed to \code{\link{nmfkc}} (e.g., \code{method="EU"}).
Also accepts: \code{nfolds} (number of folds, default 5; \code{div} also accepted),
\code{seed} (integer seed, default 123).}
}
\value{
A list with components:
\item{objfunc}{Numeric vector containing the Mean Squared Error (MSE) for each Q.}
\item{sigma}{Numeric vector containing the Residual Standard Error (RMSE) for each Q. Only available if method="EU".}
\item{objfunc.fold}{List of length equal to Q vector. Each element contains the MSE values for the k folds.}
\item{folds}{A list of length \code{div}, containing the linear indices of held-out elements for each fold (shared across all Q).}
}
\description{
\code{nmfkc.ecv} performs k-fold cross-validation by randomly holding out
individual elements of the data matrix (element-wise), assigning them a
weight of 0 via \code{Y.weights}, and evaluating the reconstruction error on
those held-out elements.

This method (also known as Wold's CV) is theoretically robust for determining
the optimal rank (Q) in NMF. This function supports vector input for \code{Q},
allowing simultaneous evaluation of multiple ranks on the same folds.

For symmetric (network) data use \code{\link{nmfkc.net.ecv}}, which
creates upper-triangle folds to prevent information leakage through
the symmetric entries \eqn{Y_{ij} = Y_{ji}}.  Passing the old
\code{Y.symmetric} argument here is no longer supported and stops
with a redirect message.
}
\examples{
# Element-wise CV to select rank
Y <- t(iris[1:30, 1:4])
res <- nmfkc.ecv(Y, rank = 1:2, nfolds = 3)
res$objfunc

}
\references{
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}
Owen, A. B., & Perry, P. O. (2009).  Bi-cross-validation of the SVD
and the nonnegative matrix factorization.  \emph{Ann. Appl. Stat.}
3(2), 564--594. \doi{10.1214/08-AOAS227}  (cross-validation of the
NMF rank; see also \code{\link{nmfkc.bicv}}).
}
\seealso{
\code{\link{nmfkc}}, \code{\link{nmfkc.cv}}; other rank-selection
criteria: \code{\link{nmfkc.rank}}, \code{\link{nmfkc.bicv}},
\code{\link{nmfkc.consensus}}, \code{\link{nmfkc.ard}}.
}
