Tidy observed, predicted, and residual diagnostics

Extracts observations, predictions, and observation SDs for catch and index from a fitted TAM object, and adds standardized residuals on the log scale.

Usage

tidy_obs_pred(
  fit,
  add_osa_res = FALSE,
  interval = 0.95,
  method = "oneStepGaussianOffMode",
  ...
)

Arguments

fit: A fitted TAM object as returned by fit_tam().
add_osa_res: Logical; calculate one-step-ahead residuals?
interval: Confidence level for combined catchability intervals.
method: OSA algorithm; defaults to "oneStepGaussianOffMode". See add_osa_residuals() for supported choices and computation details.
...: Arguments to pass to RTMB::oneStepPredict().

Value

A named list with two data frames:

catch: original columns plus pred, sd, and std_res.
index: original columns plus pred, sd, q, and std_res. Combined catchability intervals are q_lwr/q_upr; q_se is on the selected link scale named in q_se_scale. They include uncertainty across the full formula, rather than combining separate coefficient SEs. With power(), q remains effective catchability. Additional q_base, q_power, and q_base_lwr/q_base_upr/q_base_se columns separate the baseline and exponent. Baseline-q SEs are on the log scale. Its unit is unspecified for active power groups because it depends on p and abundance units.

Details

pred is the conditional median on the natural scale. sd is the fitted SD of log observations, not a standard error of the prediction. Standardized residuals are (log(obs) - log(pred)) / sd; zero and missing observations have missing residuals. These standardized residuals do not account for the uncertainty in fitted states. Optional one-step-ahead residuals use a different predictive calculation. See tinyAM-model for the observation equations. OSA calculation rebuilds a temporary objective at stored fitted parameters; it does not refit fixed parameters or modify the fitted objective. With add_osa_res = TRUE, it computes the requested method afresh and records its settings and observation coverage. osa_method identifies the algorithm beside osa_res. To retain diagnostics while preserving existing observation tables and confidence intervals, use add_osa_residuals(). When stockassessment is loaded, one-step residuals run sequentially: the upstream TMB parallel helper cannot select between SAM and RTMB libraries.

Examples

fit <- fit_tam(
  cod_obs,
  years = 1983:2024,
  ages = 2:14,
  N_settings = list(process = "iid", init = "exp"),
  F_settings = list(process = "rw", mu_form = NULL),
  M_settings = list(process = "off", mu_supplied = ~ I(0.3)),
  catch_settings = list(sd_form = ~ 1),
  index_settings = list(sd_form = ~ 1, q_form = ~ q_block),
  silent = TRUE
)
obs_pred <- tidy_obs_pred(fit)
head(obs_pred$catch)
#>     year age obs          unit F_y_block F_a_block is_proj      pred        sd
#> 174 1983   2  18 thousand fish 1954-1991       2-3   FALSE 13.281992 0.3814101
#> 175 1984   2   3 thousand fish 1954-1991       2-3   FALSE  4.438363 0.3814101
#> 176 1985   2   0 thousand fish 1954-1991       2-3   FALSE  2.539587 0.3814101
#> 177 1986   2   1 thousand fish 1954-1991       2-3   FALSE  2.211582 0.3814101
#> 178 1987   2  42 thousand fish 1954-1991       2-3   FALSE 18.146481 0.3814101
#> 179 1988   2  25 thousand fish 1954-1991       2-3   FALSE 21.066685 0.3814101
#>        std_res
#> 174  0.7969445
#> 175 -1.0269088
#> 176         NA
#> 177 -2.0809837
#> 178  2.2002381
#> 179  0.4488161
head(obs_pred$index)
#>     year age      obs     survey samp_time q_block          unit is_proj
#> 612 1983   2 698822.0 Fall 2J3KL       0.8       2 thousand fish   FALSE
#> 633 1984   2 685850.3 Fall 2J3KL       0.8       2 thousand fish   FALSE
#> 654 1985   2 128102.7 Fall 2J3KL       0.8       2 thousand fish   FALSE
#> 675 1986   2 178331.8 Fall 2J3KL       0.8       2 thousand fish   FALSE
#> 696 1987   2 144096.3 Fall 2J3KL       0.8       2 thousand fish   FALSE
#> 717 1988   2 227219.7 Fall 2J3KL       0.8       2 thousand fish   FALSE
#>         pred        sd        q   q_unit      q_se    q_upr   q_lwr q_se_scale
#> 612 669326.5 0.4282125 1.751148 unitless 0.1739374 2.462513 1.24528        log
#> 633 371895.6 0.4282125 1.751148 unitless 0.1739374 2.462513 1.24528        log
#> 654 183755.3 0.4282125 1.751148 unitless 0.1739374 2.462513 1.24528        log
#> 675 138185.2 0.4282125 1.751148 unitless 0.1739374 2.462513 1.24528        log
#> 696 259546.9 0.4282125 1.751148 unitless 0.1739374 2.462513 1.24528        log
#> 717 280768.8 0.4282125 1.751148 unitless 0.1739374 2.462513 1.24528        log
#>        std_res
#> 612  0.1007073
#> 633  1.4293045
#> 654 -0.8425091
#> 675  0.5956191
#> 696 -1.3742146
#> 717 -0.4941802