See the model behind the settings
Source:vignettes/articles/model-structure.Rmd
model-structure.Rmdplot_model() connects a fitted model’s settings to its
biological components. Choose a model above the diagram, then expand
Formulas and settings to see its actual formulas,
initial-state conventions, fleets, surveys and age blocks. The same
viewer is on the dashboard’s Model structure page.
These small cod examples illustrate two hypotheses. They use the same observations and fixed natural mortality; the second adds variation in cohort survival, recruitment and fishing mortality. They are teaching examples, not recommended assessment settings. Warnings are retained, and no numerical failures are retuned.
scaa <- fit_tam(
cod_obs, years = 2000:2010, ages = 2:8,
N_settings = list(process = "off", init = "exp"),
rec_settings = list(process = "off", mu_form = ~ factor(year)),
F_settings = list(
process = "off", mu_form = ~ factor(year) + factor(age), mean_ages = 5:8
),
M_settings = list(process = "off", mu_supplied = ~ I(0.3)),
catch_settings = list(sd_form = ~ 1),
index_settings = list(sd_form = ~ 1, q_form = ~ mono(q_block)),
silent = TRUE
)
sam <- update(
scaa,
N_settings = list(process = "iid"),
rec_settings = list(process = "rw", mu_form = NULL),
F_settings = list(process = "cor_rw", mu_form = NULL),
silent = TRUE
)
#> Warning in sqrt(diag(object$cov.fixed)): NaNs produced
#> Warning in sqrt(diag(object$cov.fixed)): NaNs produced
#> Warning in sqrt(diag(object$cov.fixed)): NaNs produced
#> Warning in sqrt(diag(object$cov.fixed)): NaNs produced
#> Warning: Numerical convergence checks did not pass; inspect `check_tam(fit)`.
#> ✖ Code 1: false convergence (8)
#> ✖ Fixed-parameter covariance must be available and finite.
#> ✖ The Hessian must be positive definite.
#> ℹ Optimizer code zero alone is insufficient. A missed gradient tolerance alone
#> does not establish a structural problem.
plot_model(SCAA = scaa, SAM = sam)Initial states
Boundary parameters
N0: exp; R0: free
Recruitment
New youngest-age fish
Deterministic: process off
Mean ~factor(year)
Fishing mortality
Total F = sum of fleet F
Deterministic: process off
Mean ~factor(year) + factor(age)
Natural mortality
Shared population M
Deterministic: process off
Baseline ~I(0.3)
Population abundance
Survivors + recruitment
Deterministic: process off
Mean: survivors
Catch observations
Fleet catch predictions
SD ~1
Survey observations
q, sampling time and abundance
q ~mono(q_block)
Spawning biomass
Mature stock biomass
SSB = sum of mature biomass
- Initial states to Population abundance
- Recruitment to Population abundance
- Fishing mortality to Population abundance
- Natural mortality to Population abundance
- Population abundance to Survey observations
- Population abundance to Catch observations
- Fishing mortality to Catch observations
- Population abundance to Spawning biomass
Navy: annual stochastic process. Orange: no annual process deviations. Dashed arrows: active input-table predictors. Process off retains the biological component. Initial parameters and observations are separate.
Arrows show biological and observation relationships, not a computation order.
Formulas and settings
Initial states
Older-age initialization: exp
Recruitment boundary: free
Initial year: 2000
Initial parameters are separate from annual process deviations.
Equations and settingsRecruitment
Deterministic (process off)
Mean: ~factor(year)
Covariates: pop_covariates.
Equations and settingsAbundance and cohort survival
Deterministic (process off)
Mean: None
Modeled ages: 2 to 8 ; oldest age is the plus group.
Apparent gains/losses do not identify migration separately from mortality.
Equations and settingsFishing mortality
Deterministic (process off)
Mean: ~factor(year) + factor(age)
Fleets: Aggregate fishery
Age blocks: 2, 3, 4, 5, 6, 7, 8
Total F is the sum of fleet F. Shared age blocks share actual F.
Equations and settingsNatural mortality
Deterministic (process off)
Supplied mean: ~I(0.3)
Mean effects: None
Age blocks: 3-8
Shared age blocks share actual M; other cells retain their mean.
Equations and settingsCatch observations
Lognormal numbers at age, conditional on population and F.
Observation SD: ~1
Supplied SD: None
Zero and missing observations are excluded from the lognormal likelihood.
Equations and settingsSurvey indices and catchability
Surveys: Fall 2J3KL
q formula: ~mono(q_block)
q link: log
Gaussian q terms: None
Observation SD: ~1
Supplied SD: None
Predictions use each survey's sampling time; q may contain Gaussian effects.
Equations and settingsSpawning biomass and projections
SSB uses stock weights, maturity and spawning timing, retaining plus-group biology.
Projections: none.
Equations and settingsThe arrows show biological and observation relationships. They do not
specify the order in which the program calculates quantities. Light navy
nodes have annual stochastic process variation. Setting a process to
"off" retains the biological component and removes its
annual deviations. Initial parameters are a separate choice; their
uncertainty is not annual process variation.
For the SCAA example, separable fishing mortality is
\[ \log F_{t,a}=\alpha_t+\beta_a, \]
and cohort survival follows the mortality calculation exactly. In the SAM-style example, log fishing mortality instead has correlated annual increments, while older-age abundance includes cohort-survival deviations:
\[ \log F_{t,a}=\log F_{t-1,a}+\epsilon^F_{t,a}, \qquad \log N_{t,a}=\log \widehat N_{t,a}+\eta^N_{t,a}. \]
Here \(\widehat N\) is surviving abundance, including retained survivors in the plus group. The SCAA example estimates recruitment as annual fixed effects; the SAM-style example uses random-walk recruitment. Both retain deterministic \(M=0.3\). Full covariance and boundary conventions are in the population equations.
Adding
rec_settings = list(process = "iid", mu_form = ~ bh(ssb)),
for example, would add a parent-SSB feedback arrow. A multi-fleet model
shows the declared fleets and their shared F blocks; total F is the sum
of fleet F. See recruitment formulas
and fleet/survey scopes.
The viewer describes a specification; it cannot establish that its parameters are identifiable or its fit has converged. Inspect numerical and statistical checks before interpreting results. A diagram remains available when a fit fails checks because it only describes stored settings; its availability does not validate that fit:
check_tam(scaa, sam)
#>
#> Advisory findings (4):
#>
#> Advisory findings (4):Common quantities are available directly as tidy tables:
head(get_ssb(scaa, sam), 3)
#> model year est lwr upr se se_scale is_proj unit
#> 1 scaa 2000 12053.85 8038.060 18075.92 0.2067367 log FALSE tonnes
#> 2 scaa 2001 11492.71 7379.463 17898.66 0.2260309 log FALSE tonnes
#> 3 scaa 2002 10073.50 5989.156 16943.19 0.2652895 log FALSE tonnes
#> spawn_time timing
#> 1 0 Start of year
#> 2 0 Start of year
#> 3 0 Start of year
head(get_fbar(scaa, sam), 3)
#> model year est lwr upr se se_scale is_proj unit
#> 1 scaa 2000 0.2923308 0.2111292 0.4047630 0.1660315 log FALSE per year
#> 2 scaa 2001 0.4836643 0.3106646 0.7530024 0.2258599 log FALSE per year
#> 3 scaa 2002 0.2265287 0.1335528 0.3842320 0.2695839 log FALSE per yearget_f() and get_m() return age-specific
mortality surfaces. get_fbar() and get_mbar()
retain each model’s configured abundance-weighted mean ages. These
selectors preserve available uncertainty, units and projection labels
and do not calculate residuals or refit models.