Package 'icesAdvice' reference manual

Package 'icesAdvice'

Title:	Functions Related to ICES Advice
Description:	A collection of functions that facilitate computational steps related to advice for fisheries management, according to ICES guidelines. These include methods for calculating reference points and model diagnostics.
Authors:	Arni Magnusson [aut], Colin Millar [aut, cre], Anne Cooper [aut], Ruben Verkempynck [ctb], Raphael Girardin [ctb]
Maintainer:	Colin Millar <[email protected]>
License:	GPL-3
Version:	2.1.1
Built:	2024-08-19 02:30:25 UTC
Source:	https://github.com/ices-tools-prod/icesAdvice

Title:

Functions Related to ICES Advice

Description:

A collection of functions that facilitate computational steps related to advice for fisheries management, according to ICES guidelines. These include methods for calculating reference points and model diagnostics.

Authors:

Arni Magnusson [aut], Colin Millar [aut, cre], Anne Cooper [aut], Ruben Verkempynck [ctb], Raphael Girardin [ctb]

Maintainer:

Colin Millar <[email protected]>

License:

GPL-3

Version:

2.1.1

Built:

2024-08-19 02:30:25 UTC

Source:

https://github.com/ices-tools-prod/icesAdvice

Help Index

Functions Related to ICES Advice

Description

Details

Calculate ICES advice:

`DLS3.2`	DLS method 3.2
`icesRound`	rounding method

Calculate PA reference points and sigma:

`Bpa`	from Blim
`Fpa`	from Flim
`sigmaCI`	from confidence interval
`sigmaPA`	from PA reference points

Other calculations:

`agesFbar`	suitable age range for Fbar
`mohn`	Mohn's rho retrospective diagnosis

Read and write files:

`read.dls`	read `DLS3.2` results from file
`write.dls`	write `DLS3.2` results to file

Example tables:

`gss`	Greater silver smelt catch at age
`shake`	Southern hake retro

Author(s)

Arni Magnusson, Colin Millar, and Anne Cooper.

References

ICES advice: https://ices.dk/advice

Age Range for Fbar

Description

Calculate a suitable age range for average fishing mortality (Fbar).

Usage

agesFbar(cn, probs = c(0.1, 0.9), plot = FALSE, main = NULL,
  xlab = NULL, ylab = NULL, col = NULL)
agesFbar(cn, probs = c(0.1, 0.9), plot = FALSE, main = NULL,
  xlab = NULL, ylab = NULL, col = NULL)

Arguments

`cn`	a vector, matrix, table, or data frame containing the catch at age as integers or decimal values. Ages are indicated in names if `cn` is a vector, or in column names if `cn` is a matrix, table, or data frame.
`probs`	a vector of probabilities, e.g. `c(0.1, 0.9)` to calculate the age range that covers 80% of the catch.
`plot`	whether to indicate the cut points on a bar plot.
`main`	passed to `barplot`.
`xlab`	passed to `barplot`.
`ylab`	passed to `barplot`.
`col`	passed to `barplot`.

Value

Vector of two values, the lower and upper age. These can be rounded to construct an Fbar age range.

Note

The calculations are more complicated than traditional quantiles, since the ages for Fbar are discrete and not continuous. For example, with a continuous variable, Fbar[5-6] has width one, but for a discrete variable it has width two.

The algorithm cuts off exactly probs[1] and 1-probs[2] from the left and right tails of the distribution and returns the corresponding values that can be rounded with a simple round(agesFbar(x)) to get a discrete age range that covers close to diff(probs) of the catch.

With plot = TRUE, the white bars are outside the Fbar age range and the dark gray bars are inside it. The bars affected by the lower and upper cut points are drawn in a shade between white and dark gray, providing a visual cue whether that age should be in the Fbar age range or not.

The calculated limits are somewhat unintuitive for interpretation, but they are statistically precise and unbiased. A lower limit of 6.8 means that 80% of age six was cut off the left tail, so rounding the lower age of Fbar to 7 appropriate. An upper limit of 14.1 means that all of age 14 and 10% of age 15 is inside the range, so rounding the upper age of Fbar to 14 is appropriate. See plot = TRUE example below.

Author(s)

Arni Magnusson.

Examples

agesFbar(gss)
agesFbar(gss, plot=TRUE)
agesFbar(gss, plot=TRUE, main="Greater silver smelt in 5b and 6a")

# 50% coverage instead of 80%
agesFbar(gss, c(0.25, 0.75))

# Include only the last 20 years
agesFbar(tail(gss, 20))

# Tests
cn1 <- setNames(c(100,400,400,100), 3:6)
cn2 <- setNames(c(99,401,401,99), 3:6)
cn3 <- setNames(c(101,399,399,101), 3:6)
cn4 <- setNames(c(500,400,50,50), 3:6)
cn5 <- setNames(c(50,50,400,500), 3:6)
agesFbar(cn1)
agesFbar(cn2)
agesFbar(cn3)
agesFbar(cn4)
agesFbar(cn5)

agesFbar(gss)
agesFbar(gss, plot=TRUE)
agesFbar(gss, plot=TRUE, main="Greater silver smelt in 5b and 6a")

# 50% coverage instead of 80%
agesFbar(gss, c(0.25, 0.75))

# Include only the last 20 years
agesFbar(tail(gss, 20))

# Tests
cn1 <- setNames(c(100,400,400,100), 3:6)
cn2 <- setNames(c(99,401,401,99), 3:6)
cn3 <- setNames(c(101,399,399,101), 3:6)
cn4 <- setNames(c(500,400,50,50), 3:6)
cn5 <- setNames(c(50,50,400,500), 3:6)
agesFbar(cn1)
agesFbar(cn2)
agesFbar(cn3)
agesFbar(cn4)
agesFbar(cn5)

Bpa from Blim

Description

Calculate the value of Bpa from Blim and sigmaB.

Usage

Bpa(Blim, sigmaB)
Bpa(Blim, sigmaB)

Arguments

`Blim`	the value of the Blim reference point.
`sigmaB`	the estimation uncertainty in B (standard error of logSSB in the terminal year).

Value

Value of Bpa.

Note

The purpose of PA reference points is to apply a precautionary approach in fisheries management.

By comparing the current B to Bpa, one can answer the question: are we at least 95% sure that B is above Blim, given the estimation uncertainty?

The ICES (2017) technical guidelines define Bpa as:

$B_\mathrm{pa} = B_\mathrm{lim} \exp(1.645\sigma_B)$

Author(s)

Arni Magnusson.

References

ICES (2017). ICES fisheries management reference points for category 1 and 2 stocks. ICES Advice Technical Guidelines 12.4.3.1. doi:10.17895/ices.pub.3036.

Examples

Bpa(100, 0.15)

Bpa(100, 0.15)

DLS Method 3.2

Description

Apply ICES method 3.2 to calculate catch advice for data-limited stocks (DLS).

Usage

DLS3.2(lastadvice, index, len = c(3, 2), buffer = FALSE, i1, i2)
DLS3.2(lastadvice, index, len = c(3, 2), buffer = FALSE, i1, i2)

Arguments

`lastadvice`	last catch advice given for this stock.
`index`	stock size index.
`len`	two integers, indicating the desired lengths of reference vectors.
`buffer`	whether to apply a -20% precautionary buffer.
`i1`	included for backward compatibility, use `len` instead.
`i2`	included for backward compatibility, use `len` instead.

Details

This function compares the average values of two reference vectors i1 and i2. In the simplest case, only lastadvice and index are required to calculate the advice.

The default value of len = c(3, 2) produces vectors i1 and i2 of lengths 3 and 2,

⁠ ⁠i1 = (I[n-4], I[n-3], I[n-2])

⁠ ⁠i2 = (I[n-1], I[n])

where I is a stock size index of length n.

Other vector lengths can be used, such as len = c(5, 2) to get

⁠ ⁠i1 = (I[n-6], I[n-5], I[n-4], I[n-3], I[n-2])

⁠ ⁠i2 = (I[n-1], I[n])

Finally, a -20% precautionary buffer can be applied at the end of all calculations.

See the ICES (2012) guidance report for details.

Value

A list containing the resulting advice and other elements showing intermediate steps in the calculations.

Author(s)

Anne Cooper and Arni Magnusson.

References

ICES (2012). ICES DLS guidance report: ICES implementation of advice for data-limited stocks in 2012 in its 2012 advice. ICES CM 2012/ACOM:68. doi:10.17895/ices.pub.5322.

Examples

# Three hypothetical surveys
survey <- data.frame(year=2001:2010, randu[1:10,])

DLS3.2(1000, survey$x)

DLS3.2(1000, survey$y)
DLS3.2(1000, survey$y, len=c(5,2))

DLS3.2(1000, survey$z)
DLS3.2(1000, survey$z, buffer=TRUE)

# Plot
output <- DLS3.2(1000, survey$y)
plot(y~year, survey, ylab="index", type="b", lty=3)
segments(2006, output$i1bar, 2008, lwd=2)
segments(2009, output$i2bar, 2010, lwd=2)

# Three hypothetical surveys
survey <- data.frame(year=2001:2010, randu[1:10,])

DLS3.2(1000, survey$x)

DLS3.2(1000, survey$y)
DLS3.2(1000, survey$y, len=c(5,2))

DLS3.2(1000, survey$z)
DLS3.2(1000, survey$z, buffer=TRUE)

# Plot
output <- DLS3.2(1000, survey$y)
plot(y~year, survey, ylab="index", type="b", lty=3)
segments(2006, output$i1bar, 2008, lwd=2)
segments(2009, output$i2bar, 2010, lwd=2)

Fpa from Flim

Description

Calculate the value of Fpa from Flim and sigmaF.

Usage

Fpa(Flim, sigmaF)
Fpa(Flim, sigmaF)

Arguments

`Flim`	the value of the Flim reference point.
`sigmaF`	the estimation uncertainty in F (standard error of logF in the terminal year).

Value

Value of Fpa.

Note

The purpose of PA reference points is to apply a precautionary approach in fisheries management.

By comparing the current F to Fpa, one can answer the question: are we at least 95% sure that F is below Flim, given the estimation uncertainty?

The ICES (2017) technical guidelines define Fpa as:

$F_\mathrm{pa} = F_\mathrm{lim} \exp(-1.645\sigma_F)$

The Fpa function can also be used to calculate reference points based on harvest rate: Hpa from Hlim and sigmaH.

Author(s)

Arni Magnusson.

References

ICES (2017). ICES fisheries management reference points for category 1 and 2 stocks. ICES Advice Technical Guidelines 12.4.3.1. doi:10.17895/ices.pub.3036.

Examples

Fpa(0.90, 0.15)

Fpa(0.90, 0.15)

Greater Silver Smelt

Description

Catch at age of greater silver smelt in areas 5b and 6a, in crosstab format.

Usage

gss
gss

Format

Data frame containing 18 columns:

`Year`	year
`5`	number of five-year-olds in the catch (thousands)
`6`	number of six-year-olds in the catch (thousands)
`...`
`21`	number of twenty-one-year-olds in the catch (thousands)

Details

The data were presented and analyzed at the 2020 ICES Benchmark Workshop on Greater Silver Smelt.

Source

https://stockassessment.org/datadisk/stockassessment/userdirs/user3/ARU.27.5b6a_WKGSS2020_FINAL/data/cn.dat

Examples

gss
agesFbar(gss)
gss
agesFbar(gss)

ICES Rounding Method

Description

Round values according to the ICES Advice Technical Guidelines.

Usage

icesRound(x, percent = FALSE, sign = percent, na = "")
icesRound(x, percent = FALSE, sign = percent, na = "")

Arguments

`x`	the values to round.
`percent`	whether to format values with a percent suffix.
`sign`	whether to format values with a sign prefix.
`na`	what to return when x is `NA`.

Value

Rounded values as a noquote string vector, retaining trailing zeros.

Note

This function implements the following ICES rounding method:

i)	Round to two significant figures when the first non-zero digit is 2 or larger.
ii)	Round to three significant figures when the first non-zero digit is 1.

As indicated in the ICES (2017) technical guidelines, this rounding method should not be applied to biomass, catch, or number of individuals. For those quantities, use the normal round function instead.

Author(s)

Colin Millar and Arni Magnusson.

References

ICES (2017). Rounding rules to be applied in ICES advice. ICES Advice Technical Guidelines 16.5.4. doi:10.17895/ices.pub.3038.

Examples

icesRound(0.123456)
icesRound(0.2468)

## Formatted string or numeric
icesRound(1.0)
as.numeric(icesRound(1.0))

## Percent, sign, NA
icesRound(33.33, percent = TRUE)
icesRound(33.33, sign = TRUE)
icesRound(c(1, NA, 3))
icesRound(c(1, NA, 3), na = NA)

## Example from the ICES Technical Guidelines
Actual <- c(0.35776, 0.34665, 0.202, 0.12665, 0.001567, 0.002567, 0.013415,
            0.02315, 1.168, 2.15678)
Rounded <- icesRound(Actual)
print(data.frame(Actual = as.character(Actual), Rounded), row.names = FALSE)

## Continued example from Guidelines, now rounding percentages
Actual <- c(9.546, 10.546, 23.445, -1.482, -9.09, 0.51, 130.11, 584)
Rounded <- icesRound(Actual, percent = TRUE)
print(data.frame(Actual = as.character(Actual), Rounded), row.names = FALSE)

icesRound(0.123456)
icesRound(0.2468)

## Formatted string or numeric
icesRound(1.0)
as.numeric(icesRound(1.0))

## Percent, sign, NA
icesRound(33.33, percent = TRUE)
icesRound(33.33, sign = TRUE)
icesRound(c(1, NA, 3))
icesRound(c(1, NA, 3), na = NA)

## Example from the ICES Technical Guidelines
Actual <- c(0.35776, 0.34665, 0.202, 0.12665, 0.001567, 0.002567, 0.013415,
            0.02315, 1.168, 2.15678)
Rounded <- icesRound(Actual)
print(data.frame(Actual = as.character(Actual), Rounded), row.names = FALSE)

## Continued example from Guidelines, now rounding percentages
Actual <- c(9.546, 10.546, 23.445, -1.482, -9.09, 0.51, 130.11, 584)
Rounded <- icesRound(Actual, percent = TRUE)
print(data.frame(Actual = as.character(Actual), Rounded), row.names = FALSE)

Mohn's Rho

Description

Calculate Mohn's rho, the average relative bias of retrospective estimates.

Usage

mohn(x, peels = 5, details = FALSE, plot = FALSE, ...)
mohn(x, peels = 5, details = FALSE, plot = FALSE, ...)

Arguments

`x`	a matrix or data frame containing retrospective estimates in columns, with years as row names.
`peels`	the number of retrospective peels to use in the calculation of rho, or `NULL` to use all retrospective columns in `x`.
`details`	whether to return the intermediate calculations of relative bias.
`plot`	whether to plot the retrospective trajectories.
`...`	passed to `matplot` and `points`.

Details

The default value peels = 5 is based on the ICES (2018) guidelines.

The basic plot = TRUE functionality is intended to quickly visualize the calculation of Mohn's rho. To produce a fully formatted plot, bypass the mohn function and plot the x data directly.

Value

Mohn's rho, along with intermediate calculations if details = TRUE.

Note

Relative bias is defined as

$b_i=\frac{\hat\theta^{R_i}_{T\!-i}\,-\,\hat\theta_{T\!-i}}{\hat\theta_{T\!-i}}$

and Mohn's rho is the average relative bias:

$\rho=\sum_{i=1}^n\frac{b_i}{n}$

See Mohn (1999), Brooks and Legault (2016), ICES (2018), and mohn(shake, details=TRUE) for details.

Author(s)

Arni Magnusson, with a contribution from Ruben Verkempynck.

References

Brooks, E.N. and Legault, C.M. (2016). Retrospective forecasting — evaluating performance of stock projections in New England groundfish stocks. Canadian Journal of Fisheries and Aquatic Sciences, 73, 935–950. doi:10.1139/cjfas-2015-0163.

ICES (2018). Guidelines for calculating Mohn's rho: Retrospective bias in assessment. Draft document version 7 (2018-04-03), available at the Expert Groups area on the ICES Sharepoint.

ICES (2020). Workshop on Catch Forecast from Biased Assessments (WKFORBIAS; outputs from 2019 meeting). ICES Scientific Reports 2(28). doi:10.17895/ices.pub.5997.

Mohn, R. (1999). The retrospective problem in sequential population analysis: An investigation using cod fishery and simulated data. ICES Journal of Marine Science, 56, 473–488. doi:10.1006/jmsc.1999.0481.

Examples

mohn(shake)
mohn(shake, details=TRUE)
mohn(shake, plot=TRUE)

mohn(shake, peels=3, plot=TRUE, col="black", ylim=0:1, yaxs="i")
lines(as.numeric(rownames(shake)), shake$base, lwd=3)

## Plot last 10 years
x <- rbind(matrix(1,28,6,dimnames=list(1981:2008,names(shake))), shake)
mohn(tail(x, 10), plot=TRUE, lwd=2, main="main")

mohn(shake)
mohn(shake, details=TRUE)
mohn(shake, plot=TRUE)

mohn(shake, peels=3, plot=TRUE, col="black", ylim=0:1, yaxs="i")
lines(as.numeric(rownames(shake)), shake$base, lwd=3)

## Plot last 10 years
x <- rbind(matrix(1,28,6,dimnames=list(1981:2008,names(shake))), shake)
mohn(tail(x, 10), plot=TRUE, lwd=2, main="main")

Read DLS3.2 Results from File

Description

Read results from the DLS3.2 advisory method from a file into a list.

Usage

read.dls(file)
read.dls(file)

Arguments

file

a filename.

Value

A list containing advice and other elements showing intermediate steps in the calculations.

Author(s)

Arni Magnusson.

Examples

## Not run: 
survey <- data.frame(year=2001:2010, randu[1:10,])
dls <- icesAdvice::DLS3.2(1000, survey$y)

write.dls(dls, "dls.txt")
read.dls("dls.txt")

file.remove("dls.txt")

## End(Not run)

## Not run: 
survey <- data.frame(year=2001:2010, randu[1:10,])
dls <- icesAdvice::DLS3.2(1000, survey$y)

write.dls(dls, "dls.txt")
read.dls("dls.txt")

file.remove("dls.txt")

## End(Not run)

Southern Hake Retro

Description

Retrospective estimates of Southern hake fishing mortality.

Usage

shake
shake

Format

Data frame containing 6 columns:

`base`	base model estimates
`-1`	1st retro peel
`-2`	2nd retro peel
`-3`	3rd retro peel
`-4`	4th retro peel
`-5`	5th retro peel

Details

This dataset is an example from the ICES (2018) Advice Technical Guidelines on quantifying and reporting retrospective bias.

Source

ICES (2018). Guidelines for calculating Mohn's rho: Retrospective bias in assessment. Draft document version 7 (2018-04-03), available at the Expert Groups area on the ICES Sharepoint.

Examples

shake
mohn(shake)
shake
mohn(shake)

Sigma from Confidence Interval

Description

Calculate the implicit sigma that was used to construct a confidence interval.

Usage

sigmaCI(lo, hi, log = TRUE, level = 0.95)
sigmaCI(lo, hi, log = TRUE, level = 0.95)

Arguments

`lo`	the lower confidence bound.
`hi`	the upper confidence bound.
`log`	whether the confidence interval is lognormal.
`level`	the confidence level.

Value

Implicit value of sigma.

Note

The purpose of PA reference points is to apply a precautionary approach in fisheries management.

This function is useful for reviewing PA reference points, when the report provides a CI but not the value of sigma.

Author(s)

Arni Magnusson.

Examples

sigmaCI(100, 200)

sigmaCI(100, 200)

Sigma from PA Reference Points

Description

Calculate the implicit sigma that was used to calculate PA reference points from limit reference points (Xpa from Xlim).

Usage

sigmaPA(lim, pa)
sigmaPA(lim, pa)

Arguments

`lim`	the value of the limit reference point, e.g., Blim or Flim.
`pa`	the value of the PA reference point, e.g., Bpa or Fpa.

Details

The order of the parameters does not matter, so sigmaPA(Fpa, Flim) and sigmaPA(Flim, Fpa) are equivalent.

Value

Implicit value of sigma.

Note

The purpose of PA reference points is to apply a precautionary approach in fisheries management.

This function is useful for reviewing PA reference points, when the advice sheet provides the value of Xlim and Xpa but not the value of sigma.

The inference is based on the following relationships:

$B_\mathrm{pa} = B_\mathrm{lim} \exp(1.645\sigma_B)$

$F_\mathrm{pa} = F_\mathrm{lim} \exp(-1.645\sigma_F)$

Author(s)

Arni Magnusson.

Examples

sigmaPA(100, 120)

sigmaPA(100, 120)

Write DLS3.2 Results to File

Description

Write results from the DLS3.2 advisory method to a file.

Usage

write.dls(x, file = "")
write.dls(x, file = "")

Arguments

`x`	a list generated by the `DLS3.2` function.
`file`	a filename.

Note

The resulting text file has Dos line endings (CRLF).

Author(s)

Arni Magnusson.

Examples

## Not run: 
survey <- data.frame(year=2001:2010, randu[1:10,])
dls <- icesAdvice::DLS3.2(1000, survey$y)

write.dls(dls, "dls.txt")
read.dls("dls.txt")

file.remove("dls.txt")

## End(Not run)

## Not run: 
survey <- data.frame(year=2001:2010, randu[1:10,])
dls <- icesAdvice::DLS3.2(1000, survey$y)

write.dls(dls, "dls.txt")
read.dls("dls.txt")

file.remove("dls.txt")

## End(Not run)

Package 'icesAdvice'

Help Index

Functions Related to ICES Advice

Description

Details

Author(s)

References

Age Range for Fbar

Description

Usage

Arguments

Value

Note

Author(s)

See Also

Examples

Bpa from Blim

Description

Usage

Arguments

Value

Note

Author(s)

References

See Also

Examples

DLS Method 3.2

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Fpa from Flim

Description

Usage

Arguments

Value

Note

Author(s)

References

See Also

Examples

Greater Silver Smelt

Description

Usage

Format

Details

Source

See Also

Examples

ICES Rounding Method

Description

Usage

Arguments

Value

Note

Author(s)

References

See Also

Examples

Mohn's Rho

Description

Usage

Arguments

Details

Value

Note

Author(s)

References

See Also

Examples

Read DLS3.2 Results from File

Description

Usage

Arguments

Value