Check numerical convergence and model diagnostics

Reviews one or more fitted models' optimization, uncertainty, formula designs and residual patterns. Numerical convergence, known structural problems and advisory findings are reported separately. A converged model can still have weakly estimated parameters or unsuitable biological assumptions.

Usage

check_tam(fit, ..., grad_tol = NULL, detailed = FALSE, model_list = NULL)

# S3 method for class 'tam_check'
print(x, ...)

# S3 method for class 'tam_checks'
print(x, ...)

Arguments

fit: A fitted tam_fit object. May be omitted when supplying models through named ... arguments or model_list.
...: Additional fitted tam_fit objects. Names label the models; unnamed models use their expression names. Unused by the print methods.
grad_tol: Positive gradient tolerance. NULL uses the tolerance stored in the fit.
detailed: Examine covariance eigenvalues and weak parameter directions?
model_list: Optional named list of fitted tam_fit objects. Supply this or individual models, not both.
x: A tam_check or tam_checks object.

Value

For one individual model, a tam_check list with is_converged, numerical, structural, structural_status, advisories, residuals, data, and curvature. numerical records pass, fail or not-assessed status for each check. Calling this function does not modify the fit or emit warnings; its print method displays the findings. Multiple models, or an explicit model_list (even with one model), return a tam_checks named list of these results. Its print method shows each model's findings under its name. Access a model with checks[["Base"]].

Details

Numerical checks require optimizer success, finite estimates and predictions, a sufficiently small gradient, and successful uncertainty calculation with a positive-definite Hessian. At an active parameter bound, the gradient is adjusted for the direction in which the parameter is allowed to move. Both raw and adjusted gradients are retained.

Structural checks look for redundant formula coefficients. Passing these checks does not prove that abundance, mortality and catchability are distinguishable from the available data. Advisory findings include strong parameter correlations, variance or correlation boundaries, sparse data and standardized residual patterns. These do not change numerical convergence. Residual summaries exclude projections and missing or zero observations. Standardized residuals depend on fitted states and their shrinkage; they are not independent tests of the assumed observation distribution.

By default the function uses information already available in the fit and does not refit the model. detailed = TRUE also examines the fixed-parameter covariance eigenvalues and weakly supported parameter combinations. Profiles, one-step residuals, simulations and retrospectives are separate investigations. Mortality-mean advisories highlight jointly estimated M mean/residual variation and F/M mean variation. Formula-effect advisories flag 95% AR1 correlation intervals wider than 0.5 and process-SD intervals spanning more than a factor of ten, including catchability effects. With M random slopes, these interval checks also cover the residual M SD and age-block/year AR1 correlations. Catchability groups with fewer than five observed effect levels are flagged when process SD or correlation is estimated. Observation-specific IID effects with estimated observation SD receive a caution under the logit link; exact log-link variance aliases are rejected before fitting. Logistic curves are flagged when the fitted midpoint is outside the observed age/size range and its 95% interval is wider than that range. Stock-recruit advisories flag limited parent-SSB contrast, wide curve or AR1 intervals, and absolute correlation above 0.5 between adjacent recruitment innovations when at least 15 historical innovations are available. The first stationary AR1 residual is excluded. Innovations depend on fitted states; this check can reveal an unsuitable residual process but does not establish or rule out a biological stock-recruit relationship. These descriptive thresholds identify imprecise estimates; they do not prove a structural problem or change the convergence criteria.

Supply fitted models individually, as in check_tam(base, alternative), or use a named model_list. Models are checked separately, without ranking or requiring matching observations. An omitted grad_tol uses each model's own stored tolerance. A supplied tolerance and detailed apply to every model.

Examples

if (FALSE) { # \dontrun{
checks <- check_tam(fit)
checks$is_converged
checks$residuals
check_tam(fit, detailed = TRUE)
check_tam(fit, alternative)
checks <- check_tam(model_list = list(Base = fit, Alternative = alternative))
checks$Base$is_converged
} # }