Scan dfU cap rates for NMF-RE

Fits the NMF-RE model across a range of 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 \(U\). The cap is computed as rate * N * Q, where \(N\) is the number of observations and \(Q\) is the rank. A suitable rate is one where the final \(\mathrm{df}_U\) is below the cap (safeguard = TRUE) and the model has converged (converged = TRUE).

When called automatically by nmfre (i.e., dfU.cap.rate = NULL), the minimum rate satisfying both safeguard = TRUE and converged = TRUE is selected.

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

rates

Numeric vector of cap rates to scan (default (1:10)/10).

Y

Observation matrix (P x N).

A

Covariate matrix (K x N).

rank

Integer. Rank of the basis matrix. For backward compatibility, Q is accepted via ....

X.init

Initial basis matrix, or NULL.

C.init

Initial coefficient matrix, or NULL.

U.init

Initial random effects matrix, or NULL.

print.trace

Logical. Print progress for each fit (default FALSE).

...

Additional arguments passed to nmfre.

Value

An object of class "nmfre.dfU.scan" with two components:

table

A data frame with the following columns:

rate

Cap rate used. The dfU cap is rate * N * Q.

dfU.cap

The dfU cap value (upper bound on effective degrees of freedom).

dfU

Final effective degrees of freedom for \(U\) at convergence.

safeguard

Logical. TRUE if the dfU cap is functioning as a safeguard (dfU / dfU.cap < 0.99): the cap prevents random-effects saturation without over-constraining \(U\). FALSE if dfU is at or near the cap, indicating the cap is binding and the rate may be too small.

hit

Logical. TRUE if the cap was reached at least once during iteration, even if dfU later decreased below the cap.

converged

Logical. TRUE if the algorithm converged within the maximum number of iterations.

tau2

Final random effect variance \(\hat{\tau}^2\).

sigma2

Final residual variance \(\hat{\sigma}^2\).

ICC

Trace-based Intraclass Correlation Coefficient \(\tau^2 \, \mathrm{tr}(X^\top X) / (\tau^2 \, \mathrm{tr}(X^\top X) + \sigma^2 P)\). See nmfre for details.

cap.rate

Optimal cap rate selected automatically. If rows with safeguard = TRUE and hit = TRUE exist, the maximum rate among them is chosen (safeguard activated but giving \(U\) the most freedom). Otherwise, the minimum rate with safeguard = TRUE and hit = FALSE is chosen. NA if no suitable rate is found.

When printed, only the table is displayed. Access cap.rate directly from the returned object.

See also

nmfre

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)
#>   rate dfU.cap dfU safeguard  hit converged  tau2 sigma2 ICC
#> 1  0.1       5   5     FALSE TRUE      TRUE 0.111      1 0.1
#> 2  0.2      10  10     FALSE TRUE      TRUE 0.250      1 0.2

# \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)
}# }
#>    rate dfU.cap  dfU safeguard   hit converged  tau2 sigma2    ICC
#> 1   0.1     2.7 2.70     FALSE  TRUE      TRUE 0.443      1 0.0270
#> 2   0.2     5.4 5.40     FALSE  TRUE      TRUE 0.996      1 0.0588
#> 3   0.3     8.1 5.42      TRUE FALSE      TRUE 1.000      1 0.0590
#> 4   0.4    10.8 5.42      TRUE FALSE      TRUE 1.000      1 0.0590
#> 5   0.5    13.5 5.42      TRUE FALSE      TRUE 1.000      1 0.0590
#> 6   0.6    16.2 5.42      TRUE FALSE      TRUE 1.000      1 0.0590
#> 7   0.7    18.9 5.42      TRUE FALSE      TRUE 1.000      1 0.0590
#> 8   0.8    21.6 5.42      TRUE FALSE      TRUE 1.000      1 0.0590
#> 9   0.9    24.3 5.42      TRUE FALSE      TRUE 1.000      1 0.0590
#> 10  1.0    27.0 5.42      TRUE FALSE      TRUE 1.000      1 0.0590