% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfae.R
\name{nmfae.ecv}
\alias{nmfae.ecv}
\title{Element-wise Cross-Validation for nmfae (Wold's CV)}
\usage{
nmfae.ecv(Y1, Y2 = Y1, rank = 1:2, rank.encoder = NULL, ...)
}
\arguments{
\item{Y1}{Output matrix \eqn{Y_1} (P1 x N).}

\item{Y2}{Input matrix \eqn{Y_2} (P2 x N). Default is \code{Y1}.}

\item{rank}{Integer vector of decoder ranks to evaluate. Default is \code{1:2}.}

\item{rank.encoder}{Integer vector of encoder ranks to evaluate. Default is \code{NULL},
which sets \code{rank.encoder = rank} and evaluates element-wise pairs.
When explicitly specified, all combinations with \code{rank} are evaluated.}

\item{...}{Additional arguments passed to \code{\link{nmfae}} (e.g., \code{epsilon}, \code{maxit}).
Also accepts: \code{nfolds} (number of folds, default 5; \code{div} also accepted),
\code{seed} (integer seed, default 123).
For backward compatibility, \code{Q} and \code{R} are accepted as aliases for
\code{rank} and \code{rank.encoder}.}
}
\value{
A list with components:
\item{objfunc}{Named numeric vector of mean MSE for each (Q, R) pair.}
\item{sigma}{Named numeric vector of RMSE (square root of MSE) for each pair.}
\item{objfunc.fold}{Named list of per-fold MSE vectors for each pair.}
\item{folds}{List of length \code{div} containing the held-out element indices for each fold.}
\item{QR}{Data frame with columns \code{Q} and \code{R} listing the evaluated pairs.}
}
\description{
\code{nmfae.ecv} performs k-fold element-wise cross-validation by randomly
holding out individual elements of \eqn{Y_1}, assigning them a weight of 0
via \code{Y1.weights}, and evaluating the reconstruction error on those
held-out elements.

This method (also known as Wold's CV) is suitable for determining the optimal
rank pair \eqn{(Q, R)} in three-layer NMF. Both \code{rank} and \code{rank.encoder} accept
vector inputs. When \code{rank.encoder = NULL} (default), \code{rank.encoder} is set equal to \code{rank}
and pairs are evaluated element-wise (i.e., \eqn{(Q_1, R_1), (Q_2, R_2), \dots}).
When \code{rank.encoder} is explicitly specified, all combinations of \code{rank} and \code{rank.encoder}
are evaluated via \code{expand.grid}.
}
\section{Lifecycle}{

This function is \strong{experimental}. The interface may change in
future versions; details are to be described in an upcoming paper.
}

\examples{
Y <- t(iris[1:30, 1:4])
# Default: rank.encoder=NULL -> paired rank=rank.encoder
res <- nmfae.ecv(Y, rank = 1:3, nfolds = 3, maxit = 500)
res$sigma
# Explicit rank.encoder: full grid
res2 <- nmfae.ecv(Y, rank = 1:3, rank.encoder = 1:3, nfolds = 3, maxit = 500)
res2$sigma

}
\seealso{
\code{\link{nmfae}}, \code{\link{nmfkc.ecv}}
}
