Implements a depletion-based harvest control rule (HCR) in which management output is scaled according to stock status relative to carrying capacity.
depletion.hcr(
stk,
ind,
metric = "ssb",
mult = 1,
hrmsy,
K,
trigger = 0.4,
lim = 0.1,
min = 1e-05,
initial,
dupp = NULL,
dlow = NULL,
all = TRUE,
...,
args,
tracking
)A stock object, typically an FLStock, used together with ind
to compute the selected metric.
An FLQuant object containing metrics to be used by the HCR.
Character string specifying the metric to use in the HCR.
Passed to mse::selectMetric(). Defaults to "ssb".
Numeric multiplier applied to the harvest rate after scaling by
the decision rule. Defaults to 1.
Numeric target harvest rate associated with MSY conditions.
Numeric carrying capacity or proxy scaling constant used to convert the metric into a depletion ratio.
Numeric depletion threshold above which the HCR applies the
full harvest rate. Defaults to 0.4.
Numeric depletion limit reference point below which the HCR
applies the minimum multiplier. Defaults to 0.1.
Numeric minimum multiplier applied when depletion falls below
lim. Defaults to 0.00001.
Optional numeric initial output value used when interannual change constraints are applied in the first management year.
Optional numeric upper bound on proportional increase in output.
If not NULL, output increases are capped at pre * dupp.
Optional numeric lower bound on proportional decrease in output.
If not NULL, output decreases are floored at pre * dlow.
Logical. If TRUE, change constraints are always applied. If
FALSE, they are only applied when the metric is below trigger.
Defaults to TRUE.
Additional arguments intended for downstream metric calculation.
A list of auxiliary framework arguments unpacked by FLCore::spread().
The function expects at least ay, iy, dy, mys, data_lag,
management_lag, and it.
A tracking object updated throughout the mse::mp() evaluation.
A named list with components:
ctrl: an fwdControl object specifying the catch target for the
management years in mys;
tracking: the updated tracking object containing recorded metric,
decision, tier, and output values.
The rule uses the ratio of a selected stock metric to K as a depletion
indicator and adjusts the harvest rate relative to hrmsy depending on
whether the stock is above a trigger level, between a limit and trigger, or
below the limit.
The function first computes the selected metric from stk and ind using
mse::selectMetric(), restricted to the terminal data year dy. This metric is
tracked under "metric.hcr".
Stock status is then expressed as the depletion ratio: $$met / K$$
The decision multiplier is calculated as a piecewise function:
if met / K >= trigger, the multiplier is 1;
if lim <= met / K < trigger, the multiplier increases linearly from
0 at lim to 1 at trigger;
if met / K < lim, the multiplier is set to min.
This multiplier is recorded in tracking under "decision.hcr".
The rule also classifies stock status into three tiers based on depletion:
Tier 1: below lim;
Tier 2: between lim and trigger;
Tier 3: at or above trigger.
Tier membership is stored under "tier.hcr".
A harvest-rate target is then computed as: $$hrtarget = hrmsy \times dec \times mult$$
and management output is set as: $$out = met \times hrtarget$$
This provisional output is stored under "output.hcr" before optional upper
and lower change constraints are applied.
If dupp and/or dlow are supplied, the previous output value is recovered
either from initial in the first management year or from the tracking
object in later years. The provisional output is then capped and/or floored
according to the specified proportional limits.
Finally, missing values are replaced with zero and the result is converted to
an FLasher::fwdControl() object with one catch target per management year.
If dupp is supplied, increases in output can be capped. If dlow is
supplied, decreases can be limited. When all = TRUE, these constraints are
always applied. When all = FALSE, they are only applied when the metric is
below the trigger, allowing unconstrained changes when stock status is at
or above the trigger level.
The function assumes spread(args[...]) creates ay, iy, dy,
mys, and it in scope.
Although ... is declared, it is not currently passed on in the call
to mse::selectMetric() in the implementation shown.
The previous output retrieval uses
tracking[metric == 'hcr' & year == ay, data], which assumes a specific
internal structure for tracking.
track(tracking, "decision.hcr", mys) stores the decision for all
management years, whereas track(tracking, "tier.hcr", ay) stores tier
at assessment year resolution.
Missing outputs are silently converted to zero.