Initialize parameter list for TAM

make_par() builds a named list of initial values and shapes for all fixed and random-effect parameters used by TAM, based on the structure in a previously constructed dat list (see prepare_tam()).

Usage

make_par(dat)

Arguments

dat

A data list returned by prepare_tam(), containing design matrices, settings, and observation mappings. The shapes and presence/absence of parameters depend on elements in dat (e.g., F_modmat, M_modmat, q_modmat, sd_catch_modmat, sd_index_modmat, N_settings, F_settings, M_settings, catch_settings, index_settings, years, ages, and M_settings$age_blocks).

Value

A named list of initialized parameters suitable to pass to the TAM objective function, with elements as described in Details. All numeric entries are start as described in Details, with zero initial process deviations where mean initialization applies. Matrices have informative dimnames.

Details

Latent-state convention: log_r, log_n0, log_n, log_f, and log_m represent latent quantities on the log scale. They are compact fitted latent-state parameters; log_N, log_F, and log_M are full model surfaces constructed internally by nll_fun(). Process errors are calculated separately as deviations (eta_*): recruitment uses successive log states by default, or expectations from rec_settings; abundance uses cohort predictions, and F and M use their log mean surfaces. In particular, log_f and log_m are absolute latent states; their deviations are eta_log_f = log_f - log_mu_F and eta_log_m = log_m - log_mu_M on the corresponding years and age blocks.

For nonconstant process-SD formulas, sd_beta_n, sd_beta_f, and sd_beta_m are ordinary coefficients of log SD. They are reported on their coefficient scale, while derived sd_N, sd_F, and sd_M report actual process SDs by age with uncertainty. Default ~ 1 retains log_sd_*.

The function inspects dat to decide which parameters are required and what their dimensions should be. For example, if dat$F_settings$process == "ar1" it initializes a 2-vector logit_phi_f; if dat$F_settings$mu_form is not NULL it creates a coefficient vector log_mu_f of length ncol(dat$F_modmat), and so on.

Most numeric parameters start at 0. Monotonic increments dq and dmu_f start at 0.05; d_n0 starts at 0.2 per age step for mono, or cumulative 0.2 steps from r0 for capped. Logistic curves start from the coordinate range. log_m and F curve states start at their log means so initial process residuals are zero. Stock-recruit parameters use the anchor and initial SSB; their recruitment states start on the expected path with zero deviations. These are starting values, not priors. Matrices are created with appropriate dimnames (year × age or year × age_block).

Created elements (when applicable) include:

• Recruitment & variability

  • log_r0 (first-year log recruitment, always present; fixed by default, integrated when rec_settings$init = "latent")

  • log_r: absolute random log recruitment in eligible process years when the recruitment process is enabled; by default these are dat$years[-1], named by year.

  • log_r_init: additional unpenalized boundary states when parent SSB lies before the modeled period, named by year.

  • log_sd_r: estimated recruitment SD unless supplied in rec_settings$sd or recruitment is deterministic (process = "off").

  • rec_beta: fixed log-scale covariate coefficients when present.

  • log_sr_alpha, log_sr_beta: positive curve parameters on the log scale.

  • logit_phi_r: estimated recruitment AR1 correlation when not supplied. Curve starts pass through the initial recruitment anchor at the first available parent SSB. Warm starts without curve parameters reinitialize the curve using their population states; see recruitment_formulas.

• Initial older-age abundance (independent of the N process)

  • log_n0: realized log abundance at initial ages ages[-1], named by age; fixed for "free", integrated without an initial density for "latent".

  • d_n0: nonnegative log-decrements, named by destination age, for "mono" (cumulative) and "capped" (relative to r0). Derived initial abundances and their uncertainty are reported separately. Exact ties occur at zero; symmetric Wald intervals can cross the boundary.

  • The default "exp" initializer is parsimonious survivorship from log_r0, using first-year Z without an equilibrium plus group. See prepare_tam() for the choices and weak-identification warning.

• Abundance states and process variability (N)

  • mu_n: signed log-cohort mean coefficients when N_settings$mu_form is supplied.

  • log_sd_n (if dat$N_settings$process != "off")

  • logit_phi_n length 2 (if process == "ar1")

  • log_n matrix (year[-1] × age[-1]) if process != "off"

• Fishing mortality (F)

  • log_sd_f (only when the F process is active)

  • With F_settings$age_breaks, log_f has one column per active F block, indexed by age_block. Unfished ages have no latent F entries. A single active block has no age-correlation parameter; AR1 retains only its temporal correlation.

  • logit_phi_f length 2 (if process == "ar1")

  • atanh_rho_f: signed age correlation of annual F increments (if process == "cor_rw"), reported as rho_f through tanh().

  • log_mu_f coefficients (length ncol(dat$F_modmat)) if a mean structure was supplied

  • dmu_f: directly fitted non-negative log-mean-F increments for mono()

  • F_a50_*, log_F_slope_*: midpoint and log positive slope for logistic() mean curves. F states start at their complete mean curve, giving zero residuals.

  • log_f matrix (only with an active F process; historical year × age; no projection rows)

• Natural mortality (M)

  • log_sd_m (if dat$M_settings$process != "off")

  • logit_phi_m length 2 (if process == "ar1")

  • mu_m coefficients (length ncol(dat$M_modmat)) if a mean structure was supplied; these act on log-\(M\) but are named without the log_ prefix because they may be positive or negative

  • log_m matrix (M_settings$years × age_block) if process != "off", with age_block = levels(dat$M_settings$age_blocks)

• Observation model

  • log_sd_catch (length ncol(dat$sd_catch_modmat)) adjusting any supplied SDs

  • log_sd_index (length ncol(dat$sd_index_modmat)) adjusting any supplied SDs

  • Gaussian observation-SD terms add signed eta_sd_catch_* or eta_sd_index_* log-SD effects, initially zero, with process SD parameters log_sd_catch_*/log_sd_index_* initially log(0.1) unless supplied. Estimated AR1 correlations start at 0.5. These process SDs measure variation in log observation SD, not observation SD itself.

  • log_q for q_link = "log", or logit_q for q_link = "logit" (length ncol(dat$q_modmat)). Zero coefficients start q at 1 or 0.5, respectively, before any mono() increments.

  • log_q_power: log positive exponents for power(), named by group, initialized at zero (p = 1), estimated as fixed effects.

  • dq only for mono() terms (length ncol(dat$q_mono_modmat)): fixed non-negative increments on the selected q-link scale, initialized to 0.05 for a nearly flat curve and bounded below by zero in fit_tam(). Names identify transitions and groups; these are not absolute q levels.

  • Structured Gaussian q terms have signed eta_q_* states, initially zero, and estimated log_sd_q_* parameters initially log(0.1) unless SD is supplied. Estimated logit_phi_q_* starts at correlation 0.5. RW states omit the zero anchor. Forecast states retain their normalized process densities and integrate out of the historical likelihood.

  • Logistic curves have q_a50_* midpoints and positive log_q_slope_* coefficients, initialized from each group's observed coordinate range. Names identify terms, groups and unique states for warm starts. double_logistic() has ascending/descending midpoints and log positive scales. There is no midpoint ordering or peak normalization.

All scalar SD parameters are on the log scale, and AR(1) parameters are on the logit scale (later transformed by plogis() in the likelihood). Temporal RW processes have no correlation parameters. Their first process row supplies a conditional starting state during simulation and has no increment penalty. See fit_tam() for mean coefficients or SDs held fixed when they have no effect on the RW likelihood.

See also

prepare_tam(), fit_tam(), tinyAM-model

Examples

dat <- prepare_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)
)
par <- make_par(dat)
str(par)
#> List of 10
#>  $ log_r0      : num 0
#>  $ log_sd_r    : num 0
#>  $ log_sd_f    : num 0
#>  $ log_sd_n    : num 0
#>  $ log_sd_catch: Named num 0
#>   ..- attr(*, "names")= chr "(Intercept)"
#>  $ log_sd_index: Named num 0
#>   ..- attr(*, "names")= chr "(Intercept)"
#>  $ log_q       : Named num [1:5] 0 0 0 0 0
#>   ..- attr(*, "names")= chr [1:5] "(Intercept)" "q_block3" "q_block4" "q_block5" ...
#>  $ log_r       : Named num [1:41] 0 0 0 0 0 0 0 0 0 0 ...
#>   ..- attr(*, "names")= chr [1:41] "1984" "1985" "1986" "1987" ...
#>  $ log_n       : num [1:41, 1:12] 0 0 0 0 0 0 0 0 0 0 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ year: chr [1:41] "1984" "1985" "1986" "1987" ...
#>   .. ..$ age : chr [1:12] "3" "4" "5" "6" ...
#>  $ log_f       : num [1:42, 1:13] 0 0 0 0 0 0 0 0 0 0 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ year: chr [1:42] "1983" "1984" "1985" "1986" ...
#>   .. ..$ age : chr [1:13] "2" "3" "4" "5" ...