% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmf.ffb.R, R/nmf.sem.R
\name{nmf.ffb.cv}
\alias{nmf.ffb.cv}
\alias{nmf.sem.cv}
\title{Cross-Validation for NMF-FFB}
\usage{
nmf.ffb.cv(...)

nmf.sem.cv(
  Y1,
  Y2,
  rank = NULL,
  X.init = "nndsvd",
  X.L2.ortho = 100,
  C1.L1 = 1,
  C2.L1 = 0.1,
  epsilon = 1e-06,
  maxit = 5000,
  ...
)
}
\arguments{
\item{...}{Additional arguments passed to \code{nmf.sem} (except for
\code{rank}, \code{seed}, \code{div}, \code{shuffle}, which are handled here).
Also accepts: \code{nfolds} (number of folds, default 5; \code{div} also accepted),
\code{seed} (master random seed, default \code{NULL}),
\code{shuffle} (logical, default \code{TRUE}).}

\item{Y1}{A non-negative numeric matrix of endogenous variables with
\strong{rows = variables (P1), columns = samples (N)}.}

\item{Y2}{A non-negative numeric matrix of exogenous variables with
\strong{rows = variables (P2), columns = samples (N)}.
Must satisfy \code{ncol(Y1) == ncol(Y2)}.}

\item{rank}{Integer; rank (number of latent factors) passed to \code{nmf.sem}.
If \code{NULL}, \code{nmf.sem} decides the effective rank (via \code{...} or \code{nrow(Y2)}).}

\item{X.init}{Initialization strategy for \code{X}, forwarded to
\code{\link{nmf.sem}}.  One of \code{"nndsvd"} (default),
\code{"kmeans"}, \code{"kmeansar"}, \code{"runif"}, a numeric
\eqn{P_1 \times Q} matrix, or \code{NULL} (alias for
\code{"nndsvd"}).  See \code{\link{nmf.sem}} for details.}

\item{X.L2.ortho}{L2 orthogonality penalty for \code{X}.}

\item{C1.L1}{L1 sparsity penalty for \code{C1} (\eqn{\Theta_1}).}

\item{C2.L1}{L1 sparsity penalty for \code{C2} (\eqn{\Theta_2}).}

\item{epsilon}{Convergence threshold for \code{nmf.sem}.}

\item{maxit}{Maximum number of iterations for \code{nmf.sem}.}
}
\value{
A numeric scalar: mean MAE across CV folds.
}
\description{
Performs K-fold cross-validation to evaluate the equilibrium mapping of
the NMF-FFB model.

For each fold, \code{nmf.sem} is fitted on the training samples,
yielding an equilibrium mapping \eqn{\hat Y_1 = M_{\mathrm{model}} Y_2}.
The held-out endogenous variables \eqn{Y_1} are then predicted from \eqn{Y_2}
using this mapping, and the mean absolute error (MAE) over all entries in the
test block is computed. The returned value is the average MAE across folds.

This implements the hyperparameter selection strategy described in the paper:
hyperparameters are chosen by predictive cross-validation rather than direct
inspection of the internal structural matrices.
}
\examples{
Y <- t(iris[, -5])
Y1 <- Y[1:2, ]
Y2 <- Y[3:4, ]
mae <- nmf.sem.cv(Y1, Y2, rank = 2, maxit = 500, nfolds = 3)
mae

}
\seealso{
\code{\link{nmf.sem}}
}
