% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfre.R
\name{nmfre}
\alias{nmfre}
\title{Non-negative Matrix Factorization with Random Effects}
\usage{
nmfre(
  Y,
  A = NULL,
  rank = 2,
  df.rate = NULL,
  wild.bootstrap = TRUE,
  epsilon = 1e-05,
  maxit = 5000,
  ...
)
}
\arguments{
\item{Y}{Observation matrix (P x N), non-negative.}

\item{A}{Covariate matrix (K x N). Default is a row of ones (intercept only).}

\item{rank}{Integer. Rank of the basis matrix \eqn{X}. Default is 2.
For backward compatibility, \code{Q} is accepted via \code{...}.}

\item{df.rate}{Rate for computing the dfU cap (\code{cap = rate * N * Q}).
For backward compatibility, \code{dfU.cap.rate} is accepted via \code{...}.
If \code{NULL} (default), runs \code{\link{nmfre.dfU.scan}} internally and
selects the minimum rate where the cap is not binding.
Use \code{\link{nmfre.dfU.scan}} beforehand to examine dfU behavior across rates
and choose an appropriate value.}

\item{wild.bootstrap}{Logical. If \code{TRUE} (default), perform wild bootstrap inference
on \eqn{\Theta}.}

\item{epsilon}{Convergence tolerance for relative change in objective (default 1e-5).}

\item{maxit}{Maximum number of iterations.  Default \code{5000}
(matches \code{\link{nmfkc}} and the other MU functions in the
package).  When the cap is hit without meeting the relative-
tolerance criterion, a \code{"maximum iterations (...) reached..."}
warning is emitted so users notice unconverged fits.}

\item{...}{Additional arguments for initialization, variance control, dfU control,
optimization, and inference settings.
\itemize{
\item \code{X.init}: Initial basis matrix (P x Q), or \code{NULL}.
When \code{NULL}, \code{\link{nmfkc}} is called internally to generate initial values.
\item \code{C.init}: Initial coefficient matrix (Q x K), or \code{NULL}.
When \code{NULL}, \code{\link{nmfkc}} is called internally to generate initial values.
\item \code{U.init}: Initial random effects matrix (Q x N), or \code{NULL} (all zeros).
\item \code{prefix}: Prefix for basis names (default \code{"Basis"}).
\item \code{sigma2}: Initial residual variance (default 1).
\item \code{sigma2.update}: Logical. Update \eqn{\sigma^2} during iterations (default \code{TRUE}).
\item \code{tau2}: Initial random effect variance (default 1).
\item \code{tau2.update}: Logical. Update \eqn{\tau^2} by moment matching (default \code{TRUE}).
Disabled when dfU cap is active.
\item \code{dfU.control}: Either \code{"cap"} (default) to enforce a cap on dfU,
or \code{"off"} for no cap.
\item \code{print.trace}: Logical. If \code{TRUE}, print progress every 100 iterations (default \code{FALSE}).
\item \code{seed}: Integer seed for reproducibility (default 1).
\item \code{C.p.side}: P-value sidedness: \code{"one.sided"} (default, for boundary null
H0: C=0 vs H1: C>0) or \code{"two.sided"}.
\item \code{wild.B}: Number of wild bootstrap replicates (default 500).
\item \code{wild.seed}: Seed for wild bootstrap (default 123).
}}
}
\value{
A list of class \code{"nmfre"} with components.
The model is \eqn{Y = X(\Theta A + U) + \mathcal{E}}.

\strong{Core matrices}
\describe{
\item{\code{X}}{Basis matrix \eqn{X} (\eqn{P \times Q}), columns normalized to sum to 1.}
\item{\code{C}}{Coefficient matrix \eqn{\Theta} (\eqn{Q \times K}).}
\item{\code{U}}{Random effects matrix \eqn{U} (\eqn{Q \times N}).}
}

\strong{Variance components}
\describe{
\item{\code{sigma2}}{Residual variance \eqn{\hat{\sigma}^2}.}
\item{\code{tau2}}{Random effect variance \eqn{\hat{\tau}^2}.}
\item{\code{lambda}}{Ridge penalty \eqn{\lambda = \sigma^2 / \tau^2}.}
}

\strong{Convergence diagnostics}
\describe{
\item{\code{converged}}{Logical. Whether the algorithm converged.}
\item{\code{stop.reason}}{Character string describing why iteration stopped.}
\item{\code{iter}}{Number of iterations performed.}
\item{\code{maxit}}{Maximum iterations setting used.}
\item{\code{epsilon}}{Convergence tolerance used.}
\item{\code{objfunc}}{Final objective function value
\eqn{\|Y - X(\Theta A + U)\|^2 + \lambda \|U\|^2}.}
\item{\code{rel.change.final}}{Final relative change in objective.}
\item{\code{objfunc.iter}}{Numeric vector of objective values per iteration.}
\item{\code{rss.trace}}{Numeric vector of \eqn{\|Y - X(\Theta A + U)\|^2} per iteration.}
}

\strong{Effective degrees of freedom (dfU) diagnostics}
\describe{
\item{\code{dfU}}{Final effective degrees of freedom
\eqn{\mathrm{df}_U = N \sum_q d_q / (d_q + \lambda)},
where \eqn{d_q} are eigenvalues of \eqn{X'X}.}
\item{\code{dfU.cap}}{Upper bound imposed on \eqn{\mathrm{df}_U}.}
\item{\code{dfU.cap.rate}}{Rate used to compute the cap.}
\item{\code{dfU.cap.scan}}{Result of \code{\link{nmfre.dfU.scan}}, or \code{NULL}.}
\item{\code{lambda.enforced}}{Final \eqn{\lambda} enforced to satisfy the cap.}
\item{\code{dfU.hit.cap}}{Logical. Whether the cap was binding.}
\item{\code{dfU.hit.iter}}{Iteration at which the cap first bound.}
\item{\code{dfU.frac}}{\eqn{\mathrm{df}_U / (NQ)}, fraction of maximum df.}
\item{\code{dfU.cap.frac}}{\eqn{\mathrm{df}_U^{\mathrm{cap}} / (NQ)}.}
}

\strong{Fitted matrices}
\describe{
\item{\code{B}}{Fixed-effect scores \eqn{\Theta A} (\eqn{Q \times N}).}
\item{\code{B.prob}}{Column-normalized probabilities from
\eqn{\max(\Theta A, 0)}.}
\item{\code{B.blup}}{BLUP scores \eqn{\Theta A + U} (\eqn{Q \times N}).}
\item{\code{B.blup.pos}}{Non-negative BLUP scores
\eqn{\max(\Theta A + U, 0)} (\eqn{Q \times N}).}
\item{\code{B.blup.prob}}{Column-normalized probabilities from
\eqn{\max(\Theta A + U, 0)}.}
\item{\code{XB}}{Fitted values from fixed effects
\eqn{X \Theta A} (\eqn{P \times N}).}
\item{\code{XB.blup}}{Fitted values including random effects
\eqn{X(\Theta A + U)} (\eqn{P \times N}).}
}

\strong{Fit statistics}
\describe{
\item{\code{r.squared}}{Pearson \eqn{\mathrm{cor}(Y, X(\Theta A + U))^2}
(BLUP prediction).}
\item{\code{r.squared.uncentered}}{Uncentered
\eqn{1 - \|Y - X(\Theta A + U)\|_F^2 / \|Y\|_F^2} (BLUP;
baseline = zero matrix).}
\item{\code{r.squared.centered}}{Row-mean centered
\eqn{1 - \|Y - X(\Theta A + U)\|_F^2 / \|Y - \bar Y_{p\cdot}\|_F^2}
(BLUP; baseline = per-row mean).}
\item{\code{r.squared.fixed}}{Pearson \eqn{\mathrm{cor}(Y, X\Theta A)^2}
(fixed-only prediction).}
\item{\code{r.squared.fixed.uncentered}, \code{r.squared.fixed.centered}}{Uncentered
and centered \eqn{R^2} for the fixed-only prediction.}
\item{\code{ICC}}{Trace-based Intraclass Correlation Coefficient.
In the NMF-RE model, the conditional covariance of the \eqn{n}-th
observation column is
\eqn{\mathrm{Var}(Y_n) = \tau^2 X X^\top + \sigma^2 I_P},
a \eqn{P \times P} matrix. Unlike a standard random intercept model
where the design matrix \eqn{Z} is a simple indicator (so the ICC
reduces to \eqn{\tau^2 / (\sigma^2 + \tau^2)}), the basis matrix
\eqn{X} plays the role of \eqn{Z} in a random slopes model,
making the variance contribution of \eqn{U} depend on \eqn{X}.
To obtain a scalar summary, we take the trace of each component:
\deqn{\mathrm{ICC} = \frac{\tau^2 \, \mathrm{tr}(X^\top X)}
      {\tau^2 \, \mathrm{tr}(X^\top X) + \sigma^2 P}.}
This equals the average (over \eqn{P} dimensions) proportion of
per-column variance attributable to the random effects.}
}

\strong{Inference on \eqn{\Theta} (wild bootstrap)}
\describe{
\item{\code{sigma2.used}}{\eqn{\hat{\sigma}^2} used for inference.}
\item{\code{C.vec.cov}}{Variance-covariance matrix for
\eqn{\mathrm{vec}(\Theta)} (\eqn{QK \times QK}).}
\item{\code{C.se}}{Standard error matrix for \eqn{\Theta} (\eqn{Q \times K}).}
\item{\code{C.se.hess}}{Sandwich (Hessian-based) SE matrix for \eqn{\Theta}.}
\item{\code{C.se.boot}}{Bootstrap SE matrix for \eqn{\Theta}.}
\item{\code{coefficients}}{Data frame with columns Estimate, Std. Error, z value,
Pr(>|z|), and confidence interval bounds for each element of \eqn{\Theta}.}
\item{\code{C.ci.lower}}{Lower confidence interval matrix for \eqn{\Theta} (\eqn{Q \times K}).}
\item{\code{C.ci.upper}}{Upper confidence interval matrix for \eqn{\Theta} (\eqn{Q \times K}).}
\item{\code{C.boot.sd}}{Bootstrap standard deviation matrix for \eqn{\Theta} (\eqn{Q \times K}).}
\item{\code{C.p.side}}{P-value sidedness used: \code{"one.sided"} or \code{"two.sided"}.}
}
}
\description{
Estimates the NMF-RE model
\deqn{Y = X(\Theta A + U) + \mathcal{E}}
where \eqn{Y} (\eqn{P \times N}) is a non-negative observation matrix,
\eqn{X} (\eqn{P \times Q}) is a non-negative basis matrix learned from the data,
\eqn{\Theta} (\eqn{Q \times K}) is a non-negative coefficient matrix capturing
systematic covariate effects on latent scores,
\eqn{A} (\eqn{K \times N}) is a covariate matrix, and
\eqn{U} (\eqn{Q \times N}) is a random effects matrix capturing
unit-specific deviations in the latent score space.

NMF-RE can be viewed as a mixed-effects latent-variable model defined on a
reconstruction (mean) structure. The non-negativity constraint on \eqn{X}
induces sparse, parts-based loadings, achieving measurement-side variable
selection without an explicit sparsity penalty. Inference on \eqn{\Theta}
provides covariate-side variable selection by identifying which covariates
significantly affect which components.

Estimation alternates ridge-type BLUP-like closed-form updates for \eqn{U}
with multiplicative non-negative updates for \eqn{X} and \eqn{\Theta}.
The effective degrees of freedom consumed by \eqn{U} are monitored and a
df-based cap can be enforced to prevent near-saturated fits.

When \code{wild.bootstrap = TRUE}, inference on \eqn{\Theta} is performed
conditional on \eqn{(\hat{X}, \hat{U})} via asymptotic linearization,
a one-step Newton update, and a multiplier (wild) bootstrap, yielding
standard errors, z-values, p-values, and confidence intervals without
repeated constrained re-optimization.
}
\examples{
# Example 1. cars data
Y <- matrix(cars$dist, nrow = 1)
A <- rbind(intercept = 1, speed = cars$speed)
res <- nmfre(Y, A, rank = 1, maxit = 5000)
summary(res)

\donttest{
# Example 2. Orthodont data (nlme)
if (requireNamespace("nlme", quietly = TRUE)) {
  Y <- matrix(nlme::Orthodont$distance, 4, 27)
  male <- ifelse(nlme::Orthodont$Sex[seq(1, 108, 4)] == "Male", 1, 0)
  A <- rbind(intercept = 1, male = male)

  # Scan dfU cap rates to choose an appropriate value
  nmfre.dfU.scan(1:10/10, Y, A, rank = 1)

  # Fit with chosen rate
  res <- nmfre(Y, A, rank = 1, df.rate = 0.2)
  summary(res)
}}

}
\references{
Satoh, K. (2026). Wild Bootstrap Inference for Non-Negative Matrix
Factorization with Random Effects. arXiv:2603.01468.
\url{https://arxiv.org/abs/2603.01468}
}
\seealso{
\code{\link{nmfre.inference}}, \code{\link{nmfre.dfU.scan}},
\code{\link{nmfkc.DOT}}, \code{\link{summary.nmfre}}
}
