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.0.7
Built:	2024-11-09 04:53:41 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)
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'.

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, n0, units, hcr, ...)

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

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

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

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

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

chr_b(
  object,
  idx_value,
  Itrigger,
  Iloss,
  w,
  yr_ref,
  n0,
  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.
`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`)
`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. 2022. ICES technical guidance for harvest control rules and stock assessments for stocks in categories 2 and 3. In Report of ICES Advisory Committee, 2022. ICES Advice 2022, Section 16.4.11, 20 pp. https://doi.org/10.17895/ices.advice.19801564.

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.
n0: Time lag between the last index year and the last year to be used.
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,
  ...
)
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,
  ...
)

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 for the advice. If provided, advice values for catch and landings are given.
`...`	Additional parameters. Not used.

Details

This function applies the chr rule following the ICES technical guidelines (ICES, 2022). The function requires the elements of the chr rule: I (the biomass index, see chr_I), F_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 * F_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)

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

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)
F <- F(hr, f) # calculate (relative) target harvest rate
plot(F)
# biomass safeguard
b <- b(ple7e_idx)
plot(b)
# multiplier
m <- m(hcr = "chr")

# apply chr rule
advice <- chr(A = A, I = I, F = F, 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")
F <- 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 = F, b = b, m = m, discard_rate = 27)
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)
F <- F(hr, f) # calculate (relative) target harvest rate
plot(F)
# biomass safeguard
b <- b(ple7e_idx)
plot(b)
# multiplier
m <- m(hcr = "chr")

# apply chr rule
advice <- chr(A = A, I = I, F = F, 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")
F <- 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 = F, b = b, m = m, discard_rate = 27)
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_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: The reference catch (previous catch advice).
I: Component I (the biomass index value).
F: Component 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 (%).

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

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, ...)
F(object, indicator, yr_ref, units, ...)

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`.
`...`	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 is 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, 2022) for details.

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

Examples


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

# 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
F <- F(hr, f)
F
advice(F)
plot(F)

# application in following years without updating target harvest rate
F <- 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
F <- F(ple7e_hr, ple7e_f2)
F
advice(F)
plot(F)

# 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
F <- F(hr, f)
F
advice(F)
plot(F)

# application in following years without updating target harvest rate
F <- 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 F (the target harvest rate) 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.
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'.

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, units_catch, units_index, units, ...)
HR(object, units_catch, units_index, units, ...)

Arguments

`object`	The data to use. Usually a `data.frame` with columns 'year', 'catch' and 'index'.
`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' is provided. The catch can be split into landings and discards by providing 'landings' and 'discards' columns.

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

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.
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 (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, 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

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

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

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. 2022. ICES technical guidance for harvest control rules and stock assessments for stocks in categories 2 and 3. In Report of ICES Advisory Committee, 2022. ICES Advice 2022, Section 16.4.11, 20 pp. https://doi.org/10.17895/ices.advice.19801564. 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, ...)

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

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

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

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

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

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

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).
`...`	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 (2022).

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

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).

Western English Channel plaice example data 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.

Description

Western English Channel plaice example data

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_catch

ple7e_f

ple7e_f2

ple7e_hr

ple7e_idx

ple7e_length

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.

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

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

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

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 Show a summary of the elements of the empirical harvest control rule

Description

show

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