Control fitting and fitted-object storage

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,
  se_report_covariance = TRUE,
  se_skip_delta_method = FALSE,
  se_group_sd = FALSE,
  keep_data = TRUE,
  keep_model_frame = TRUE,
  keep_tmb_object = TRUE,
  sparse_fixed = FALSE,
  aggregate_gaussian = FALSE,
  logsigma_clamp = c(-12, 12),
  logsigma_clamp_margin = 3,
  optimizer_preset = c("default", "careful", "robust"),
  multi_start = 1L,
  fallback_optimizer = NULL
)

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. Profile-likelihood intervals still require keep_tmb_object = TRUE.
se_report_covariance: Logical; passed to the getReportCovariance argument of TMB::sdreport(). The default TRUE builds the full covariance matrix of every ADREPORTed quantity. Models with a direct-SD surface (sd_phylo(...) ~ .) report one standard deviation per group, so this matrix is n_group x n_group and its memory cost grows with the square of the number of groups; at ten thousand tips it dominates the fit. Set to FALSE to keep per-quantity standard errors while skipping their joint covariance.
se_skip_delta_method: Logical; passed to the skip.delta.method argument of TMB::sdreport(). Set to TRUE to skip standard errors for ADREPORTed quantities entirely while retaining fixed-effect standard errors and stats::vcov(). This is the cheapest route to Wald inference on the fixed effects for large structured models.
se_group_sd: Logical; report delta-method standard errors for the per-group direct-SD surface (sd_phylo(...) ~ .). Defaults to FALSE. The surface has one standard deviation per group, so ADREPORTing it makes the joint ADREPORT covariance n_group x n_group. Under REML = TRUE the fixed effects are integrated into the Laplace random block and stats::vcov() reads exactly that joint covariance, so at ten thousand tips a bivariate fit needs tens of gigabytes for it. The fitted per-group standard deviations themselves are always available (they are recomputed from the parameters); only their standard errors are opt-in. Set to TRUE to restore the pre-0.3.0 behaviour.
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, and profile-likelihood confidence intervals will be unavailable.
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.
logsigma_clamp: Numeric c(lo, hi) band, or NULL. Bounds the per-observation Gaussian log(sigma) with an identity-in-band soft-clamp, a numerical guard against scale overflow on near-degenerate per-group scale models. The default c(-12, 12) is identity for any standardized response; widen it for legitimately huge-variance unstandardized data, or set NULL to disable the guard entirely. It is a numerical guard only and does not change identifiability.
logsigma_clamp_margin: Positive number; the soft-clamp saturation margin beyond logsigma_clamp (default 3, saturating to [-15, 15] for the default band). Ignored when logsigma_clamp = NULL.
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. The optimizer escalates this ladder automatically when a preset does not converge.
multi_start: Whole number >= 1 (default 1). With multi_start > 1, each optimizer preset is run from multi_start starting points – the principled start plus reproducibly perturbed starts – and the lowest- objective result is kept. Opt-in robustness for weakly identified models; multi_start = 1 is the single-start fit and is unchanged.
fallback_optimizer: NULL (default) or one stats::optim() method ("BFGS", "L-BFGS-B", "Nelder-Mead", "CG"). When set, and no nlminb() preset converges, drmTMB() tries this optimizer as a final attempt; a different algorithm can succeed on a numerically awkward but identified problem. Opt-in; NULL keeps the nlminb()-only ladder.

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.

When the selected preset uses the standard nlminb() budget and no explicit optimizer controls, drmTMB() escalates the preset ladder ("default" -> "careful" -> "robust") when an attempt either raises an error (such as a non-finite gradient) or does not converge cleanly (a nonzero convergence code or a non-finite objective). The first cleanly-converged attempt is returned; if no preset converges, the best (lowest-objective) attempt is returned and the fit-time convergence warning flags it. Every attempted preset is recorded in fit$optimizer_attempts and the selected one in fit$optimizer_used.

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
  )
)