% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfkc.bicv.R
\name{nmfkc.bicv}
\alias{nmfkc.bicv}
\title{Bi-cross-validation for NMF rank selection}
\usage{
nmfkc.bicv(Y, rank = 1:3, ...)
}
\arguments{
\item{Y}{Observation matrix (\eqn{P \times N}), non-negative.}

\item{rank}{Integer vector of ranks to evaluate.}

\item{...}{Advanced options, rarely needed (defaults in parentheses):
\code{nfolds} (\code{2}), the number of row and column folds (the grid is
\code{nfolds x nfolds}; \code{2} leaves out half the rows / columns, Owen
& Perry's recommendation); \code{seed} (\code{123}, fold-assignment seed);
and \code{nnls.maxit} (\code{100}, multiplicative-update iterations for the
fold-in non-negative regressions).  Any other arguments are passed to
\code{\link{nmfkc}} for the per-block fits (e.g.\ \code{maxit}).}
}
\value{
A list (cf.\ \code{\link{nmfkc.ecv}}) with:
\item{objfunc}{Held-out mean squared error for each rank.}
\item{sigma}{Its square root (RMSE) for each rank.}
\item{rank}{The evaluated rank vector.}
\item{nfolds}{The number of folds used.}
}
\description{
Owen & Perry's (2009) bi-cross-validation (BCV) for choosing the NMF
rank.  A lightweight CV engine in the spirit of \code{\link{nmfkc.ecv}}:
it returns the held-out error per rank and nothing more (no plot, no
table) -- pass the result to \code{which.min(sigma)}, or build your own
diagnostics.

Unlike the element-wise CV of \code{\link{nmfkc.ecv}} (which holds out
scattered \emph{entries} and refits with weights), BCV holds out a whole
\strong{row-block and column-block} simultaneously: the model is fit only
on the retained block \eqn{D}, and the held-out block \eqn{A} is predicted
by folding the held-out rows/columns onto the fixed \eqn{D}-factors via
non-negative regression (\eqn{\hat A = L_I R_J}).  Because the held-out
rows and columns never enter the fit, there is no information leakage.
Covariates are ignored (plain NMF).  The recommended setting is to leave
out roughly half the rows and half the columns (\code{nfolds = 2}).
}
\details{
Each fold keeps about \eqn{(1 - 1/\text{nfolds})} of the rows
and columns, so the retained block \eqn{D} must have more than
\code{rank} rows \strong{and} columns.  The largest testable rank is
therefore about \eqn{(1 - 1/\text{nfolds})\min(P, N) - 1}; with
\code{nfolds = 2} this is roughly \eqn{\min(P, N)/2 - 1}.  Ranks above
this return \code{NA} and trigger a \code{\link[base]{warning}} that
names the limit and the \code{nfolds} (or \code{\link{nmfkc.ecv}})
that would reach the requested ranks.  Raising \code{nfolds} lifts the
limit at the cost of a smaller hold-out and more compute
(\eqn{(\text{nfolds} - 1)^2} full fits per rank).
}
\examples{
\donttest{
## rank-3 non-negative data; bi-CV needs enough kept rows/cols per
## fold (> rank), so use a matrix with ample dimensions.
set.seed(1)
X <- matrix(abs(rnorm(30 * 3)), 30, 3)
B <- matrix(abs(rnorm(3 * 40)), 3, 40)
bv <- nmfkc.bicv(X \%*\% B, rank = 1:6)   # nfolds = 2 (Owen & Perry) by default
bv$sigma                  # held-out RMSE per rank
bv$rank[which.min(bv$sigma)]
}
}
\references{
A. B. Owen and P. O. Perry (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}.
}
\seealso{
\code{\link{nmfkc.rank}}, \code{\link{nmfkc.ecv}},
\code{\link{nmfkc.consensus}}, \code{\link{nmfkc.ard}}
}
