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.

Details

Calculate ICES advice:

Calculate PA reference points and sigma:

Other calculations:

Read and write files:

Example tables:

Author(s)

Arni Magnusson, Colin Millar, and Anne Cooper.

References

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

Bpa from Blim

Description

Calculate the value of Bpa from Blim and sigmaB.

Usage

Bpa(Blim, sigmaB)

Arguments

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. doi: 10.17895/ices.pub.3036ICES Advice Technical Guidelines 12.4.3.1.

See Also

Fpa calculates that reference point from Flim and sigmaF.

sigmaPA calculates the implicit sigma from PA reference points.

icesAdvice-package gives an overview of the package.

Examples

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)

Arguments

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.

See Also

read.dls and write.dls read and write DLS3.2 results to file.

icesAdvice-package gives an overview of the package.

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)

Fpa from Flim

Description

Calculate the value of Fpa from Flim and sigmaF.

Usage

Fpa(Flim, sigmaF)

Arguments

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. doi: 10.17895/ices.pub.3036ICES Advice Technical Guidelines 12.4.3.1.

See Also

Bpa calculates that reference point from Blim and sigmaB.

sigmaPA calculates the implicit sigma from PA reference points.

icesAdvice-package gives an overview of the package.

Examples

Fpa(0.90, 0.15)

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)

Arguments

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.

See Also

gss is an example catch-at-age table.

quantile is the base function to calculate quantiles.

icesAdvice-package gives an overview of the package.

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)

Greater Silver Smelt

Description

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

Usage

gss

Format

Data frame containing 18 columns:

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

See Also

agesFbar calculates a suitable age range for Fbar.

icesAdvice-package gives an overview of the package.

Examples

gss
agesFbar(gss)

ICES Rounding Method

Description

Round values according to the ICES Advice Technical Guidelines.

Usage

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

Arguments

Value

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

Note

This function implements the following ICES rounding method:

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. doi: 10.17895/ices.pub.3038ICES Advice Technical Guidelines 16.5.4.

See Also

signif rounds values to a specified number of significant digits.

icesAdvice-package gives an overview of the package.

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)

Mohn's Rho

Description

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

Usage

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

Arguments

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.

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). doi: 10.17895/ices.pub.5997ICES Scientific Reports 2(28).

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.

See Also

shake is a retrospective example table.

icesAdvice-package gives an overview of the package.

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

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)

Arguments

Value

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

Author(s)

Arni Magnusson.

See Also

write.dls writes DLS3.2 results to a file.

DLS3.2 can be used to calculate catch advice for data-limited stocks (DLS).

icesAdvice-package gives an overview of the package.

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)

Southern Hake Retro

Description

Retrospective estimates of Southern hake fishing mortality.

Usage

shake

Format

Data frame containing 6 columns:

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.

See Also

mohn calculates Mohn's rho.

icesAdvice-package gives an overview of the package.

Examples

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)

Arguments

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.

See Also

sigmaPA calculates the implicit sigma from PA reference points.

icesAdvice-package gives an overview of the package.

Examples

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)

Arguments

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.

See Also

sigmaCI calculates the implicit sigma from a confidence interval.

Bpa and Fpa calculate those reference points from the limit reference points, based on a given sigma.

icesAdvice-package gives an overview of the package.

Examples

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 = "")

Arguments

Note

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

Author(s)

Arni Magnusson.

See Also

read.dls reads DLS3.2 results from a file back into R.

DLS3.2 can be used to calculate catch advice for data-limited stocks (DLS).

icesAdvice-package gives an overview of the package.

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)