Implements a buffer harvest control rule (HCR) that adjusts management output according to the recent value of a stock or index metric relative to a set of threshold reference points.
Tools for visualizing a buffer-based harvest control rule (HCR), including the HCR curve itself and optional shaded management-tier bands.
buffer.hcr(
stk,
ind,
metric = "wmean",
target = 1,
width = 0.5,
lim = max(target * 0.1, target - 2 * width),
bufflow = max(lim * 1.5, target - width),
buffupp = target + width,
sloperatio = 0.15,
initial,
nyears = 4,
dupp = NULL,
dlow = NULL,
all = TRUE,
scale = FALSE,
...,
args,
tracking
)
plot_buffer.hcr(
args,
obs = "missing",
alpha = 0.3,
labels = c(lim = "Limit", bufflow = "Lower~buffer", buffupp = "Upper~buffer", metric =
metric, output = output),
metric = args$metric,
output = "multiplier",
xlim = buffupp * 1.5,
ylim = scale * 1.5
)
buffer_bands(x)A stock object, typically an FLStock, used together with ind
to compute the HCR metric.
An index object used when computing the selected metric.
Character string giving the metric used for the x-axis and,
when obs is an FLStock, the variable extracted from FLCore::metrics().
Numeric. Target value of the metric.
Numeric. Half-width of the buffer around target.
Numeric. Lower limit reference point for the metric.
Numeric. Lower bound of the buffer zone.
Numeric. Upper bound of the buffer zone.
Numeric. Controls the slope of output increases above
buffupp.
Initial output value used when no previous output is available.
Number of recent years over which the metric is averaged.
Optional upper bound on proportional increase in output.
Optional lower bound on proportional decrease in output.
Logical. If TRUE, change limits are always applied.
Logical. If TRUE, do not recover previous output from tracking.
Additional arguments passed to mse::selectMetric().
A list of arguments defining the buffer HCR. Typically includes
values such as lim, bufflow, buffupp, sloperatio, and optionally
other elements used by the plotting method. If an object of class
mseCtrl is supplied to plot_buffer.hcr(), its arguments are extracted
using args().
A tracking object updated with metric, decision, tier, and output values.
Optional observed values to overlay on the HCR plot. Can be:
an FLStock object, in which case metric and output are
extracted and plotted;
a numeric value, in which case a single point is added on the HCR curve;
omitted, in which case no observations are added.
Numeric. Alpha transparency used for observed points and paths.
Labels for plot annotations. A named vector or list with names
among lim, bufflow, buffupp, metric, and output. Supplied values
override the defaults.
Character string giving the output used for the y-axis and,
when obs is an FLStock, the variable extracted from FLCore::metrics().
Numeric. Maximum x-axis value for the HCR plot. By default set to
buffupp * 1.5.
Numeric. Maximum y-axis value for the HCR plot.
An object for which args() returns a list containing at least the
buffer-HCR parameters lim, bufflow, and buffupp.
For buffer.hcr(), a list with components ctrl and tracking.
For buffer_bands(), a list of ggplot2 layers for shading HCR zones.
For plot_buffer.hcr(), a ggplot2 object.
For buffer_bands(), a list of ggplot2 components:
a ggplot2::geom_rect() layer that draws shaded tier bands;
a ggplot2::scale_fill_manual() layer that assigns colours to tiers.
buffer.hcr() computes a piecewise decision multiplier from the selected
metric and applies it to the previous output value.
buffer_bands() creates shaded ggplot2 rectangles marking the critical,
recovery, buffer, and above-target zones implied by the same thresholds.
plot_buffer.hcr() draws the HCR curve implied by the buffer rule and can
optionally overlay observed values.
buffer_bands() returns ggplot2 layers that shade the management tiers
defined by the HCR thresholds.
The buffer harvest control rule is defined by threshold values that partition the x-axis metric into zones:
below lim: critical zone;
between lim and bufflow: recovery zone;
between bufflow and buffupp: buffer zone;
above buffupp: above-target zone.
plot_buffer.hcr() evaluates the implied HCR multiplier across a sequence of
metric values and draws the resulting curve, including annotations for the
key thresholds.
buffer_bands() constructs semi-transparent shaded rectangles spanning these
threshold intervals to support interpretation of HCR plots.
plot_buffer.hcr() computes the HCR response curve from the supplied buffer
rule parameters and returns a ggplot object. The plot includes:
the HCR line;
vertical reference markers for lim, bufflow, and buffupp;
labels for the threshold points;
optional observed points or trajectories.
If obs is an FLStock object, the function extracts the chosen metric
and output values using FLCore::metrics() and overlays them on the HCR curve. If
there is a single iteration, both points and a path are added, and first/last
years are labelled.
If obs is numeric, a single red point is placed at the corresponding
location on the HCR curve.
buffer_bands() extracts lim, bufflow, and buffupp from args(x) and
defines four contiguous x-axis intervals. A fourth threshold,
target = 1.5 * buffupp, is used as the upper bound for the final tier.
The returned rectangles extend from y = 0 to y = Inf, so they occupy the
full vertical plotting range.
Thresholds are assumed to satisfy
0 <= lim <= bufflow <= buffupp.
buffer_bands() adds a fill scale and may therefore override an
existing fill scale in a ggplot object.
In plot_buffer.hcr(), default values such as xlim and ylim
depend on objects created after argument expansion and may rely on the
surrounding evaluation framework.
plot_buffer.hcr() currently uses internal helper functions such as
FLCore::spread(), args(), and FLCore::metrics(), and assumes these are available.
plot_buffer.hcr()
args(), FLCore::metrics(), ggplot2::geom_line(),
ggplot2::geom_rect(), ggplot2::scale_fill_manual()
if (FALSE) { # \dontrun{
args <- list(lim = 0.4, bufflow = 1, buffupp = 2, sloperatio = 0.2)
# Plot the HCR curve
plot_buffer.hcr(args, labels = list(metric = "CPUE", output = "C~mult"))
# Add buffer bands to a custom ggplot
layers <- buffer_bands(hcr)
p <- ggplot(dat, aes(x = biomass, y = harvest)) + geom_line()
for (ly in layers) p <- p + ly
p
} # }