% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmfre.R
\name{nmfre.dfU.scan}
\alias{nmfre.dfU.scan}
\title{Scan dfU cap rates for NMF-RE}
\usage{
nmfre.dfU.scan(
  rates = (1:10)/10,
  Y,
  A,
  rank = NULL,
  X.init = NULL,
  C.init = NULL,
  U.init = NULL,
  print.trace = FALSE,
  ...
)
}
\arguments{
\item{rates}{Numeric vector of cap rates to scan (default \code{(1:10)/10}).}

\item{Y}{Observation matrix (P x N).}

\item{A}{Covariate matrix (K x N).}

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

\item{X.init}{Initial basis matrix, or \code{NULL}.}

\item{C.init}{Initial coefficient matrix, or \code{NULL}.}

\item{U.init}{Initial random effects matrix, or \code{NULL}.}

\item{print.trace}{Logical. Print progress for each fit (default \code{FALSE}).}

\item{...}{Additional arguments passed to \code{\link{nmfre}}.}
}
\value{
An object of class \code{"nmfre.dfU.scan"} with two components:
\describe{
\item{\code{table}}{A data frame with the following columns:
\describe{
\item{\code{rate}}{Cap rate used. The dfU cap is \code{rate * N * Q}.}
\item{\code{dfU.cap}}{The dfU cap value (upper bound on effective degrees of freedom).}
\item{\code{dfU}}{Final effective degrees of freedom for \eqn{U} at convergence.}
\item{\code{safeguard}}{Logical. \code{TRUE} if the dfU cap is functioning
as a safeguard (\code{dfU / dfU.cap < 0.99}): the cap prevents
random-effects saturation without over-constraining \eqn{U}.
\code{FALSE} if dfU is at or near the cap, indicating the cap is
binding and the rate may be too small.}
\item{\code{hit}}{Logical. \code{TRUE} if the cap was reached at least once
during iteration, even if dfU later decreased below the cap.}
\item{\code{converged}}{Logical. \code{TRUE} if the algorithm converged
within the maximum number of iterations.}
\item{\code{tau2}}{Final random effect variance \eqn{\hat{\tau}^2}.}
\item{\code{sigma2}}{Final residual variance \eqn{\hat{\sigma}^2}.}
\item{\code{ICC}}{Trace-based Intraclass Correlation Coefficient
\eqn{\tau^2 \, \mathrm{tr}(X^\top X) /
      (\tau^2 \, \mathrm{tr}(X^\top X) + \sigma^2 P)}.
See \code{\link{nmfre}} for details.}
}}
\item{\code{cap.rate}}{Optimal cap rate selected automatically.
If rows with \code{safeguard = TRUE} and \code{hit = TRUE} exist,
the maximum rate among them is chosen (safeguard activated but
giving \eqn{U} the most freedom). Otherwise, the minimum rate
with \code{safeguard = TRUE} and \code{hit = FALSE} is chosen.
\code{NA} if no suitable rate is found.}
}

When printed, only the \code{table} is displayed. Access \code{cap.rate}
directly from the returned object.
}
\description{
Fits the NMF-RE model across a range of \code{dfU.cap.rate} values and
returns a diagnostic table showing the resulting effective degrees of freedom,
variance components, and convergence diagnostics for each rate.

The dfU cap limits the effective degrees of freedom consumed by the random
effects \eqn{U}. The cap is computed as \code{rate * N * Q}, where \eqn{N}
is the number of observations and \eqn{Q} is the rank. A suitable rate is
one where the final \eqn{\mathrm{df}_U} is below the cap
(\code{safeguard = TRUE}) and the model has converged
(\code{converged = TRUE}).

When called automatically by \code{\link{nmfre}} (i.e., \code{dfU.cap.rate = NULL}),
the minimum rate satisfying both \code{safeguard = TRUE} and
\code{converged = TRUE} is selected.
}
\examples{
# Example 1. cars data (small maxit for speed)
Y <- matrix(cars$dist, nrow = 1)
A <- rbind(intercept = 1, speed = cars$speed)
tab <- nmfre.dfU.scan(rates = c(0.1, 0.2), Y = Y, A = A, rank = 1, maxit = 1000)
print(tab)

\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)
  nmfre.dfU.scan(1:10/10, Y, A, rank = 1)
}}

}
\seealso{
\code{\link{nmfre}}
}
