SAM: SAM

Description

Calculate the size adherence multiplier (SAM), which evaluates adherence to harvest slot limits by comparing (lower, upper) percentiles of length–frequency data to minLS and maxLS. Optionally, produce a graph showing how SAM varies across a grid of (lower, upper) values.

When lower >= minLS and upper <= maxLS, neither of the slot limits are violated and the multiplier is calculated without constraint. When lower < minLS or upper > maxLS, at least one slot limit is violated and the multiplier is capped at constraint (default = 1).

Usage

SAM(
  lower = NULL,
  upper = NULL,
  minLS = NULL,
  maxLS = NULL,
  constraint = 1,
  digits = 2,
  plot = FALSE,
  res = 1,
  lower_percentile = 2.5,
  upper_percentile = 97.5,
  length_units = NULL
)

Value

A list with:

lower_adherence: Relative deviation of lower from minLS: \((lower - minLS)/minLS\).
upper_adherence: Relative deviation of upper from maxLS: \((maxLS - upper)/maxLS\).
SAM: Size adherence multiplier. SAM > 1 increases the advised catch; SAM < 1 decreases it.
plot: (only when plot = TRUE) a ggplot2 object visualizing SAM over a grid. Illogical combinations of percentiles are shaded grey (e.g., \(L_{2.5} > L_{97.5}\)).

Arguments

lower: Numeric (length 1). Lower percentile of catch length (e.g., 2.5th).
upper: Numeric (length 1). Upper percentile of catch length (e.g., 97.5th).
minLS: Numeric (length 1). Minimum landing size (must be > 0).
maxLS: Numeric (length 1). Maximum landing size (must be > 0).
constraint: Numeric (length 1) in \([0,1]\). Cap applied when either slot limit is violated (default = 1).
digits: Integer. Number of decimal places used to round outputs (default = 2). Set digits = NA to prevent rounding.
plot: Logical. If TRUE, include a ggplot2 plot of the calculated value on a grid of (lower, upper) combinations (default FALSE).
res: Numeric > 0. Grid step for plotting when plot = TRUE. Smaller values increase smoothness but can be slower (default 1).
lower_percentile, upper_percentile: Numbers used only for axis labels when plot = TRUE (defaults 2.5 and 97.5).
length_units: Optional character scalar. Units to display in the x/y-axis labels when plot = TRUE (e.g., "cm" or "mm"). If NULL (default), units are omitted.

Details

The unconstrained multiplier is \((1 + lower\_adherence) \times (1 + upper\_adherence)\). If any slot limit is violated, the multiplier is pmin(constraint, multiplier).

Examples

Run this code

SAM(lower = 13, upper = 24, minLS = 12, maxLS = 24)                      # no violation
SAM(lower = 13, upper = 25, minLS = 12, maxLS = 24, constraint = 0.95)   # violation with constraint

# \donttest{
out <- SAM(
  lower = 13, upper = 25,
  minLS = 12, maxLS = 24,
  res = 0.5,
  lower_percentile = 5, upper_percentile = 95,
  constraint = 1,
  plot = TRUE,
  length_units = "cm")
out$SAM
# }