Tidy parameter estimates (fixed & random) with CIs and back-transforms

Summarizes fitted parameters with estimates, confidence limits, and clearly labelled SE scales. Use this to inspect process variability, catchability effects, and latent population states. Actual catchability for each survey observation is available from tidy_obs_pred().

Usage

tidy_par(fit, interval = 0.95)

Arguments

fit: A fitted TAM object (from fit_tam()) containing an sdrep (an RTMB::sdreport() object) and obj$env$.random (names of random effects).
interval: Confidence level for Wald intervals; default 0.95.

Value

A list with two elements:

fixed: a data frame stacking all fixed-effect parameters with columns parameter/index columns (par, coef, year, age, as applicable), then est, lwr, upr, se, se_scale, and is_proj when applicable.
random: a named list of data frames (one per random block) with the same columns as fixed (indices appropriate to each random effect).

Details

Combines estimates (Estimate) and standard errors (Std. Error) from fit$sdrep. Parameters whose names begin with log_ or logit_ are back-transformed to the natural scale:

log_ → exp() (and the log_ prefix is dropped, e.g. log_sd_r → sd_r)
logit_ → plogis() (and the logit_ prefix is dropped, e.g. logit_phi_f → phi_f)

An exception is logit_q: formula coefficients, confidence limits and SEs remain on the fitted logit scale (se_scale = "logit"). A slope or contrast is not an absolute q and must not be inverse-logit transformed on its own. Actual observation-specific q is reported by tidy_obs_pred().

Estimates and confidence limits are shown on the reported scale. SEs remain on the fitted scale, identified by se_scale: "log", "logit", or "reported" (the same scale as the displayed estimate). A small log-scale SE approximates a CV: 0.10 is approximately 10% relative uncertainty. This interpretation does not apply to logit or reported-scale SEs, and is unreliable for large log-scale SEs. Confidence limits are the preferred summary of uncertainty on the reported scale.

For mono() catchability terms, dq is a non-negative step on the selected q-link scale (log-q or logit-q). Estimates and SEs are reported directly on this same scale, with untransformed Wald intervals (which may cross zero at a boundary). These local curvature SEs are not boundary-adjusted inference. F mean-curve increments dmu_f likewise remain on their fitted log-F increment scale. F logistic midpoints are on the age/covariate scale; slopes are reported positive, with SEs on their fitted log scale. Double-logistic scales are also positive with log-scale SEs. Coefficient names identify transitions and groups. Actual observation-specific q is in tidy_obs_pred().
Smooth null-space coefficients and penalized basis coefficients are signed link-scale effects, not exponentiated F/q values. Smoothing SDs are positive with log-scale SEs. Complete functions, including null-space contributions, are in tidy_tam()'s formula_effects$smooths, with joint uncertainty.

Ordinary formula coefficients named log_mu_f, log_sd_*, or log_q are exponentiated in summaries. An exponentiated slope is a multiplicative change per unit covariate, not the fitted F, SD, or q surface itself. An exception is the mean-$M$ formula coefficients (mu_m), which operate on the log scale but are named without a log_ prefix to reflect that their values may be positive or negative; they therefore print on the fitted log scale.

Fixed-effect parameters are returned in a single data frame ($fixed); random-effect parameters are returned as a named list of data frames ($random), one per random block (e.g. log_f, log_r, …).

Labels are added where applicable:

For parameters specified using a formula in prepare_tam() (e.g., log_q, logit_q, log_sd_catch, log_sd_index), a coef column is added.
For log_r, year contains eligible recruitment process years (by default years 2:Y). Fixed early log_r_init states also carry year labels. Full recruitment is in tidy_pop(); parent pairs and process diagnostics are in tidy_recruitment().
For log_n0, an age column identifies the initial older-age state. log_r0 and log_n0 are exponentiated to abundance levels. d_n0 remains a log-decrement with an SE on that same scale. For constrained initialization, derived n0 estimates use joint RTMB uncertainty.
For matrices (e.g., log_f, log_n), year and/or age columns are added from their dimensions; shared F/M states use age_block rather than duplicating the parameter at each biological age. via tidy_array().

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
)
par_tab <- tidy_par(fit)
names(par_tab)
#> [1] "fixed"  "random"
par_tab$fixed
#>         par        coef year age          unit          est          lwr
#> 1        r0        <NA> 1983   2 thousand fish 4.859111e+05 3.909536e+05
#> 2      sd_r        <NA>   NA  NA          <NA> 4.972649e-01 3.668274e-01
#> 3      sd_f        <NA>   NA  NA          <NA> 4.932985e-01 4.298799e-01
#> 4      sd_n        <NA>   NA  NA          <NA> 5.951395e-01 5.306665e-01
#> 5  sd_catch (Intercept)   NA  NA          <NA> 3.814101e-01 3.007537e-01
#> 6  sd_index (Intercept)   NA  NA          <NA> 4.282125e-01 3.722307e-01
#> 7         q (Intercept)   NA  NA          <NA> 1.751148e+00 1.245280e+00
#> 8         q    q_block3   NA  NA          <NA> 1.484490e+00 1.142447e+00
#> 9         q    q_block4   NA  NA          <NA> 1.476626e+00 1.083231e+00
#> 10        q    q_block5   NA  NA          <NA> 1.284043e+00 9.101990e-01
#> 11        q q_block6-20   NA  NA          <NA> 1.002332e+00 7.095340e-01
#>             upr         se se_scale is_proj
#> 1  6.039325e+05 0.11093916      log   FALSE
#> 2  6.740836e-01 0.15522297      log      NA
#> 3  5.660731e-01 0.07020984      log      NA
#> 4  6.674457e-01 0.05850218      log      NA
#> 5  4.836969e-01 0.12121827      log      NA
#> 6  4.926138e-01 0.07148390      log      NA
#> 7  2.462513e+00 0.17393738      log      NA
#> 8  1.928938e+00 0.13362419      log      NA
#> 9  2.012891e+00 0.15807009      log      NA
#> 10 1.811435e+00 0.17556740      log      NA
#> 11 1.415957e+00 0.17626673      log      NA
names(par_tab$random)        # e.g., "log_f", "log_r", ...
#> [1] "log_f" "log_r" "log_n"
head(par_tab$random$log_f)
#>   par year age unit          est          lwr          upr        se se_scale
#> 1   f 1983   2 <NA> 3.163951e-05 1.619098e-05 6.182817e-05 0.3418188      log
#> 2   f 1984   2 <NA> 1.902865e-05 9.263852e-06 3.908629e-05 0.3672649      log
#> 3   f 1985   2 <NA> 2.203581e-05 8.746427e-06 5.551718e-05 0.4714493      log
#> 4   f 1986   2 <NA> 2.551802e-05 1.171828e-05 5.556869e-05 0.3970659      log
#> 5   f 1987   2 <NA> 1.114730e-04 5.373377e-05 2.312556e-04 0.3723237      log
#> 6   f 1988   2 <NA> 1.196298e-04 5.844459e-05 2.448693e-04 0.3654775      log
#>   is_proj
#> 1   FALSE
#> 2   FALSE
#> 3   FALSE
#> 4   FALSE
#> 5   FALSE
#> 6   FALSE