Use these terms in index_settings$q_form when catchability should increase
with age or size, or in F_settings$mu_form for a rising long-term mean F.
mono() fits flexible non-decreasing steps, including exact
plateaus. logistic() fits a smooth rising selectivity curve. Ordinary formula
terms supply baseline catchability; neither curve describes a dome with other
covariates held constant.
Details
Both functions are additive formula markers, not numeric transformations.
Flexible steps: mono()
Numeric values are ordered increasingly; factors (including ordered factors) use their declared levels. Supply factor levels in the scientifically intended order.
The first represented level has no increment. Subsequent link-scale levels add
cumulative non-negative increments dq, fitted directly with a lower bound
of zero by fit_tam(). These are increments on the log-q scale by default,
or logit-q when index_settings$q_link = "logit", not absolute q.
Both links preserve non-decreasing q. Steps start at 0.05.
A zero step gives an exact plateau between separate
levels at a finite parameter value; pooled levels also retain identical q.
When optimizing nll_fun() directly, supply the same zero lower bounds for
dq. Standard errors describe local curvature on the increment scale;
inference at an active boundary need not follow a symmetric normal law.
by gives each group independent steps, using only levels represented in
that group, in their declared order. Each group needs at least two levels.
Baselines come from ordinary formula terms: ~ mono(x, by = survey) shares
an intercept, whereas ~ survey + mono(x, by = survey) gives separate
survey baselines. Other ordinary covariates can modify q, so monotonicity
holds with those covariates held constant. Interactions involving mono(),
transformed arguments, and ordinary effects of the same x are unsupported.
Smooth selectivity: logistic()
For numeric age or size, the curve is
\(S(x) = 1 / (1 + \exp\{-k(x-a_{50})\})\), with positive slope \(k\).
The midpoint \(a_{50}\) is the age/size at half the asymptotic selectivity.
This curve multiplies catchability after the selected inverse link, rather
than adding a sigmoid on the link scale. Thus logit q remains below one.
Ordinary terms supply its baseline: ~ survey + logistic(age, by = survey)
gives survey-specific baselines and curves. Each curve needs at least three
observed x values. Numeric by and interactions are unsupported.
Midpoint and positive slope are fixed effects, not Gaussian random effects.
Redundant curves, such as logistic plus an unrestricted factor of the same
age, are rejected. See formula_effects for variation around these curves.
Fitting warns if the midpoint lies outside the observed age/size range and
its 95% interval is wider than that range. Maximum catchability and curve
shape may then be difficult to distinguish. Uncertainty advisories require
a successful positive-definite uncertainty calculation; failures are reported
separately by the numerical convergence checks.
Mean fishing mortality
With F_settings$process = "off", "iid" or "ar1", use ~ mono(age) or
~ logistic(age). Ordinary terms provide the baseline F. One curve is allowed
on each set of applicable rows; for_fleet() can give fleets different curves.
Its numeric coordinate must be age or an age-derived catch-table column
constant across years at each age within the fleet. Categorical by groups
may have separate curves. M mean curves are not enabled.
For mono, \(\log\mu_F = X\beta + C d\), where C contains cumulative
indicators and the directly fitted dmu_f increments satisfy \(d\geq0\).
For logistic, \(\log\mu_F = X\beta + \log S(x)\). The baseline therefore
gives the asymptotic F when other covariates are held constant. Midpoint
F_a50_* and positive slope log_F_slope_* are fitted separately from q
curves. With the residual process off, F equals this mean. Otherwise realized
F fluctuates around it and need not be monotonic.
mu_F is the exponential of expected log F, rather than an arithmetic
average over lognormal process draws.
Static curves are rejected with RW/correlated-RW residuals because they
cancel from the increments. Gaussian structured mean terms retain their
existing IID-residual or no-residual-process restriction, including with a curve.
dmu_f has the same zero bounds and boundary-inference limitations as dq.
tidy_pop() reports mean-F profiles with joint RTMB-derived uncertainty.
Examples
~q_block # ordinary unconstrained q
#> ~q_block
#> <environment: 0x5edf822917b0>
~ mono(q_block)
#> ~mono(q_block)
#> <environment: 0x5edf822917b0>
~ survey + mono(q_block, by = survey)
#> ~survey + mono(q_block, by = survey)
#> <environment: 0x5edf822917b0>
~ survey + logistic(age, by = survey)
#> ~survey + logistic(age, by = survey)
#> <environment: 0x5edf822917b0>
# F_settings = list(process = "iid", mu_form = ~ mono(age))
# F_settings = list(process = "ar1", mu_form = ~ logistic(age))