sdmTMB() and stats::nlminb() control options.
Usage
sdmTMBcontrol(
eval.max = 2000L,
iter.max = 1000L,
normalize = deprecated(),
nlminb_loops = 1L,
newton_loops = 1L,
getsd = TRUE,
quadratic_roots = FALSE,
start = NULL,
map = NULL,
lower = NULL,
upper = NULL,
censored_method = c("auto", "direct"),
multiphase = TRUE,
profile = FALSE,
get_joint_precision = TRUE,
parallel = getOption("sdmTMB.cores", 1L),
suppress_nlminb_warnings = TRUE,
collapse_spatial_variance = FALSE,
collapse_threshold = deprecated(),
collapse_spatial_variance_threshold = 0.01,
collapse_spatiotemporal_ar1 = FALSE,
collapse_ar1_threshold = 0.01,
sar_weight_style = c("row", "raw"),
get_rsr = FALSE,
backend = deprecated(),
...
)Arguments
- eval.max
Maximum number of evaluations of the objective function allowed.
- iter.max
Maximum number of iterations allowed.
- normalize
Ignored. This used
TMB::normalize()with the removed C++ TMB backend; the RTMB densities are already fully normalized.- nlminb_loops
How many times to run
stats::nlminb()optimization. Sometimes restarting the optimizer at the previous best values aids convergence. If the maximum gradient is still too large, try increasing this to2.- newton_loops
How many Newton optimization steps to try after running
stats::nlminb(). This sometimes aids convergence by further reducing the log-likelihood gradient with respect to the fixed effects. This calculates the Hessian at the current MLE withstats::optimHess()using a finite-difference approach and uses this to update the fixed effect estimates.- getsd
Logical indicating whether to call
RTMB::sdreport().- quadratic_roots
Experimental feature for internal use right now; may be moved to a branch. Logical: should quadratic roots be calculated? Note: on the sdmTMB side, the first two coefficients are used to generate the quadratic parameters. This means that if you want to generate a quadratic profile for depth, and depth and depth^2 are part of your formula, you need to make sure these are listed first and that an intercept isn't included. For example,
formula = cpue ~ 0 + depth + depth2 + as.factor(year).- start
A named list specifying the starting values for parameters. You can see the necessary structure by fitting the model once and inspecting
your_model$tmb_obj$env$parList(). Elements ofstartthat are specified will replace the default starting values.- map
A named list with factor
NAs specifying parameter values that should be fixed at a constant value. See the documentation inRTMB::MakeADFun(). This should usually be used withstartto specify the fixed value.- lower
An optional named list of lower bounds within the optimization. Parameter vectors with the same name (e.g.,
b_jorln_kappain some cases) can be specified as a numeric vector. E.g.lower = list(b_j = c(-5, -5)). Note thatstats::optimHess()does not implement lower and upper bounds, so you must setnewton_loops = 0if setting limits.- upper
An optional named list of upper bounds within the optimization.
- censored_method
How
censored_betabinomial()sums the likelihood."auto"(default) sums the interval or its complement, whichever has fewer terms, and checks the precision at the estimate, refitting with the direct sum for any rows that fail."direct"always sums the interval, which can be much slower. The check only applies at the estimate, so consider"direct"when evaluating the likelihood far from it (e.g., MCMC sampling).- multiphase
Logical: estimate the fixed and random effects in phases? Phases are usually faster and more stable.
- profile
Logical: should population-level/fixed effects be profiled out of the likelihood? These are then appended to the random effects vector without the Laplace approximation. See
RTMB::MakeADFun(). This can dramatically speed up model fit if there are many fixed effects but is experimental at this stage.- get_joint_precision
Logical. Passed to
getJointPrecisioninRTMB::sdreport(). Must beTRUEto use simulation-based methods inpredict.sdmTMB()orget_index_sims(). If not needed, setting this toFALSEwill reduce object size.- parallel
Argument currently ignored.
- suppress_nlminb_warnings
Suppress uninformative warnings from
stats::nlminb()arising when a function evaluation isNA, which are then replaced withInfand avoided during estimation?- collapse_spatial_variance
Logical: should spatial and/or spatiotemporal random fields be automatically dropped if their estimated standard deviation is effectively zero (i.e., below
collapse_spatial_variance_threshold)? This helps prevent overfitting and numerical instability when the data provide little evidence for spatial or spatiotemporal variation, i.e., when the variance parameter is estimated on or near the boundary of zero. When enabled, the model will be automatically refitted viaupdate.sdmTMB()with the corresponding field(s) disabled. This adds the computational cost of one or more model refits if collapsing occurs but can yield a simpler, more stable model and more reliable inference. Default isFALSEfor backward compatibility.- collapse_threshold
Deprecated alias for
collapse_spatial_variance_threshold. It will be removed in a future release.- collapse_spatial_variance_threshold
Numeric: the standard deviation threshold below which random fields are considered to be collapsing to zero. Only used when
collapse_spatial_variance = TRUE. Values are on the standard deviation scale (i.e., square root of variance). Default is 0.01.- collapse_spatiotemporal_ar1
Logical: should spatiotemporal AR1 fields be automatically simplified when the estimated correlation (
rho) is near zero or one? Fields withabs(rho) <= collapse_ar1_thresholdare refitted as"iid"; fields withrho >= 1 - collapse_ar1_thresholdare refitted as"rw". This does not apply totime_varyingeffects. Default isFALSE.- collapse_ar1_threshold
Numeric: distance from zero or one at which a spatiotemporal AR1 correlation is considered to be collapsing. Must be greater than zero and less than 0.5. Only used when
collapse_spatiotemporal_ar1 = TRUE. Default is 0.01.- sar_weight_style
Weight matrix to use for areal SAR models.
"row"uses row-normalized weights and is the default."raw"uses the raw adjacency/weight matrix for direct comparisons to packages that do so.- get_rsr
Experimental option, whether to calculate the restricted spatial regression (RSR) adjusted estimator for covariate responses. If
get_rsr = TRUE, these will be available viatidy(fit, effects = "rsr"). See Hanks et al. (2015) and Diaz and Thorson (2025).- backend
Ignored. The C++ TMB backend was removed and all models use RTMB.
- ...
Anything else. See the 'Control parameters' section of
stats::nlminb().
Details
Usually used within sdmTMB(). For example:
References
Restricted Spatial Regression (get_rsr):
Diaz, R.R., and Thorson, J.T. 2025. When and How to Use Restricted Spatial Regression to Separate Environmental Effects from Spatial Confounding. EcoEvoRxiv. doi:10.32942/X28351 .
Hanks, E.M., Schliep, E.M., Hooten, M.B., and Hoeting, J.A. 2015. Restricted spatial regression in practice: geostatistical models, confounding, and robustness under model misspecification. Environmetrics 26(4): 243–254. doi:10.1002/env.2331 .
Examples
sdmTMBcontrol()
#> $eval.max
#> [1] 2000
#>
#> $iter.max
#> [1] 1000
#>
#> $nlminb_loops
#> [1] 1
#>
#> $newton_loops
#> [1] 1
#>
#> $getsd
#> [1] TRUE
#>
#> $profile
#> [1] FALSE
#>
#> $quadratic_roots
#> [1] FALSE
#>
#> $start
#> NULL
#>
#> $map
#> NULL
#>
#> $lower
#> NULL
#>
#> $upper
#> NULL
#>
#> $censored_method
#> [1] "auto"
#>
#> $multiphase
#> [1] TRUE
#>
#> $parallel
#> [1] 1
#>
#> $get_joint_precision
#> [1] TRUE
#>
#> $suppress_nlminb_warnings
#> [1] TRUE
#>
#> $collapse_spatial_variance
#> [1] FALSE
#>
#> $collapse_spatial_variance_threshold
#> [1] 0.01
#>
#> $collapse_spatiotemporal_ar1
#> [1] FALSE
#>
#> $collapse_ar1_threshold
#> [1] 0.01
#>
#> $sar_weight_style
#> [1] "row"
#>
#> $get_rsr
#> [1] FALSE
#>
