Run Jitter Analysis for Model Diagnostics

Performs a jitter analysis to evaluate sensitivity of model optimization to starting parameter values. The function repeatedly perturbs the parameter vector with additive normal noise, refits the model, and records resulting time series and diagnostic metrics.

Usage

do_jitter(
  data,
  parameters,
  mapping,
  random = NULL,
  sd,
  n_jitter,
  n_newton_loops = 0,
  do_par,
  n_cores,
  par_vec = NULL,
  jitter_random = FALSE
)

Arguments

data

A list of model data used to construct the RTMB objective function.

parameters

A named list of model parameters used to initialize RTMB::MakeADFun().

mapping

A named list defining parameter mappings for RTMB::MakeADFun().

random

Character vector specifying random-effect parameters.

sd

Numeric value specifying the standard deviation of the additive normal noise used to jitter parameters.

n_jitter

Integer specifying the number of jittered optimization runs.

n_newton_loops

Integer specifying the number of additional Newton optimization steps performed after nlminb() convergence. Default = 0.

do_par

Logical indicating whether jitter iterations should be executed in parallel.

n_cores

Integer specifying the number of parallel workers to use when do_par = TRUE.

par_vec

Optional numeric vector of starting values to jitter. Accepts either the fixed-effect vector (length(obj$par), for example fit$optim$par) or the joint fixed and random vector (length(obj$env$par), for example fit$env$last.par.best). Any other length is an error. NULL uses the model's own start.

jitter_random

Logical indicating whether the random effects are perturbed alongside the fixed effects. Only the fixed effects are searched by nlminb(), so the random draws move the starting point of the inner Laplace solve and check whether it settles on the same modes. Either way the inner solve starts from the random values in par_vec, or from the model's own start when par_vec holds no random effects. Default is FALSE.

Value

A data.frame containing jitter iteration results. The output includes time series of spawning stock biomass (SSB) and recruitment, along with diagnostic information for each jitter run, including:

• Jitter index

• Whether the Hessian is positive definite

• Joint negative log-likelihood

• Maximum absolute gradient of fixed effects

Details

Each jitter iteration:

• Perturbs the fixed effects with additive normal noise, and the random effects too when jitter_random = TRUE.

• Optimizes the objective function using stats::nlminb().

• Optionally performs additional Newton steps to refine the solution.

• Extracts reported quantities (e.g., spawning biomass and recruitment) and diagnostic statistics.

The analysis can be executed sequentially or in parallel using the future framework.

See also

Other Model Diagnostics: do_likelihood_profile(), do_retrospective(), do_runs_test(), get_catch_fits_plot(), get_comp_prop(), get_idx_fits(), get_idx_fits_plot(), get_model_rep_from_mcmc(), get_nLL_plot(), get_osa(), get_retrospective_plot(), get_retrospective_relative_difference(), plot_resids()