Package 'cat3advice' reference manual

Title:	ICES category 3 empirical harvest control rules
Description:	A package to apply the the ICES category 3 empirical (model-free) harvest control rules.
Authors:	Simon H. Fischer [aut, cre]
Maintainer:	Simon Fischer <[email protected]>
License:	GPL-3
Version:	0.1.2
Built:	2026-05-15 09:20:28 UTC
Source:	https://github.com/shfischer/cat3advice

A-class

Description

An S4 class to represent component Ay (the last advice or reference catch) of the rfb, rb, and chr rules.

The classes rfb_A, rb_A, and chr_A inherit from A and their only difference is that the slot hcr is set to the corresponding catch rule name ('rfb', 'rb', or 'chr').

Slots

value: The value of component Ay (reference catch)
value_landings: Optional. The landings corresponding to value.
value_discards: Optional. The discards corresponding to value.
value_catch: Optional. The total catch corresponding to value. May differ from value if discard survival is considered.
hcr: The harvest control rule (hcr) for which Ay is used. One of 'rfb', 'rb', or 'chr'.
data: Time series of historical catches and/or advice
avg_years: Number of years for calculating average catch
basis: Basis of Ay. Either "advice" for using previous advice or "average catch" when based on average of historical catch
advice_metric: Advice metric, 'catch' or 'landings'.
discard_survival: Optional. Discard survival (%). Can be used to show the reference catch (or advice) in the form of dead catch (or advice).

ICES advice sheet-style output table

Description

This function returns an advice sheet-style table for the empirical harvest control rules. The argument passed to the function can either be a single component of any rules (components r, f, b, ...) or the output from applying any of the rules (rfb, rb, chr).

Usage

advice(object)
advice(object)

Arguments

object

A component of any of the empirical harvest control rules or the the output from applying the rule.

Value

NULL. A table is displayed in the R terminal.

rb/rfb/chr rule - component b (biomass safeguard)

Description

This function calculates component b (the biomass safeguard) of the rb, rfb, and chr rule. The index needs to be a biomass index without age structure.

Usage

b(object, idx_value, Itrigger, Iloss, w, yr_ref, lag, n_yrs, units, hcr, ...)

rfb_b(
  object,
  idx_value,
  Itrigger,
  Iloss,
  w,
  yr_ref,
  lag,
  n_yrs,
  units,
  hcr = "rfb",
  ...
)

rb_b(
  object,
  idx_value,
  Itrigger,
  Iloss,
  w,
  yr_ref,
  lag,
  n_yrs,
  units,
  hcr = "rb",
  ...
)

chr_b(
  object,
  idx_value,
  Itrigger,
  Iloss,
  w,
  yr_ref,
  lag,
  n_yrs,
  units,
  hcr = "chr",
  ...
)
b(object, idx_value, Itrigger, Iloss, w, yr_ref, lag, n_yrs, units, hcr, ...)

rfb_b(
  object,
  idx_value,
  Itrigger,
  Iloss,
  w,
  yr_ref,
  lag,
  n_yrs,
  units,
  hcr = "rfb",
  ...
)

rb_b(
  object,
  idx_value,
  Itrigger,
  Iloss,
  w,
  yr_ref,
  lag,
  n_yrs,
  units,
  hcr = "rb",
  ...
)

chr_b(
  object,
  idx_value,
  Itrigger,
  Iloss,
  w,
  yr_ref,
  lag,
  n_yrs,
  units,
  hcr = "chr",
  ...
)

Arguments

object

The biomass index. Can be a data.frame with columns 'data' and 'index'.

idx_value

Optional. The current index value. Only used if no index time series is supplied.

Itrigger

Optional. The index trigger value below which the biomass safeguard reduces the catch advice.

Iloss

Optional. The lowest index value, can be used to calculate Itrigger.

w

Optional. The index trigger buffer (multiplier) to link Itrigger to Iloss. Defaults to w=1.4.

yr_ref

Optional. If supplied, this specifies the year in the biomass index which is used as Iloss and Itrigger is calculated from this value.

lag

Optional. Time lag between the last index year and the last year to be used. By default, the last index year is used (lag=0).

n_yrs

Optional. The number of years used in the index. By default, only the last index value is used (n_yrs=1).

units

Optional. The units of the biomass index, e.g. 'kg/hr'. Only used for plotting.

hcr

Optional. One of 'rfb', 'rb', or 'chr'.

...

Additional arguments. Not used.

Details

The biomass safeguard compares the last index value (I) to an index trigger value (I_trigger). If the current index value is below the trigger, the biomass safeguard reduces the catch advice:

b = min{1, I / I_trigger}

, where I_trigger is usually derived from the lowest observed biomass index value (I_loss) as:

I_trigger = w * I_loss

with

w = 1.4

See ICES (2022) for the full definition definition.

Usually, this method is used by providing only a biomass index, e.g. as a data.frame. The method uses this index, searches for the lowest index value (Iloss), multiplies this value by the index trigger buffer (w) to get the index trigger value (Itrigger). The last index value in the time series is then compared to Itrigger and if the index value is below, the biomass safeguard reduces the catch advice.

The biomass safeguard is identical in the rfb, rb, and chr rules. rfb_b(), rb_b() and chr_b() are aliases for b() with identical arguments and functionality.

Value

An object of class b with the value of the biomass safeguard

Warning

Please note that I_trigger should only be defined once the first time the empirical harvest control rule is applied. In the following years, the same value should be used for I_trigger. For application in ICES, do not change the defaults unless the change is supported by stock-specific simulations.

References

ICES. 2025. ICES Guidelines - Advice rules for stocks in category 2 and 3. Version 3. ICES Guidelines and Policies - Advice Technical Guidelines. 31 pp. https://doi.org/10.17895/ices.pub.28506179.

Fischer, S. H., De Oliveira, J. A. A., Mumford, J. D., and Kell, L. T. 2023. Risk equivalence in data‐limited and data‐rich fisheries management: An example based on the ICES advice framework. Fish and Fisheries, 24: 231–247. https://doi.org/10.1111/faf.12722.

Fischer, S. H., De Oliveira, J. A. A., Mumford, J. D., and Kell, L. T. 2022. Exploring a relative harvest rate strategy for moderately data-limited fisheries management. ICES Journal of Marine Science, 79: 1730–1741. https://doi.org/10.1093/icesjms/fsac103.

Fischer, S. H., De Oliveira, J. A. A., Mumford, J. D., and Kell, L. T. 2021. Application of explicit precautionary principles in data-limited fisheries management. ICES Journal of Marine Science, 78: 2931–2942. https://doi.org/10.1093/icesjms/fsab169.

Fischer, S. H., De Oliveira, J. A. A., Mumford, J. D., and Kell, L. T. 2021. Using a genetic algorithm to optimize a data-limited catch rule. ICES Journal of Marine Science, 78: 1311–1323. https://doi.org/10.1093/icesjms/fsab018.

Fischer, S. H., De Oliveira, J. A. A., and Kell, L. T. 2020. Linking the performance of a data-limited empirical catch rule to life-history traits. ICES Journal of Marine Science, 77: 1914–1926. https://doi.org/10.1093/icesjms/fsaa054.

Examples

# If the value of the biomass safeguard is known
b(1)

# First application of the biomass safeguard
# Use a data.frame with index values
df_idx <- data.frame(year = 2017:2021,
                     index = c(1.33, 1.13, 0.84, 0.60, 1.03))
b <- b(df_idx)
b
advice(b)

# plot
plot(b(df_idx, units = "kg/hr"))

# Use of the biomass safeguard in a following year without updating Itrigger
df_idx <- data.frame(year = 2017:2022,
                     index = c(1.33, 1.13, 0.84, 0.60, 1.03, 0.5))
b(df_idx, yr_ref = 2020)

# If the value of the biomass safeguard is known
b(1)

# First application of the biomass safeguard
# Use a data.frame with index values
df_idx <- data.frame(year = 2017:2021,
                     index = c(1.33, 1.13, 0.84, 0.60, 1.03))
b <- b(df_idx)
b
advice(b)

# plot
plot(b(df_idx, units = "kg/hr"))

# Use of the biomass safeguard in a following year without updating Itrigger
df_idx <- data.frame(year = 2017:2022,
                     index = c(1.33, 1.13, 0.84, 0.60, 1.03, 0.5))
b(df_idx, yr_ref = 2020)

b-class

Description

An S4 class to represent component b of the rfb/rb/chr rules.

This class (b) stores the input for component b (the biomass safeguard) as well as the resulting b value.

The classes rfb_b, rb_b, and chr_b inherit from b and their only difference is that the slot hcr is set to the corresponding catch rule name ('rfb', 'rb', or 'chr').

Slots

value: The value of component b
idx_value: Index value that is compared to Itrigger.
Itrigger: The index trigger value below which the advice is reduced. Usually calculated as Itrigger=Iloss*w.
Iloss: The lowest observed index value. Can be used as the basis for Itrigger.
w: Index trigger buffer. Connects Itrigger to Iloss.
yr_ref: Reference year on which Itrigger is based.
yr_last: Last data year of the biomass index. The index value in this year is compared to Itrigger.
lag: numeric. Time lag between the last index year and the last year to be used.
n_years: numeric. The number of years used for the index value.
idx: data.frame. A data.frame with the index values.
units: character. The units of the biomass index, e.g. 'kg/hr'.
hcr: character. The harvest control rule (hcr) for which the biomass safeguard is used. One of 'rfb', 'rb', or 'chr'.

chr rule

Description

This function applies the chr rule.

Usage

chr(
  object = new("chr"),
  A = object@A,
  I = object@I,
  F = object@F,
  b = object@b,
  m = object@m,
  cap = "conditional",
  cap_upper = 20,
  cap_lower = -30,
  years,
  frequency = "annual",
  discard_rate = NA,
  discard_survival = 0,
  ...
)
chr(
  object = new("chr"),
  A = object@A,
  I = object@I,
  F = object@F,
  b = object@b,
  m = object@m,
  cap = "conditional",
  cap_upper = 20,
  cap_lower = -30,
  years,
  frequency = "annual",
  discard_rate = NA,
  discard_survival = 0,
  ...
)

Arguments

object

Optional. An object of class chr.

A

A. The reference catch (previous catch advice). Required for calculating change in advice and for the application of the stability clause.

I

I. The biomass index value.

F

F. The harvest rate target.

b

b. The biomass safeguard.

m

m. The multiplier.

cap

The uncertainty cap (stability clause). Defaults to 'conditional', i.e. it is only considered when b=1.

cap_upper

Optional. numeric. The maximum allowed increase in the catch advice in %. Default to +20.

cap_lower

Optional. numeric. The maximum allowed decrease in the catch advice in %. Default to -20.

years

Optional. numeric. The years for which the advice should be given.

frequency

Optional. The frequency of the advice ('annual'/'biennial'/'triennial'). Defaults to 'annual'.

discard_rate

Optional. numeric. The discard rate (in %) for the advice. If provided, advice values for catch and landings are given.

discard_survival

Optional. numeric. The discard survival rate (in %) for the advice. If provided, Discards are split into dead and surviving discards.

...

Additional parameters. Not used.

Details

This function applies the chr rule following the ICES technical guidelines (ICES, 2025). The function requires the elements of the chr rule: I (the biomass index, see chr_I), HR_MSYproxy (the target harvest rate, see F), b (the biomass safeguard, see chr_b) and m (the multiplier, see chr_m). The catch advice is then calculated as

A_y+1 = I * HR_MSYproxy * b * m

restricted by the stability clause relative to A_y. See the help files of the components for their definition (chr_I, F, chr_b, chr_m)

The cat3advice package vignette includes an example on how to apply the chr rule with custom control parameters, derived from an MSE, and how to include discard survival.

Value

An object of class chr.

Warning

For application in ICES, do not change the default parameters (frequency, stability clause, etc) unless the changes are supported by case-specific simulations.

References

ICES. 2025. ICES Guidelines - Advice rules for stocks in category 2 and 3. Version 3. ICES Guidelines and Policies - Advice Technical Guidelines. 31 pp. https://doi.org/10.17895/ices.pub.28506179.

Examples

# calculate elements of chr rule for plaice
# reference catch
data(ple7e_catch)
A <- A(object = ple7e_catch, basis = "advice", units = "tonnes", advice_metric = "catch")
# biomass index value
data(ple7e_idx)
I <- I(ple7e_idx)
plot(I)
# target harvest rate
data(ple7e_length)
data(ple7e_catch)
lc <- Lc(data = ple7e_length, pool = 2017:2021) # length at first capture
plot(lc)
lmean <- Lmean(data = ple7e_length, Lc = lc, units = "mm") # mean catch length
plot(lmean)
lref <- Lref(Lc = 264, Linf = 528) # reference length
f <- f(Lmean = lmean, Lref = lref, units = "mm") # f indicator
plot(f)
df <- merge(ple7e_catch, ple7e_idx, all = TRUE) # combine catch & index data
hr <- HR(df, units_catch = "tonnes", units_index = "kg/hr") # harvest rate
plot(hr)
HR <- F(hr, f) # calculate (relative) target harvest rate
plot(HR)
# biomass safeguard
b <- b(ple7e_idx)
plot(b)
# multiplier
m <- m(hcr = "chr")

# apply chr rule
advice <- chr(A = A, I = I, F = HR, b = b, m = m, discard_rate = 27)
advice
advice(advice)

# application in following years without updating reference levels
A <- A(object = ple7e_catch, basis = "advice", units = "tonnes", advice_metric = "catch")
I <- I(ple7e_idx)
hr <- HR(merge(ple7e_catch, ple7e_idx, all = TRUE), units_catch = "tonnes", units_index = "kg/hr")
HR <- F(hr, yr_ref = c(2016, 2019)) # use reference years to define target
b <- b(ple7e_idx, yr_ref = 2007) # use reference year for Itrigger
m <- m(0.5) # keep multiplier
advice <- chr(A = A, I = I, F = HR, b = b, m = m, discard_rate = 27)
advice

# application of custom control parameters and discard survival
# see package vignette for more details
data("ple7e_WKBPLAICE")
A <- chr_A(ple7e_WKBPLAICE, units = "tonnes", 
           basis = "advice", advice_metric = "catch", 
           discard_survival = 50)
I <- chr_I(ple7e_WKBPLAICE, n_yrs = 2, lag = 1, 
           units = "kg/(hr m beam)")
hr <- HR(ple7e_WKBPLAICE, units_catch = "tonnes", 
         units_index = "kg/(hr m beam)", split_discards = TRUE,
         discard_survival = 50)
HR <- F(hr, yr_ref = 2003:2023, MSE = TRUE, multiplier = 0.66)
b <- chr_b(I, ple7e_WKBPLAICE, units = "kg/(hr m beam)", 
           yr_ref = 2007, w = 3.7)
m <- chr_m(1, MSE = TRUE)
advice <- chr(A = A, I = I, F = HR, b = b, m = m,
              frequency = "biennial",
              discard_rate = 26.43168,
              discard_survival = 50,
              units = "tonnes", advice_metric = "catch")
advice(advice)

# calculate elements of chr rule for plaice
# reference catch
data(ple7e_catch)
A <- A(object = ple7e_catch, basis = "advice", units = "tonnes", advice_metric = "catch")
# biomass index value
data(ple7e_idx)
I <- I(ple7e_idx)
plot(I)
# target harvest rate
data(ple7e_length)
data(ple7e_catch)
lc <- Lc(data = ple7e_length, pool = 2017:2021) # length at first capture
plot(lc)
lmean <- Lmean(data = ple7e_length, Lc = lc, units = "mm") # mean catch length
plot(lmean)
lref <- Lref(Lc = 264, Linf = 528) # reference length
f <- f(Lmean = lmean, Lref = lref, units = "mm") # f indicator
plot(f)
df <- merge(ple7e_catch, ple7e_idx, all = TRUE) # combine catch & index data
hr <- HR(df, units_catch = "tonnes", units_index = "kg/hr") # harvest rate
plot(hr)
HR <- F(hr, f) # calculate (relative) target harvest rate
plot(HR)
# biomass safeguard
b <- b(ple7e_idx)
plot(b)
# multiplier
m <- m(hcr = "chr")

# apply chr rule
advice <- chr(A = A, I = I, F = HR, b = b, m = m, discard_rate = 27)
advice
advice(advice)

# application in following years without updating reference levels
A <- A(object = ple7e_catch, basis = "advice", units = "tonnes", advice_metric = "catch")
I <- I(ple7e_idx)
hr <- HR(merge(ple7e_catch, ple7e_idx, all = TRUE), units_catch = "tonnes", units_index = "kg/hr")
HR <- F(hr, yr_ref = c(2016, 2019)) # use reference years to define target
b <- b(ple7e_idx, yr_ref = 2007) # use reference year for Itrigger
m <- m(0.5) # keep multiplier
advice <- chr(A = A, I = I, F = HR, b = b, m = m, discard_rate = 27)
advice

# application of custom control parameters and discard survival
# see package vignette for more details
data("ple7e_WKBPLAICE")
A <- chr_A(ple7e_WKBPLAICE, units = "tonnes", 
           basis = "advice", advice_metric = "catch", 
           discard_survival = 50)
I <- chr_I(ple7e_WKBPLAICE, n_yrs = 2, lag = 1, 
           units = "kg/(hr m beam)")
hr <- HR(ple7e_WKBPLAICE, units_catch = "tonnes", 
         units_index = "kg/(hr m beam)", split_discards = TRUE,
         discard_survival = 50)
HR <- F(hr, yr_ref = 2003:2023, MSE = TRUE, multiplier = 0.66)
b <- chr_b(I, ple7e_WKBPLAICE, units = "kg/(hr m beam)", 
           yr_ref = 2007, w = 3.7)
m <- chr_m(1, MSE = TRUE)
advice <- chr(A = A, I = I, F = HR, b = b, m = m,
              frequency = "biennial",
              discard_rate = 26.43168,
              discard_survival = 50,
              units = "tonnes", advice_metric = "catch")
advice(advice)

An S4 class to represent the chr rule.

Description

This class contains the components of the chr rule (I, F, b, m).

Slots

advice: The value of the catch advice.
advice_dead: The dead catch corresponding to the advice.
advice_landings: Landings corresponding to the catch advice.
advice_discards: Discards corresponding to the catch advice.
advice_discards_dead: Dead discards corresponding to the catch advice.
advice_discards_surviving: Surviving discards corresponding to the catch advice.
advice_uncapped: The value of the catch advice without the uncertainty cap.
units: The unit (e.g. tonnes) of the catch advice.
advice_metric: The advice metric, 'catch' or 'landings'.
frequency: The advice frequency (annual/biennial).
years: The years for which the advice is valid.
A: The reference catch (previous catch advice).
I: Component I (the biomass index value).
F: Component HR (previously called "F", the relative harvest rate target).
b: Component b (the biomass safeguard).
m: Component m (the multiplier).
cap: Uncertainty cap (stability clause, restricts changes in advice).
cap_lower: Maximum allowed reduction in advice in %, e.g. -30.
cap_upper: Maximum allowed increase in advice in %, e.g. 20.
change: Change in advice compared to previous advice.
change_uncapped: Change in advice compared to previous advice before application of the uncertainty cap.
discard_rate: Discard rate (%).
discard_survival: Discard survival (%).

rfb rule - component f (fishing pressure proxy, length indicator)

Description

This function calculates component f (the fishing pressure proxy, derived from a length indicator ) of the rfb rule.

Usage

f(object, Lmean, Lref, n0 = 0, units, hcr, ...)
f(object, Lmean, Lref, n0 = 0, units, hcr, ...)

Arguments

object

Optional. An object of class f.

Lmean

The mean catch length. Either a data.frame with columns 'year' and 'Lmean' or an object of class Lmean.

Lref

The reference length. Either a numeric with the value or an object of class Lref.

n0

Time lag between the last indicator year and the last year to be used. Defaults to 0.

units

Optional. The units of the length dat, e.g. 'cm'. Only used for plotting.

hcr

Optional. Defaults to 'rfb'.

...

Additional arguments. Not currently used.

Details

The value is calculated by comparing the mean catch length (above length of first capture Lc) to a reference length.

rfb_f() is an alias for f() with identical arguments and functionality.

Value

An object of class f with the length indicator value(s).

Note

The reference length Lref should be kept constant for all years unless there is a substantial changes in the fishery or fishery selectivity.

References

ICES. 2025. ICES Guidelines - Advice rules for stocks in category 2 and 3. Version 3. ICES Guidelines and Policies - Advice Technical Guidelines. 31 pp. https://doi.org/10.17895/ices.pub.28506179.

Examples

# use ple7e example data
data(ple7e_length)
# calculate (pooled) length at first capture first
lc <- Lc(data = ple7e_length, pool = 2017:2021)
# calculate mean catch length
lmean <- Lmean(data = ple7e_length, Lc = lc, units = "mm")
# reference length
lref <- Lref(Lc = 264, Linf = 585)
# calculate component f
f <- f(Lmean = lmean, Lref = lref, units = "mm")
f
advice(f)
plot(f)

# use ple7e example data
data(ple7e_length)
# calculate (pooled) length at first capture first
lc <- Lc(data = ple7e_length, pool = 2017:2021)
# calculate mean catch length
lmean <- Lmean(data = ple7e_length, Lc = lc, units = "mm")
# reference length
lref <- Lref(Lc = 264, Linf = 585)
# calculate component f
f <- f(Lmean = lmean, Lref = lref, units = "mm")
f
advice(f)
plot(f)

Calculation of the (relative) harvest rate target

Description

This function calculates the target harvest rate for chr rule.

Usage

F(object, indicator, yr_ref, units, MSE, multiplier, ...)
F(object, indicator, yr_ref, units, MSE, multiplier, ...)

Arguments

object

The time series with (relative) harvest rate values. See HR.

indicator

The length based indicator. See f.

yr_ref

Optional. Allows direct specification of years to include in the calculation instead of using indicator.

units

Optional. The units of the harvest rate. Can be derived automatically from argument HR.

MSE

Optional. TRUE/FALSE. Is the harvest rate a generic value or was it calculated with stock-specific simulations (MSE)?

multiplier

Optional. numeric. Multiplier to adjust the target harvest rate. Only used if MSE=TRUE.

...

Additional arguments. Not currently used.

Details

Usually, this functions is used by providing a time series of (relative) harvest rate values (see HR) and a length-based indicator based on the mean catch length (see f). The functions then finds those years where the indicator values are above 1, indicating that the fishing pressure is likely below Fmsy, extracts the corresponding (relative) harvest rate values for these years, and returns the average of these values as the target harvest rate.

Alternatively, years can directly be specified with the argument yr_ref and the target harvest rate is then calculated as the average of the (relative) harvest rates for these years. See the ICES technical guidelines (ICES, 2025) for details.

If stock-specific simulations were conducted to derive the target harvest rate, the calculation may differ. Nevertheless, it is good practice to express the target harvest rate relative to the harvest of one or more years. This is useful when historical harvest rates are revised (e.g. because of a revision of historical biomass index values) because the target harvest rate will then be scaled accordingly. If the argument MSE=TRUE, it is possible to include a multiplier directly in the calculation of the target harvest with the argument multiplier.

If an object of class F is provided, its validity is checked.

Value

An object of class F with the target harvest rate and the input data.

Warning

For application in ICES, the target harvest rate should only be calculated in the first year the chr rule is used and the same value used in subsequent years.

References

ICES. 2025. ICES Guidelines - Advice rules for stocks in category 2 and 3. Version 3. ICES Guidelines and Policies - Advice Technical Guidelines. 31 pp. https://doi.org/10.17895/ices.pub.28506179.

Examples


# load harvest rate time series and length-based indicator
data(ple7e_hr)
data(ple7e_f2)
# calculate target harvest rate
HR <- F(ple7e_hr, ple7e_f2)
HR
advice(HR)
plot(HR)

# use reference years when using in following years
F(ple7e_hr, yr_ref = c(2016, 2019))

# full example with ple7e data
data(ple7e_length)
# calculate (pooled) length at first capture first
lc <- Lc(data = ple7e_length, pool = 2017:2021)
# calculate mean catch length
lmean <- Lmean(data = ple7e_length, Lc = lc, units = "mm")
# reference length
lref <- Lref(Lc = 264, Linf = 528)
# calculate component f
f <- f(Lmean = lmean, Lref = lref, units = "mm")
# harvest rate
data(ple7e_idx)
data(ple7e_catch)
df <- merge(ple7e_catch, ple7e_idx, all = TRUE) # combine catch & index data
hr <- HR(df, units_catch = "tonnes", units_index = "kg/hr")
# calculate (relative) target harvest rate
HR <- F(hr, f)
HR
advice(HR)
plot(HR)

# application in following years without updating target harvest rate
HR <- F(hr, yr_ref = c(2016, 2019))

# load harvest rate time series and length-based indicator
data(ple7e_hr)
data(ple7e_f2)
# calculate target harvest rate
HR <- F(ple7e_hr, ple7e_f2)
HR
advice(HR)
plot(HR)

# use reference years when using in following years
F(ple7e_hr, yr_ref = c(2016, 2019))

# full example with ple7e data
data(ple7e_length)
# calculate (pooled) length at first capture first
lc <- Lc(data = ple7e_length, pool = 2017:2021)
# calculate mean catch length
lmean <- Lmean(data = ple7e_length, Lc = lc, units = "mm")
# reference length
lref <- Lref(Lc = 264, Linf = 528)
# calculate component f
f <- f(Lmean = lmean, Lref = lref, units = "mm")
# harvest rate
data(ple7e_idx)
data(ple7e_catch)
df <- merge(ple7e_catch, ple7e_idx, all = TRUE) # combine catch & index data
hr <- HR(df, units_catch = "tonnes", units_index = "kg/hr")
# calculate (relative) target harvest rate
HR <- F(hr, f)
HR
advice(HR)
plot(HR)

# application in following years without updating target harvest rate
HR <- F(hr, yr_ref = c(2016, 2019))

f-class

Description

An S4 class to represent component f of the rfb rule.

This class (f) stores the input for component f (the length indicator as well as the resulting f value.

Slots

value: The value of component f
indicator: Length indicator time series
yr_last: numeric. The last year with data.
years: Years with data.
Lmean: Mean catch length.
Lref: Reference catch length.
n0: Time lag between the last index year and the last year to be used.
units: character. The units of the biomass index, e.g. 'kg/hr'.
hcr: factor. The harvest control rule (hcr) for which component f is used (rfb).

F

Description

An S4 class to represent component HR (the target harvest rate, previously called "F") of the chr rule.

This class (F) stores the input for the target harvest rate (if any) as well as the resulting target harvest rate.

Slots

value: The target harvest rate value.
metric: The metric for the harvest rate (e.g. catch, landings, or dead catch)
data: data.frame. The data (harvest rates) used for calculating the target harvest rate.
yr_ref: numeric. The years from which data are used.
units: character. The units of the harvest rate.
HR: HR. The harvest rate input data.
indicator: F. The indicator used to select years of the harvest rate.
hcr: character. The harvest control rule (hcr) for which the index is used. Only applicable to 'chr'.
MSE: logical. Is the harvest rate a generic value or was it calculated with stock-specific simulations (MSE)? Defaults to FALSE.
multiplier: numeric. Optional. Multiplier to adjust the target harvest rate. Only applicable if MSE=TRUE.

Calculation of the (relative) harvest rate

Description

The (relative) harvest rate is calculated by dividing the catch values by biomass index values.

Usage

HR(
  object,
  split_discards = FALSE,
  discard_survival,
  units_catch,
  units_index,
  units,
  ...
)
HR(
  object,
  split_discards = FALSE,
  discard_survival,
  units_catch,
  units_index,
  units,
  ...
)

Arguments

object

The data to use. Usually a data.frame with columns 'year', 'catch' and 'index'.

split_discards

Shall the catch be split into landings and discards? Defaults to FALSE.

discard_survival

Discard survival (%). If split_discards=TRUE, this will be used to calculate the dead discards and these will be used in the harvest rate calculation.

units_catch

Optional. The units of the catch, e.g. 'tonnes'.

units_index

Optional. The units of the biomass index, e.g. 'kg/hr'.

units

Optional. The units of the harvest rate. Can be derived automatically from units_catch and units_index.

...

Additional arguments. Not currently used.

Details

Usually, this functions is used by providing a data.frame with columns 'year', 'catch' and 'index'. The catch can be split into landings and discards by providing 'landings' and 'discards' columns. The harvest rate can be calculated on the dead catch by specifying split_catch=TRUE and defining discard_survival. In this case, the harvest rate will be calculated on the dead catch (landings plus proportion of discards that die).

If an object of class HR is provided, its validity is checked.

Value

An object of class HR with the harvest rate value(s).

References

ICES. 2025. ICES Guidelines - Advice rules for stocks in category 2 and 3. Version 3. ICES Guidelines and Policies - Advice Technical Guidelines. 31 pp. https://doi.org/10.17895/ices.pub.28506179.

Examples


# create data.frame with data
df <- data.frame(year = 2017:2021, 
                 index = c(1.33, 1.13, 0.84, 0.60, 1.03),
                 catch = c(2949, 2513, 2091, 1888, 1615))
# calculate harvest rate
HR(df)

# check objects validity
HR(HR(df))

# plot harvest rate
# plot(HR(df, units_catch = "tonnes", units_index = "kg/hr"))

# create data.frame with data
df <- data.frame(year = 2017:2021, 
                 index = c(1.33, 1.13, 0.84, 0.60, 1.03),
                 catch = c(2949, 2513, 2091, 1888, 1615))
# calculate harvest rate
HR(df)

# check objects validity
HR(HR(df))

# plot harvest rate
# plot(HR(df, units_catch = "tonnes", units_index = "kg/hr"))

HR-class

Description

An S4 class to represent the harvest rate (hr) of the chr rule.

This class (HR) stores the input for the harvest rate (catch, landings) as well as the resulting harvest rates.

Slots

value: The values of the harvest rate time series.
metric: The metric for the harvest rate (e.g. catch, landings, or dead catch)
data: data.frame. The input data (catch and index values)
units: character. The units of the harvest rate.
units_catch: character. The units of the catch.
units_index: character. The units of the index.
hcr: character. The harvest control rule (hcr) for which the index is used. Only applicable to 'chr'.

chr rule - component I (biomass index value)

Description

This function calculates component I (the last biomass index value) of the chr rule. The index needs to be a biomass index without age structure.

Usage

I(object, lag = 0, n_yrs = 1, units, hcr = "chr", ...)

chr_I(object, lag = 0, n_yrs = 1, units, hcr = "chr", ...)
I(object, lag = 0, n_yrs = 1, units, hcr = "chr", ...)

chr_I(object, lag = 0, n_yrs = 1, units, hcr = "chr", ...)

Arguments

object

The biomass index. Can be a data.frame with columns 'data' and 'index', a vector, or a single value.

lag

Optional. The time lag (in years) between the last available index value and the value to be used. Defaults to 0 (the last value is used).

n_yrs

Optional. The number of years if an average index value is used. Defaults to 1 (use last year's value only).

units

Optional. The units of the biomass index, e.g. 'kg/hr'. Only used for plotting.

hcr

Optional. Should be 'chr'.

...

Additional arguments. Not used.

Details

See ICES (2025) for the full definition definition.

Usually, this method is used by providing only a biomass index, e.g. as a data.frame. The method uses this index, and takes the last index value.

chr_I() is an alias for I() with identical arguments and functionality.

Value

An object of class I with the value of the biomass index

Warning

For application in ICES, do not change the defaults unless the change is supported by stock-specific simulations.

References

ICES. 2025. ICES Guidelines - Advice rules for stocks in category 2 and 3. Version 3. ICES Guidelines and Policies - Advice Technical Guidelines. 31 pp. https://doi.org/10.17895/ices.pub.28506179.

Examples

# Use a data.frame with index values
df_idx <- data.frame(year = 2017:2021,
                     index = c(1.33, 1.13, 0.84, 0.60, 1.03))
I <- I(df_idx)
I
advice(I)


# If only the value of the last biomass index is known
I(1)

# ple7e example data
data(ple7e_idx)
I <- I(ple7e_idx)
advice(I)
plot(I)

# Use a data.frame with index values
df_idx <- data.frame(year = 2017:2021,
                     index = c(1.33, 1.13, 0.84, 0.60, 1.03))
I <- I(df_idx)
I
advice(I)


# If only the value of the last biomass index is known
I(1)

# ple7e example data
data(ple7e_idx)
I <- I(ple7e_idx)
advice(I)
plot(I)

I-class

Description

An S4 class to represent component I (the current biomass index value) of the chr rule.

This class (I) stores the input for component I as well as the resulting I value.

Slots

value: The value of component I
lag: The time lag (in years) between the last available index value and the value to be used.
n_years: numeric. The number of years used for the index value.
idx: data.frame. A data.frame with the index values.
yr_last: numeric. The last year with index data.
units: character. The units of the biomass index, e.g. 'kg/hr'.
hcr: character. The harvest control rule (hcr) for which the index is used. Only applicable to 'chr'.

indicator

Description

This function returns the indicator value(s) for the empirical harvest control rules, e.g. the length indicator.

Usage

indicator(object)

## S4 method for signature 'f'
indicator(object)
indicator(object)

## S4 method for signature 'f'
indicator(object)

Arguments

object

The object from which the indicator is requested.

Return the inverse indicator for component f of the chr rule.

Description

Return the inverse indicator for component f of the chr rule.

Usage

inverse_indicator(object)
inverse_indicator(object)

Arguments

object

An object of class f.

Value

A data.frame with the inverse length indicator value(s).

Length at first capture Lc

Description

This function calculates length at first capture Lc from a length frequency distribution for use with the rfb/chr rules.

Usage

Lc(
  data,
  pool = FALSE,
  average = FALSE,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  units,
  ...
)

## S4 method for signature 'numeric'
Lc(
  data,
  pool = FALSE,
  average = FALSE,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  units,
  ...
)

## S4 method for signature 'Lc'
Lc(
  data,
  pool = FALSE,
  average = FALSE,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  units,
  ...
)

## S4 method for signature 'data.frame'
Lc(
  data,
  pool = FALSE,
  average = FALSE,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  units,
  ...
)
Lc(
  data,
  pool = FALSE,
  average = FALSE,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  units,
  ...
)

## S4 method for signature 'numeric'
Lc(
  data,
  pool = FALSE,
  average = FALSE,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  units,
  ...
)

## S4 method for signature 'Lc'
Lc(
  data,
  pool = FALSE,
  average = FALSE,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  units,
  ...
)

## S4 method for signature 'data.frame'
Lc(
  data,
  pool = FALSE,
  average = FALSE,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  units,
  ...
)

Arguments

data

The input data with the length distribution. (see details below)

pool

Pool data from several years in the calculation? TRUE/FALSE or a vector specifying years to use.

average

Calculate Lc as the average of several annual values? TRUE/FALSE or a vector specifying years to use.

lmin

Optional. Smallest length class to use. If defined, length classes below lmin are ignored.

lmax

Optional. Largest length class to use. If defined, length classes above lmax are ignored.

lstep

Optional. Size of length classes. Allows combining length classes into larger length classes. (see details below)

rounding

Optional. The method used to round length classes when using lstep. Defaults to floor, can also be ceiling or round.

units

Units of length data, e.g. "cm".

...

Additional arguments. Not currently used.

Details

Length at first capture Lc is defined as the first length class, in which the numbers of fish is at or above the mode of the distribution (the length class with the highest number of fish).

The length distribution is passed to Lc with the argument data. data is ideally a data.frame with columns "year", "length", and "numbers".

The argument pool allows the pooling of length data from several years in the estimation of Lc. If set to FALSE (default), Lc will be calculated for each year, if set to TRUE, all years will be combined. Alternatively, a vector of years can be provided and only these years will be used.

The argument average allows the averaging of annual Lc values over several years. If set to FALSE (default), Lc will be calculated for each year, if set to TRUE, Lc values from all years will be averaged. Alternatively, a vector of years can be provided and only these years will be used for the average.

The optional arguments lmin and lmax allow removing of length classes outside this range. lstep can be used to combine the length into broader length classes. This can be useful if data are noisy with several local minima/maxima and to smooth the length distribution.

Value

An object of class Lc

Note

For application with the rfb or chr rule, Lc should be set once in the first year of the implementation. At every subsequent application of the method, the previous Lc should then be kept unless a substantial change happened (e.g. because of changed in the fishery or fishery selectivity).

References

ICES. 2025. ICES Guidelines - Advice rules for stocks in category 2 and 3. Version 3. ICES Guidelines and Policies - Advice Technical Guidelines. 31 pp. https://doi.org/10.17895/ices.pub.28506179.

Examples

# example data for plaice
data(ple7e_length)
# annual length at first capture
lc <- Lc(data = ple7e_length)
lc
plot(lc)

# pool data over several years (recommended)
lc <- Lc(data = ple7e_length, pool = 2017:2021)
plot(lc)


# example data for plaice
data(ple7e_length)
# annual length at first capture
lc <- Lc(data = ple7e_length)
lc
plot(lc)

# pool data over several years (recommended)
lc <- Lc(data = ple7e_length, pool = 2017:2021)
plot(lc)

An S4 class to represent length at first capture

Description

This class (Lc) stores the input data (length frequencies) for the length at first capture and the resulting length at first capture value(s).

Slots

value: The length at first capture value(s)
summary: A summary of the length at first capture value(s)
years: The years used in the calculation of length at first capture
pooled: Are length data from several years combined (pooled)?
averaged: Are annual values from several years average?
units: The units for length data (e.g. cm)
data: The data (length frequencies) used in the calculation

Mean catch length Lmean

Description

This function calculates the mean catch length above the length of first capture.

Usage

Lmean(
  data,
  Lc,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  include_Lc = TRUE,
  units,
  ...
)

## S4 method for signature 'numeric,missing'
Lmean(
  data,
  Lc,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  include_Lc = TRUE,
  units,
  ...
)

## S4 method for signature 'Lmean,missing'
Lmean(
  data,
  Lc,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  include_Lc = TRUE,
  units,
  ...
)

## S4 method for signature 'data.frame,missing'
Lmean(
  data,
  Lc,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  include_Lc = TRUE,
  units,
  ...
)

## S4 method for signature 'data.frame,data.frame'
Lmean(
  data,
  Lc,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  include_Lc = include_Lc,
  units,
  ...
)

## S4 method for signature 'data.frame,Lc'
Lmean(
  data,
  Lc,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  include_Lc = include_Lc,
  units,
  ...
)
Lmean(
  data,
  Lc,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  include_Lc = TRUE,
  units,
  ...
)

## S4 method for signature 'numeric,missing'
Lmean(
  data,
  Lc,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  include_Lc = TRUE,
  units,
  ...
)

## S4 method for signature 'Lmean,missing'
Lmean(
  data,
  Lc,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  include_Lc = TRUE,
  units,
  ...
)

## S4 method for signature 'data.frame,missing'
Lmean(
  data,
  Lc,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  include_Lc = TRUE,
  units,
  ...
)

## S4 method for signature 'data.frame,data.frame'
Lmean(
  data,
  Lc,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  include_Lc = include_Lc,
  units,
  ...
)

## S4 method for signature 'data.frame,Lc'
Lmean(
  data,
  Lc,
  lmin,
  lmax,
  lstep,
  rounding = floor,
  include_Lc = include_Lc,
  units,
  ...
)

Arguments

data

The input data with the length distribution. (see details below)

Lc

Length of first capture. Either a single value used for all years or a data.frame with columns "year" and "Lc".

lmin

Optional. Smallest length class to use. If defined, length classes below lmin are ignored.

lmax

Optional. Largest length class to use. If defined, length classes above lmax are ignored.

lstep

Optional. Size of length classes. Allows combining length classes into larger length classes. (see details below)

rounding

Optional. The method used to round length classes when using lstep. Defaults to floor, can also be ceiling or round.

include_Lc

Optional. Include individuals at the length of first capture (Lc)? Defaults to TRUE. If set to FALSE, only individuals above Lc are considered.

units

Units of length data, e.g. "cm".

...

Additional arguments. Not currently used.

Details

The mean catch length is calculated as the mean length of fish in the catch which are above the length of first capture (Lc). The mean catch length is essentially the mean of lengths, weighted by the number of fish in the length classes.

The length distribution is passed to Lmean with the argument data. data is ideally a data.frame with columns "year", "length", and "numbers". An optional column, "catch_category", can be included to distinguish between categories such as "landings" and "discards".

The mean catch length calculation only considers length classes above the length of first capture Lc. Lc can be provided as a single value (recommended) or annual values can be provided with a data.frame with columns "year" and "Lc". Generally, it is recommended to use a single value for Lc and only change it if there are substantial changes between years.

If Lc is not provided, the input data is passed to Lc() to estimate Lc.

By default, the calculation of the mean length includes individuals at the length of first capture (Lc). This can be manually turned off by providing the argument include_Lc = FALSE. If this is turned off, only fish above Lc are considered.

Value

An object of class Lc

References

ICES. 2025. ICES Guidelines - Advice rules for stocks in category 2 and 3. Version 3. ICES Guidelines and Policies - Advice Technical Guidelines. 31 pp. https://doi.org/10.17895/ices.pub.28506179.

Examples

# example data for plaice
data(ple7e_length)
# calculate (pooled) length at first capture first
lc <- Lc(data = ple7e_length, pool = 2017:2021)
# mean catch length
lmean <- Lmean(data = ple7e_length, Lc = lc, units = "mm")
lmean
plot(lmean)


# example data for plaice
data(ple7e_length)
# calculate (pooled) length at first capture first
lc <- Lc(data = ple7e_length, pool = 2017:2021)
# mean catch length
lmean <- Lmean(data = ple7e_length, Lc = lc, units = "mm")
lmean
plot(lmean)

An S4 class to represent mean catch length

Description

This class (Lmean) stores the input data (length frequencies) for the mean catch length and the resulting mean catch length(s), above the length at first capture (Lc).

Slots

value: The mean catch length value(s)
summary: A summary of the mean catch length value(s)
years: The years for which mean catch length is calculated
Lc: The length at first capture
include_Lc: Include Lc in the calculation of the mean length? (default: TRUE)
units: The units for length data (e.g. cm)
data: The data (length frequencies) used in the calculation

Reference catch length

Description

This function calculates the reference catch length.

Usage

Lref(
  value,
  basis = "LF=M",
  Lc,
  Linf,
  Mk = 1.5,
  gamma = 1,
  theta = 1/Mk,
  units,
  ...
)
Lref(
  value,
  basis = "LF=M",
  Lc,
  Linf,
  Mk = 1.5,
  gamma = 1,
  theta = 1/Mk,
  units,
  ...
)

Arguments

value

Optional. The reference length value, if already known.

basis

The basis for the calculation, defaults to "LF=M".

Lc

The length at first capture.

Linf

The asymptotic length from a von Bertalanffy growth model.

Mk

The ratio of natural mortality M to von Bertalanffy k.

gamma

Links fishing mortality F to natural mortality M to set the proxy for MSY (see details).

theta

Alternative option to link M and k.

units

The units for length data (e.g. cm)

...

Additional arguments. Not currently used.

Details

The default is to calculate the MSY proxy reference length following Beverton & Holt (1957) and as derived by Jardim et al. (2015):

(theta * Linf + Lc * (gamma + 1)) / (theta + gamma + 1)

where Linf is the asymptotic length of a von Bertalanffy growth model, Lc the length of first capture, theta links von Bertalanffy individual growth parameter k and natural mortality (M) through k = theta * M and gamma links fishing mortality F to M through F = gamma * M. The default reference length calculation assumes theta = 2/3, i.e. that M/k = 1.5 and that gamma = 1, i.e. that F = M can be used as a proxy for MSY. The ratio M/k can be set directly with the argument Mk or indirectly with theta which defaults to 1/Mk.

Value

An object of class Lref

Warning

Changing the default parameters is discouraged. Any change to the default parameters should be well justified.

The reference length is usually set once the first time the rfb rule is applied and should then be kept constant unless there a substantial changes in the fishery or fishery selectivity.

References

Beverton, R. J. H., and Holt, S. J. 1957. On the Dynamics of Exploited Fish Populations. Fishery Investigation Series 2. HMSO for Ministry of Agriculture, Fisheries and Food, London. 533 pp. ICES. 2025. ICES Guidelines - Advice rules for stocks in category 2 and 3. Version 3. ICES Guidelines and Policies - Advice Technical Guidelines. 31 pp. https://doi.org/10.17895/ices.pub.28506179. Jardim, E., Azevedo, M., and Brites, N. M. 2015. Harvest control rules for data limited stocks using length-based reference points and survey biomass indices. Fisheries Research, 171: 12–19. https://doi.org/10.1016/j.fishres.2014.11.013.

Examples

# calculate MSY proxy LF=M
Lref(Lc = 26.4, Linf = 58.5)

# calculate MSY proxy LF=M
Lref(Lc = 26.4, Linf = 58.5)

An S4 class to represent the reference catch length

Description

This class (Lref) stores the value of the reference catch length, e.g. LF=M.

Arguments

value

The reference catch length.

basis

The basis for the calculation, defaults to "LF=M".

Lc

The length at first capture.

Linf

The asymptotic length from a von Bertalanffy growth model.

Mk

The ratio of natural mortality M to von Bertalanffy k.

gamma

Links fishing mortality F to natural mortality M to set the proxy for MSY (see details).

theta

Alternative option to link M and k.

years

Years, if annual values provided.

units

The units for length data (e.g. cm)

rfb/rb/chr rule - component m (multiplier)

Description

This function returns the default multiplier for the rfb, rb, and chr rules.

Usage

m(object, hcr, k, MSE, ...)

rfb_m(object, hcr = "rfb", k, MSE, ...)

rb_m(object, hcr = "rb", k, MSE, ...)

chr_m(object, hcr = "chr", k, MSE, ...)
m(object, hcr, k, MSE, ...)

rfb_m(object, hcr = "rfb", k, MSE, ...)

rb_m(object, hcr = "rb", k, MSE, ...)

chr_m(object, hcr = "chr", k, MSE, ...)

Arguments

object

Optional. A multiplier m value, if known, or an existing m object.

hcr

The harvest control rule (hcr) for which the multiplier is used. One of 'rfb', 'rb', or 'chr'.

k

Optional. The von Bertalanffy k parameter (individual growth rate, unit: 1/year).

MSE

Optional. logical. Default multiplier or multiplier derived from stock specific MSE?

...

Additional arguments. Not used.

Details

rfb_m(), rb_m(), and chr_m() are aliases for m() in which the hcr argument is already set to 'rfb', 'rb', or 'chr'.

The multiplier is set following ICES (2025).

For the rfb rule, the multiplier is set depending on the von Bertalanffy parameter k (individual growth rate, units: 1/year; ICES, 2022). For species where k is below 0.2/year, the multiplier is set to m=0.95. For species where k is at or above 0.2/year, but below 0.32/year, the multiplier is set to m=0.90. If the rfb rule is applied and k is unknown, the more precautionary multiplier of m=0.90 is used.

For the rb rule, the multiplier is set to m=0.50 (ICES, 2022).

For the chr rule, the multiplier is set to m=0.50 (ICES, 2022).

Value

An object of class m

Warning

For application in ICES, do not change the default multiplier unless the change is supported by stock-specific simulations.

References

ICES. 2025. ICES Guidelines - Advice rules for stocks in category 2 and 3. Version 3. ICES Guidelines and Policies - Advice Technical Guidelines. 31 pp. https://doi.org/10.17895/ices.pub.28506179.

Examples

# rfb rule with known k
rfb_m(k = 0.1) # 0.95
m(hcr = "rfb", k = 0.1) # 0.95
rfb_m(k = 0.25) # 0.90
m(hcr = "rfb", k = 0.25) # 0.90
# rfb rule with unknown k
rfb_m() # 0.90
m(hcr = "rfb") # 0.90

# rb rule
rb_m() # 0.5
m(hcr = "rb") # 0.5

# chr rule
chr_m() # 0.5
m(hcr = "chr") # 0.5

# rfb rule with known k
rfb_m(k = 0.1) # 0.95
m(hcr = "rfb", k = 0.1) # 0.95
rfb_m(k = 0.25) # 0.90
m(hcr = "rfb", k = 0.25) # 0.90
# rfb rule with unknown k
rfb_m() # 0.90
m(hcr = "rfb") # 0.90

# rb rule
rb_m() # 0.5
m(hcr = "rb") # 0.5

# chr rule
chr_m() # 0.5
m(hcr = "chr") # 0.5

m-class

Description

An S4 class to represent component m (the multiplier) of the rfb, rb, and chr rules.

The classes rfb_m, rb_m, and chr_m inherit from m and their only difference is that the slot hcr is set to the corresponding catch rule name ('rfb', 'rb', or 'chr').

Slots

value: The value of component m
hcr: The harvest control rule (hcr) for which the multiplier is used. One of 'rfb', 'rb', or 'chr'.
k: Optional. The von Bertalanffy k parameter (individual growth rate, unit: 1/year).
MSE: logical. Generic multiplier or multiplier based on stock-specific simulations.

Western English Channel plaice example data

Description

This data set contains 2022 example data from Western English Channel plaice (ple.27.7e) to illustrate the application of the ICES category 3 empirical harvest control rules.

Usage

ple7e_catch

ple7e_f

ple7e_f2

ple7e_hr

ple7e_idx

ple7e_length

ple7e_WKBPLAICE
ple7e_catch

ple7e_f

ple7e_f2

ple7e_hr

ple7e_idx

ple7e_length

ple7e_WKBPLAICE

Format

An object of class data.frame with 36 rows and 5 columns.

An object of class comp_f of length 1.

An object of class f of length 1.

An object of class HR of length 1.

An object of class data.frame with 19 rows and 2 columns.

An object of class data.frame with 777 rows and 4 columns.

An object of class data.frame with 45 rows and 8 columns.

Source

https://github.com/ices-taf

Plot length frequencies

Description

A convenience function for plotting length frequencies and length reference points.

Usage

## S4 method for signature 'Lc,ANY'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'Lmean,ANY'
plot(x, y, y_label, show.data = TRUE, ...)
## S4 method for signature 'Lc,ANY'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'Lmean,ANY'
plot(x, y, y_label, show.data = TRUE, ...)

Arguments

x

An object of class Lc, Lmean, ...

y

Not used.

y_label

Not used.

show.data

Not used.

...

Additional arguments. Not currently used.

Value

An object of class gg/ggplot with the plot. Can be manipulated with the usual ggplot2 commands, e.g. ylim().

rfb/rb rule - component r (index ratio)

Description

This function calculates component r (the index ratio) of the rfb and rb rule. The index needs to be a biomass index without age structure.

Usage

r(object, n0, n1, n2, units, hcr, ...)

rfb_r(object, n0, n1, n2, units, hcr = "rfb", ...)

rb_r(object, n0, n1, n2, units, hcr = "rb", ...)
r(object, n0, n1, n2, units, hcr, ...)

rfb_r(object, n0, n1, n2, units, hcr = "rfb", ...)

rb_r(object, n0, n1, n2, units, hcr = "rb", ...)

Arguments

object

The biomass index. Can be a data.frame with columns 'data' and 'index' or an FLQuant object defined by FLCore.

n0

Optional. Time lag between the last index year and the last year to be used. By default, the last index year is used (n0=0)

n1

Optional. Number of years used in the numerator of the r component. Defaults to 2 (i.e. n1 and n2 use a 2 over 3 ratio).

n2

Optional. Number of years used in the denominator of the r component. Defaults to 3.

units

Optional. The units of the biomass index, e.g. 'kg/hr'. Only used for plotting.

hcr

Optional. One of 'rfb' or 'rb'.

...

Additional arguments. Not used.

Details

Usually, this method is used by providing only a biomass index, e.g. as a data.frame. The default index ratio is the average of the last two index values, divided by the average of the three preceeding index values.

The index ratio is identical in the rfb and rb rules. rfb_r() and rb_b() are aliases for r() with identical arguments and functionality.

Value

An object of class r

Warning

For application in ICES, do not change the defaults (n0, n1, n2) unless the change is supported by stock-specific simulations.

References

ICES. 2025. ICES Guidelines - Advice rules for stocks in category 2 and 3. Version 3. ICES Guidelines and Policies - Advice Technical Guidelines. 31 pp. https://doi.org/10.17895/ices.pub.28506179.

Examples

# If the value of r is known
rfb_r(0.9)
r(0.9)

# Use a data.frame with index values
df_idx <- data.frame(year = 2017:2021,
                     index = c(1.33, 1.13, 0.84, 0.60, 1.03))
r <- r(df_idx)
r
advice(r)

# plot
plot(r(df_idx, units = "kg/hr"))

# If the value of r is known
rfb_r(0.9)
r(0.9)

# Use a data.frame with index values
df_idx <- data.frame(year = 2017:2021,
                     index = c(1.33, 1.13, 0.84, 0.60, 1.03))
r <- r(df_idx)
r
advice(r)

# plot
plot(r(df_idx, units = "kg/hr"))

r-class

Description

An S4 class to represent component r of the rfb and rb rules.

This class (r) stores the input for component r (the index ratio ) as well as the resulting r value.

Slots

value: The value of component r
n0,n1,n2: Parameters for the calculation of the r component. See ?rfb_r for details.
yr_last: numeric. The last year with index data.
n1_yrs,n2_yrs: numeric. The years used for n1 and n2.
n1_mean,n2_mean: numeric. The mean index values over n1_yrs and n2_yrs.
idx: data.frame. A data.frame with the index values.
units: character. The units of the biomass index, e.g. 'kg/hr'.
hcr: character. The harvest control rule (hcr) for which the biomass safeguard is used. One of 'rfb' or 'rb'.

rb rule

Description

This function applies the rb rule.

Usage

rb(
  object,
  A,
  r,
  b,
  m,
  cap = "conditional",
  cap_upper = 20,
  cap_lower = -30,
  years,
  frequency = "biennial",
  discard_rate = NA,
  ...
)
rb(
  object,
  A,
  r,
  b,
  m,
  cap = "conditional",
  cap_upper = 20,
  cap_lower = -30,
  years,
  frequency = "biennial",
  discard_rate = NA,
  ...
)

Arguments

object

Optional. An object of class rfb.

A

The reference catch. Should be an object of class A, see A.

r

The biomass index ratio. Should be an object of class r, see r.

b

The biomass safeguard. Should be an object of class b, see b.

m

The multiplier. Should be an object of class m, see m.

cap

logical. The uncertainty cap (stability clause). Defaults to TRUE

cap_upper

Optional. numeric. The maximum allowed increase in the catch advice in %. Default to +20.

cap_lower

Optional. numeric. The maximum allowed decrease in the catch advice in %. Default to -20.

years

Optional. numeric. The years for which the advice should be given.

frequency

Optional. The frequency of the advice ('annual'/'biennial'/'triennial'). Defaults to 'biennial'.

discard_rate

Optional. The discard rate for the advice (numeric). If provided, advice values for catch and landings are given.

...

Additional parameters. Not used.

Details

The function requires the elements of the rb rule: A (the reference) catch, r (the biomass index ratio), f (the fising pressure proxy), b (the biomass safeguard) and m (the multiplier). See the help files for details A, vr, b, and m.

Value

An object of class rb.

Warning

For application in ICES, do not change the default parameters (frequency, stability clause, etc) unless the changes are supported by case-specific simulations.

References

ICES. 2025. ICES Guidelines - Advice rules for stocks in category 2 and 3. Version 3. ICES Guidelines and Policies - Advice Technical Guidelines. 31 pp. https://doi.org/10.17895/ices.pub.28506179.

Examples

#' # calculate elements of rb rule for plaice
# reference catch
data(ple7e_catch)
A <- A(object = ple7e_catch, basis = "advice", units = "tonnes", advice_metric = "catch")
# biomass index trend
data(ple7e_idx)
r <- r(ple7e_idx)
# biomass safeguard
b <- b(ple7e_idx)
# multiplier
m <- m(hcr = "rb", k = 0.1)
# apply rb rule
advice <- rb(A = A, r = r, b = b, m = m, discard_rate = 27)
advice
advice(advice)

### application in subsequent years (without updating reference levels)
A <- A(object = ple7e_catch, basis = "advice", units = "tonnes", advice_metric = "catch")
r <- r(ple7e_idx)
b <- b(ple7e_idx, yr_ref = 2007) # use reference year for Itrigger
m <- m(0.95) # keep multiplier
advice <- rb(A = A, r = r, b = b, m = m, discard_rate = 27)
advice
advice(advice)

#' # calculate elements of rb rule for plaice
# reference catch
data(ple7e_catch)
A <- A(object = ple7e_catch, basis = "advice", units = "tonnes", advice_metric = "catch")
# biomass index trend
data(ple7e_idx)
r <- r(ple7e_idx)
# biomass safeguard
b <- b(ple7e_idx)
# multiplier
m <- m(hcr = "rb", k = 0.1)
# apply rb rule
advice <- rb(A = A, r = r, b = b, m = m, discard_rate = 27)
advice
advice(advice)

### application in subsequent years (without updating reference levels)
A <- A(object = ple7e_catch, basis = "advice", units = "tonnes", advice_metric = "catch")
r <- r(ple7e_idx)
b <- b(ple7e_idx, yr_ref = 2007) # use reference year for Itrigger
m <- m(0.95) # keep multiplier
advice <- rb(A = A, r = r, b = b, m = m, discard_rate = 27)
advice
advice(advice)

An S4 class to represent the rb rule.

Description

This class contains the components of the rb rule (rb_A, rb_r, rb_b, rb_m).

Slots

advice: The value of the catch advice.
advice_landings: Landings corresponding to the catch advice.
advice_uncapped: The value of the catch advice without the uncertainty cap.
units: The unit (e.g. tonnes) of the catch advice.
advice_metric: The advice metric, 'catch' or 'landings'.
frequency: The advice frequence (annual/biennial).
years: The years for which the advice is valid.
A: Component A (the reference catch).
r: Component r (the biomass index ratio).
b: Component b (the biomass safeguard).
m: Component m (the multiplier).
cap: Uncertainty cap (stability clause, restricts changes in advice).
cap_lower: Maximum allowed reduction in advice in %, e.g. -30.
cap_upper: Maximum allowed increase in advice in %, e.g. 20.
change: Change in advice compared to previous advice.
change_uncapped: Change in advice compared to previous advice before application of the uncertainty cap.
discard_rate: Discard rate (%).

rfb rule

Description

This function applies the rfb rule.

Usage

rfb(
  object,
  A,
  r,
  f,
  b,
  m,
  cap = "conditional",
  cap_upper = 20,
  cap_lower = -30,
  years,
  frequency = "biennial",
  discard_rate = NA,
  ...
)
rfb(
  object,
  A,
  r,
  f,
  b,
  m,
  cap = "conditional",
  cap_upper = 20,
  cap_lower = -30,
  years,
  frequency = "biennial",
  discard_rate = NA,
  ...
)

Arguments

object

Optional. An object of class rfb.

A

The reference catch. Should be an object of class A, see A.

r

The biomass index ratio. Should be an object of class r, see r.

f

The fishing pressure proxy. Should be an object of class f, see f.

b

The biomass safeguard. Should be an object of class b, see b.

m

The multiplier. Should be an object of class m, see m.

cap

logical. The uncertainty cap (stability clause). Defaults to TRUE

cap_upper

Optional. numeric. The maximum allowed increase in the catch advice in %. Default to +20.

cap_lower

Optional. numeric. The maximum allowed decrease in the catch advice in %. Default to -20.

years

Optional. numeric. The years for which the advice should be given.

frequency

Optional. The frequency of the advice ('annual'/'biennial'/'triennial'). Defaults to 'biennial'.

discard_rate

Optional. The discard rate for the advice (numeric). If provided, advice values for catch and landings are given.

...

Additional parameters. Not used.

Details

The function requires the elements of the rfb rule: A (the reference) catch, r (the biomass index ratio), f (the fising pressure proxy), b (the biomass safeguard) and m (the multiplier). See the help files for details: A, vr, f, b, and m.

Value

An object of class rfb.

Warning

For application in ICES, do not change the default parameters (frequency, stability clause, etc) unless the changes are supported by case-specific simulations.

References

ICES. 2025. ICES Guidelines - Advice rules for stocks in category 2 and 3. Version 3. ICES Guidelines and Policies - Advice Technical Guidelines. 31 pp. https://doi.org/10.17895/ices.pub.28506179.

Examples

# calculate elements of rfb rule for plaice
# reference catch
data(ple7e_catch)
A <- A(object = ple7e_catch, basis = "advice", units = "tonnes", advice_metric = "catch")
# biomass index trend
data(ple7e_idx)
r <- r(ple7e_idx)
plot(r)
# fishing pressure proxy
data(ple7e_length)
lc <- Lc(data = ple7e_length, pool = 2017:2021)
lmean <- Lmean(data = ple7e_length, Lc = lc, units = "mm")
lref <- Lref(Lc = 264, Linf = 585)
f <- f(Lmean = lmean, Lref = lref, units = "mm")
plot(f)
# biomass safeguard
b <- b(ple7e_idx)
plot(b)
plot(b, r)
# multiplier
m <- m(hcr = "rfb", k = 0.1)
# apply rfb rule
advice <- rfb(A = A, r = r, f = f, b = b, m = m, discard_rate = 27)
advice
advice(advice)

### application in subsequent years (without updating reference levels)
A <- A(object = ple7e_catch, basis = "advice", units = "tonnes", advice_metric = "catch")
r <- r(ple7e_idx)
lref <- Lref(344.25) # use previous value
f <- f(Lmean = lmean, Lref = lref, units = "mm")
b <- b(ple7e_idx, yr_ref = 2007) # use reference year for Itrigger
m <- m(0.95) # keep multiplier
advice <- rfb(A = A, r = r, f = f, b = b, m = m, discard_rate = 27)
advice
advice(advice)

# calculate elements of rfb rule for plaice
# reference catch
data(ple7e_catch)
A <- A(object = ple7e_catch, basis = "advice", units = "tonnes", advice_metric = "catch")
# biomass index trend
data(ple7e_idx)
r <- r(ple7e_idx)
plot(r)
# fishing pressure proxy
data(ple7e_length)
lc <- Lc(data = ple7e_length, pool = 2017:2021)
lmean <- Lmean(data = ple7e_length, Lc = lc, units = "mm")
lref <- Lref(Lc = 264, Linf = 585)
f <- f(Lmean = lmean, Lref = lref, units = "mm")
plot(f)
# biomass safeguard
b <- b(ple7e_idx)
plot(b)
plot(b, r)
# multiplier
m <- m(hcr = "rfb", k = 0.1)
# apply rfb rule
advice <- rfb(A = A, r = r, f = f, b = b, m = m, discard_rate = 27)
advice
advice(advice)

### application in subsequent years (without updating reference levels)
A <- A(object = ple7e_catch, basis = "advice", units = "tonnes", advice_metric = "catch")
r <- r(ple7e_idx)
lref <- Lref(344.25) # use previous value
f <- f(Lmean = lmean, Lref = lref, units = "mm")
b <- b(ple7e_idx, yr_ref = 2007) # use reference year for Itrigger
m <- m(0.95) # keep multiplier
advice <- rfb(A = A, r = r, f = f, b = b, m = m, discard_rate = 27)
advice
advice(advice)

Plot elements of the rfb/rb/chr rule

Description

A convenience function for plotting elements of the rfb, rb, and chr rules using ggplot2 and loosely following ICES style figures.

Usage

plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'r,missing'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'b,missing'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'r,b'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'b,r'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'I,missing'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'f,missing'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'F,missing'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'HR,ANY'
plot(x, y, y_label, show.data = TRUE, ...)
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'r,missing'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'b,missing'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'r,b'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'b,r'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'I,missing'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'f,missing'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'F,missing'
plot(x, y, y_label, show.data = TRUE, ...)

## S4 method for signature 'HR,ANY'
plot(x, y, y_label, show.data = TRUE, ...)

Arguments

x

An object of class rfb_r, rfb_b, ...

y

Optional. An additional object of rfb_b, ...

y_label

Optional. The y-axis label.

show.data

Show input data. Only applicable to some methods.

...

Additional arguments. Not used.

Details

Combinations of object are possible, e.g. for the rfb rule, it is possible to plot components r (index ratio) and b (biomass safeguard) on the same plot.

For the chr rule, plotting component f will return a plot with the absolute value of the mean catch length. The inverse indicator length can be plotted with plot(f, inverse = TRUE).

Value

An object of class gg/ggplot with the plot. Can be manipulated with the usual ggplot2 commands, e.g. ylim().

Examples

# Component b 
df_idx <- data.frame(year = 2017:2021,
                     index = c(1.33, 1.13, 0.84, 0.60, 1.03))
b <- rfb_b(df_idx)
plot(b, y_label = "Biomass index in kg/hr")

# Component r
r <- rfb_r(df_idx)
plot(r, y_label = "Biomass index in kg/hr")

# Components r and b combined
plot(r, b)

# Component b 
df_idx <- data.frame(year = 2017:2021,
                     index = c(1.33, 1.13, 0.84, 0.60, 1.03))
b <- rfb_b(df_idx)
plot(b, y_label = "Biomass index in kg/hr")

# Component r
r <- rfb_r(df_idx)
plot(r, y_label = "Biomass index in kg/hr")

# Components r and b combined
plot(r, b)

An S4 class to represent the rfb rule.

Description

This class contains the components of the rfb rule (rfb_A, rfb_r, rfb_f, rfb_b, rfb_m).

Slots

advice: The value of the catch advice.
advice_landings: Landings corresponding to the catch advice.
advice_uncapped: The value of the catch advice without the uncertainty cap.
units: The unit (e.g. tonnes) of the catch advice.
advice_metric: The advice metric, 'catch' or 'landings'.
frequency: The advice frequence (annual/biennial).
years: The years for which the advice is valid.
A: Component A (the reference catch).
r: Component r (the biomass index ratio).
f: Component f (the fishing pressure proxy).
b: Component b (the biomass safeguard).
m: Component m (the multiplier).
cap: Uncertainty cap (stability clause, restricts changes in advice).
cap_lower: Maximum allowed reduction in advice in %, e.g. -30.
cap_upper: Maximum allowed increase in advice in %, e.g. 20.
change: Change in advice compared to previous advice.
change_uncapped: Change in advice compared to previous advice before application of the uncertainty cap.
discard_rate: Discard rate (%).

show

Description

Show a summary of the elements of the empirical harvest control rule

summary

Description

This function returns a summary of any component or the advice for the empirical harvest control rules

Usage

## S4 method for signature 'A'
summary(object, ...)

## S4 method for signature 'HR'
summary(object)

## S4 method for signature 'b'
summary(object, ...)

## S4 method for signature 'm'
summary(object, ...)

## S4 method for signature 'r'
summary(object, ...)
## S4 method for signature 'A'
summary(object, ...)

## S4 method for signature 'HR'
summary(object)

## S4 method for signature 'b'
summary(object, ...)

## S4 method for signature 'm'
summary(object, ...)

## S4 method for signature 'r'
summary(object, ...)

Arguments

object

The object for which a summary is requested.

...

Additional arguments. Not used.

value

Description

This function returns the value of any component or the advice for the empirical harvest control rules

Usage

value(object)

## S4 method for signature 'A'
value(object)

## S4 method for signature 'f'
value(object)

## S4 method for signature 'HR'
value(object)

## S4 method for signature 'F'
value(object)

## S4 method for signature 'I'
value(object)

## S4 method for signature 'm'
value(object)

## S4 method for signature 'chr'
value(object)

## S4 method for signature 'r'
value(object)

## S4 method for signature 'b'
value(object)

## S4 method for signature 'rb'
value(object)

## S4 method for signature 'rfb'
value(object)
value(object)

## S4 method for signature 'A'
value(object)

## S4 method for signature 'f'
value(object)

## S4 method for signature 'HR'
value(object)

## S4 method for signature 'F'
value(object)

## S4 method for signature 'I'
value(object)

## S4 method for signature 'm'
value(object)

## S4 method for signature 'chr'
value(object)

## S4 method for signature 'r'
value(object)

## S4 method for signature 'b'
value(object)

## S4 method for signature 'rb'
value(object)

## S4 method for signature 'rfb'
value(object)

Arguments

object

The object from which the value is extracted.

Package 'cat3advice'

Help Index

A-class

Description

Slots

ICES advice sheet-style output table

Description

Usage

Arguments

Value

rb/rfb/chr rule - component b (biomass safeguard)

Description

Usage

Arguments

Details

Value

Warning

References

Examples

b-class

Description

Slots

chr rule

Description

Usage

Arguments

Details

Value

Warning

References

Examples

An S4 class to represent the chr rule.

Description

Slots

rfb rule - component f (fishing pressure proxy, length indicator)

Description

Usage

Arguments

Details

Value

Note

References

Examples

Calculation of the (relative) harvest rate target

Description

Usage

Arguments

Details

Value

Warning

References

Examples

f-class

Description

Slots

F

Description

Slots

Calculation of the (relative) harvest rate

Description

Usage

Arguments

Details

Value

References

Examples

HR-class

Description

Slots

chr rule - component I (biomass index value)

Description

Usage

Arguments

Details

Value

Warning

References

Examples

I-class

Description