Skip to contents

Control fitting and fitted-object storage

Source: R/control.R
drm_control.Rd

drm_control() collects optimizer settings and storage choices for drmTMB(). Use optimizer for settings passed to stats::nlminb(), or optimizer_preset for named nlminb() budgets that keep ordinary defaults fast while making complex refits easier to write. Use the storage flags when a fitted object should keep less R-side state, for example during large-data experiments where the original data frame and TMB automatic-differentiation object are expensive to retain.

Usage

drm_control(
  optimizer = list(),
  se = TRUE,
  keep_data = TRUE,
  keep_model_frame = TRUE,
  keep_tmb_object = TRUE,
  sparse_fixed = FALSE,
  aggregate_gaussian = FALSE,
  optimizer_preset = c("default", "careful", "robust")
)

Arguments

optimizer

Named list passed to the control argument of stats::nlminb().

se

Logical; compute standard errors and fixed-effect covariance with TMB::sdreport() after optimization. Set to FALSE to keep fitted coefficients, fitted values, residuals, predictions, simulations, and profile-likelihood paths while skipping Wald standard errors, stats::vcov(), and Wald confidence intervals.

keep_data

Logical; keep the complete-case model data in the fitted object. Set to FALSE to drop fit$data and fit$model$data after fitting. Prediction, fitted values, residuals, simulation, and basic summaries still use the stored model matrices and response vectors.

keep_model_frame

Logical; keep model frames in the fitted object. Set to FALSE to drop fit$model$model_frame and random-effect scale model frames after fitting. Prediction, fitted values, residuals, simulation, sigma(), rho12(), corpairs(), and check_drm() use stored model matrices, terms, response vectors, offsets, and response-name metadata.

keep_tmb_object

Logical; keep the TMB automatic-differentiation object in fit$obj. Set to FALSE to reduce fitted-object size after optimization. check_drm() will then report the fixed-gradient check as a note because it cannot re-evaluate the gradient without fit$obj.

sparse_fixed

Logical; opt-in control for sparse fixed-effect design matrices. The first fitted path is limited to univariate Gaussian mu fixed effects with no random effects and intercept-only sigma.

aggregate_gaussian

Logical; opt-in control for sufficient- statistic row aggregation in univariate Gaussian fixed-effect models. The first fitted path rejects random effects, structured effects, known sampling covariance, bivariate models, non-Gaussian families, non-unit likelihood weights, and combined sparse fixed-effect matrices.

optimizer_preset

Optimizer-budget preset. "default" adds no optimizer controls, "careful" sets iter.max = 1000 and eval.max = 1000, and "robust" sets iter.max = 5000 and eval.max = 5000.

Value

A drm_control object.

Details

For optimizer-only settings, control = list(eval.max = 1000) remains valid. When using drm_control(), put optimizer arguments inside optimizer = list(...); do not pass eval.max directly to drm_control(). Presets "careful" and "robust" expand to explicit iter.max and eval.max controls for nlminb(). Values in optimizer override values from the selected preset.

Examples

dat <- data.frame(y = rnorm(20), x = rnorm(20))
fit <- drmTMB(
  bf(y ~ x, sigma ~ 1),
  data = dat,
  control = drm_control(
    optimizer_preset = "careful",
    se = FALSE,
    keep_data = FALSE,
    keep_model_frame = FALSE,
    keep_tmb_object = FALSE
  )
)