% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfkc.R
\name{nmfkc.cv}
\alias{nmfkc.cv}
\title{Perform k-fold cross-validation for NMF with kernel covariates}
\usage{
nmfkc.cv(Y, A = NULL, rank = 2, 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}{Rank of the basis matrix \eqn{X}. Default is 2.}

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

\item{...}{Additional arguments controlling CV and the internal \code{\link{nmfkc}} call:
\describe{
\item{\code{Y.weights}}{Non-negative weight matrix or vector
(\code{lm()}-style: loss \eqn{\sum W \, r^2}).  Binary
\code{{0,1}} masks (\code{TRUE} / \code{FALSE} also accepted)
are the typical ECV usage -- 0/\code{FALSE} excludes an element.
See \code{\link{nmfkc}} for full details.}
\item{\code{div}}{Number of folds (\eqn{k}); default: \code{5}.}
\item{\code{seed}}{Integer seed for reproducible partitioning; default: \code{123}.}
\item{\code{shuffle}}{Logical. If \code{TRUE} (default), randomly shuffles samples (standard CV);
if \code{FALSE}, splits sequentially (block CV; recommended for time series).}
\item{\code{Q}}{(Deprecated) Alias for \code{rank}.}
\item{\emph{Arguments passed to} \code{\link{nmfkc}}}{e.g., \code{gamma} (\code{B.L1}), \code{epsilon},
\code{maxit}, \code{method} (\code{"EU"} or \code{"KL"}), \code{X.restriction}, \code{X.init}, etc.}
}}
}
\value{
A list with components:
\describe{
\item{\code{objfunc}}{Mean loss per valid entry over all folds (MSE for \code{method="EU"}).}
\item{\code{sigma}}{Residual standard error (RMSE). Available only if \code{method="EU"}; on the same scale as \code{Y}.}
\item{\code{objfunc.block}}{Loss for each fold.}
\item{\code{block}}{Vector of fold indices (1, …, \code{div}) assigned to each column of \eqn{Y}.}
}
}
\description{
\code{nmfkc.cv} performs k-fold cross-validation for the tri-factorization model
\eqn{Y \approx X C A = X B}, where
\itemize{
\item \eqn{Y(P,N)} is the observation matrix,
\item \eqn{A(R,N)} is the covariate (or kernel) matrix,
\item \eqn{X(P,Q)} is the basis matrix,
\item \eqn{C(Q,R)} is the parameter matrix, and
\item \eqn{B(Q,N)} is the coefficient matrix (\eqn{B = C A}).
}
Given \eqn{Y} (and optionally \eqn{A}), \eqn{X} and \eqn{C} are fitted on each
training split and predictive performance is evaluated on the held-out split.
}
\examples{
# Example 1 (with explicit covariates):
Y <- matrix(cars$dist, nrow = 1)
A <- rbind(1, cars$speed)
res <- nmfkc.cv(Y, A, rank = 1)
res$objfunc

# Example 2 (kernel A and beta sweep):
Y <- matrix(cars$dist, nrow = 1)
U <- matrix(c(5, 10, 15, 20, 25), nrow = 1)
V <- matrix(cars$speed, nrow = 1)
betas <- 25:35/1000
obj <- numeric(length(betas))
for (i in seq_along(betas)) {
  A <- nmfkc.kernel(U, V, beta = betas[i])
  obj[i] <- nmfkc.cv(Y, A, rank = 1, nfolds = 10)$objfunc
}
betas[which.min(obj)]

}
\seealso{
\code{\link{nmfkc}}, \code{\link{nmfkc.kernel.beta.cv}}, \code{\link{nmfkc.ar.degree.cv}}
}
