robustlmm-options: Global options consulted by 'robustlmm'

In robustlmm: Robust Linear Mixed Effects Models

Global options consulted by robustlmm

Description

robustlmm reads a small number of global options, set with options() and queried with getOption(). With one experimental exception (the Monte-Carlo DAS-tau calibration below), none of them change the fitted estimates; they only tune optional diagnostics and the default behaviour of summary (see rlmerMod-class).

Degrees-of-freedom options

These control whether summary(object) computes the robust Satterthwaite degrees of freedom and Pr(>|t|) column by default (df = "auto"); see the “Coefficient-table degrees of freedom” section of rlmerMod-class.

robustlmm.summary.df.max

Numeric, default 5000. The size cutoff for computing the Satterthwaite df under df = "auto". The cost of the df is a deterministic dimension-only “workload” W – one O(n) score evaluation per parameter-Jacobian column: W = (p + q + 1 + L) n for method "DASvar" and W = 40\,L\,n for "DAStau", where n is the number of observations, p the number of fixed effects, q the number of random effects and L the number of variance parameters. If W exceeds this cutoff and no influence function is cached on the fit, summary falls back to the plain Estimate / Std. Error / t value table and prints a note. The rule is dimensionless, so the same fit behaves identically on every machine. The default 5000 computes the df by default up to about n = 170 for a single random intercept fit with "DASvar" (n = 125 for "DAStau"). Set it higher to show the df on larger fits, or to 0 to always skip the automatic computation (you can still request it with summary(object, df = "satterthwaite")).

Monte-Carlo DAS-tau calibration (EXPERIMENTAL)

These options enable and tune an experimental Monte-Carlo calibration of the DAS-tau fixed point in rlmer. Without it, method = "DAStau" computes the consistency factors for non-diagonal random-effect blocks by Gauss-Hermite quadrature, which is limited to blocks of dimension \le 2; fits containing a larger block fall back to method = "DASvar" with a warning. The Monte-Carlo path lifts this restriction: it computes the same self-consistent fixed point by plain Monte-Carlo integration, which works for any block dimension, including structured (cs/ar1) and unstructured blocks of dimension > 2. It is simulation-validated – in the companion ar1 simulation study it removes the small calibration residual that the DASvar approximation leaves in the fitted correlation – but it is not backed by a finite-sample theorem, and it has been validated on clean Gaussian data only. For blocks of dimension \le 2 the classical quadrature path remains the default and the Monte-Carlo path offers no improvement there.

robustlmm.dastau.mc

Logical, default FALSE. Master switch. When TRUE, method = "DAStau" uses the Monte-Carlo calibration for all non-diagonal random-effect blocks of dimension > 2 (instead of falling back to "DASvar" for the whole fit). The Monte-Carlo sample is drawn once per fit (common random numbers), deterministically seeded and moment-matched to exact zero mean and identity second moment, so repeated fits are identical and the caller's .Random.seed is left untouched. rlmer emits a message when the experimental path is active.

robustlmm.dastau.mc.all

Logical, default FALSE. Research switch: also use the Monte-Carlo path for blocks of dimension 2, replacing the Gauss-Hermite quadrature. Intended only for comparing the two calibration paths; it offers no improvement over the quadrature.

robustlmm.dasmc.nsim

Integer, default 1e5. Number of Monte-Carlo draws. Larger values reduce the (deterministic, seed-dependent) residual calibration error at linear cost in time and memory.

robustlmm.dasmc.seed

Integer, default 20260703. Seed for the common-random-numbers draw. Fits are deterministic given this option; change it (e.g. per replicate in a simulation) to decorrelate the residual Monte-Carlo calibration error across fits. The global RNG state is saved and restored around the draw.

Developer options

robustlmm.check_rhs_optimisation

Logical, default FALSE. When TRUE, rlmer cross-checks the vectorised right-hand-side computation in the block-diagonal \theta update against an explicit per-block loop and stops on any discrepancy. Intended for development and debugging only; it adds redundant work and is not needed in normal use.

See Also

rlmerMod-class, rlmer

Examples

## show the df on larger fits (raise the size cutoff)
## Not run: 
options(robustlmm.summary.df.max = 20000)

## End(Not run)

robustlmm documentation built on July 30, 2026, 5:11 p.m.