Package 'msy' reference manual

Title:	Estimation of Equilibrium Reference Points for Fsisheries
Description:	Methods to estimate equilibrium reference points for fisheries data. Currently data must be converted into FLStock objects of the FLR (Fisheries Library in R) style, defined in the R package FLCore.
Authors:	John Simmonds [aut], Einar Hjorleifsson [aut], Carmen Fernandez [ctb], Colin Millar [aut, cre]
Maintainer:	Colin Millar <[email protected]>
License:	GPL (>= 2)
Version:	0.1.19
Built:	2024-12-22 03:02:30 UTC
Source:	https://github.com/ices-tools-prod/msy

Estimation of equilibrium reference points for fisheries

Description

Methods to estimate equilibrium reference points for fisheries data. Currently data must be converted into FLStock objects of the FLR (Fisheries Library in R) style, defined in the R package FLCore

Details

Model fitting and simulation:

`eqsr_fit`	fitting stock recruit models to data
`eqsim_run`	simulation am 'equilibrium' population state

Plotting:

`eqsr_plot`	plot stock recuitment fit
`eqsim_plot`	plot summary of simulation showing reference points
`eqsim_plot_range`	plot summary of MSY ranges reference points

Example data:

`icesStocks`	A list of various stocks

Author(s)

John Simmonds, Einar Hjorleifsson, Carmen Fernandez and Colin Millar.

References

ICES (2015) Report of the Workshop to consider F MSY ranges for stocks in ICES categories 1 and 2 in Western Waters (WKMSYREF4). 01 WKMSYREF4 Report.pdf

ICES (2017) ICES fisheries management reference points for category 1 and 2 stocks. DOI: 10.17895/ices.pub.3036

Buckland, S.T., K.P. Burnham & N.H. Augustin (1997). Model selection: An integral part of inference. Biometrics 53, 603-618. DOI: 10.2307/2533961

To explore the code of the package see the GitHub repo: ices-tools-prod/msy

Plots of the results from eqsim

Description

XXX

Usage

eqsim_ggplot(sim, Scale = 1, plotit = TRUE)
eqsim_ggplot(sim, Scale = 1, plotit = TRUE)

Arguments

`sim`	An object returned from the function eqsim_run
`Scale`	A value, the scaling on the yaxis
`plotit`	Boolean, if TRUE (default) returns a plot

Author(s)

Einar Hjorleifsson [email protected]

Plots of the results from eqsim

Description

XXX

Usage

eqsim_plot(sim, ymax.multiplier = 1.2, catch = TRUE)
eqsim_plot(sim, ymax.multiplier = 1.2, catch = TRUE)

Arguments

`sim`	An object returned from the function eqsim_run
`ymax.multiplier`	A value that acts as a multiplier of the maximum observed variable being plotted. E.g. 1.2 means that for each of the three panels a, b and c the ymax is set to 1.2 of the maximum observed recruitment, spawning stock biomass and yield (catch or landings, depending on user input.
`catch`	Boolean, if TRUE (default) returns a plot based on catch. If false returns a plot based on landings.

Author(s)

Einar Hjorleifsson [email protected]

Calculate Fmsy range

Description

XXX

Usage

eqsim_plot_range(sim, interval = 0.95, type = "median")
eqsim_plot_range(sim, interval = 0.95, type = "median")

Arguments

`sim`	XXX
`interval`	XXX
`type`	XXX

Simulates the Equilibrium Results for a Population.

Description

Simulate a fish stock forward in time given biological parameters, fishery parameters and advice parameters.

Usage

eqsim_run(
  fit,
  bio.years = c(-5, -1) + FLCore::dims(fit$stk)$maxyear,
  bio.const = FALSE,
  sel.years = c(-5, -1) + FLCore::dims(fit$stk)$maxyear,
  sel.const = FALSE,
  Fscan = seq(0, 2, len = 40),
  Fcv = 0,
  Fphi = 0,
  SSBcv = 0,
  rhologRec = TRUE,
  Blim,
  Bpa,
  recruitment.trim = c(3, -3),
  Btrigger = 0,
  Nrun = 200,
  process.error = TRUE,
  verbose = TRUE,
  extreme.trim = c(0, 1),
  R.initial = mean(fit$rby$rec),
  keep.sims = FALSE
)
eqsim_run(
  fit,
  bio.years = c(-5, -1) + FLCore::dims(fit$stk)$maxyear,
  bio.const = FALSE,
  sel.years = c(-5, -1) + FLCore::dims(fit$stk)$maxyear,
  sel.const = FALSE,
  Fscan = seq(0, 2, len = 40),
  Fcv = 0,
  Fphi = 0,
  SSBcv = 0,
  rhologRec = TRUE,
  Blim,
  Bpa,
  recruitment.trim = c(3, -3),
  Btrigger = 0,
  Nrun = 200,
  process.error = TRUE,
  verbose = TRUE,
  extreme.trim = c(0, 1),
  R.initial = mean(fit$rby$rec),
  keep.sims = FALSE
)

Arguments

`fit`	A list returned from the function fitModels
`bio.years`	The years to sample maturity, weights and M from, given as a vector of length 2, i.e. c(2010, 2015) select from the years 2010 to 2015 inclusive.
`bio.const`	A flag (default FALSE), if TRUE mean of the biological values from the years selected are used
`sel.years`	The years to sample the selection patterns from, given as a vector of length 2, i.e. c(2010, 2015) select from the years 2010 to 2015 inclusive.
`sel.const`	A flag (default FALSE), if TRUE mean of the selection patterns from the years selected are used
`Fscan`	F values to scan over, i.e. seq(0, 2, by = 0.05)
`Fcv`	Assessment error in the advisory year
`Fphi`	Autocorrelation in assessment error in the advisory year
`SSBcv`	Spawning stock biomass error in the advisory year
`rhologRec`	A flag for recruitment autocorrelation, default (TRUE), or a vector of numeric values specifcying the autocorrelation parameter for the residuals for each SR model.
`Blim`	SSB limit reference point
`Bpa`	SSB precuationary reference point
`recruitment.trim`	A numeric vector with two log-value clipping the extreme recruitment values from a continuous lognormal distribution. The values must be set as c("high","low").
`Btrigger`	If other than 0 (default) the target F applied is reduced by SSB/Btrigger. This is the "ICES Advice Rule".
`Nrun`	The number of years to run in total (the last 50 years from that will be retained to compute equilibrium values from)
`process.error`	Use stochastic recruitment or mean recruitment? TRUE (default) uses the predictive distribution of recruitment, model estimate of recruitment + simulated observation error. FALSE uses model prediction of recruitment with no observation error.
`verbose`	Flag, if TRUE (default) indication of the progress of the simulation is provided in the console. Useful to turn to FALSE when knitting documents.
`extreme.trim`	a pair of quantiles (low, high) which are used to trim the equilibrium catch values, across simulations within an F scenario, when calculating the mean catch and landings for that F scenario. These mean values calculated accross simulations within an F scenario are used to find which F scenario gave the maximum catch. `extreme.trim` can therefore be used to stablise the estimate of mean equilibrium catch and landings by F scenario. The default is c(0, 1) which includes all the data and is effectively an untrimmed mean.
`R.initial`	Initial recruitment for the simulations. This is common accross all simulations. Default = mean of all recruitments in the series.
`keep.sims`	Flag, if TRUE returns a matrix of population tragectories for each value of F in Fscan (see examples).

Details

Details of the steps required to evaluate reference points are given in ICES (2017). WHile, details of the calculation of MSY ranges is given in ICES (2015).

Value

A list containing the results from the forward simulation and the reference points calculated from it.

References

ICES (2015) Report of the Workshop to consider F MSY ranges for stocks in ICES categories 1 and 2 in Western Waters (WKMSYREF4). 01 WKMSYREF4 Report.pdf

ICES (2017) ICES fisheries management reference points for category 1 and 2 stocks. DOI: 10.17895/ices.pub.3036

Examples

## Not run: 
data(icesStocks)
FIT <- eqsr_fit(icesStocks$saiNS,
                nsamp = 1000,
                models = c("Ricker", "Segreg"))
SIM <-
  eqsim_run(
    FIT,
    bio.years = c(2004, 2013),
    sel.years = c(2004, 2013),
    Fcv = 0.24,
    Fphi = 0.42,
    Blim = 106000,
    Bpa = 200000,
    Fscan = seq(0, 1.2, len = 40)
   )

# extract tragectories
ssbsim <- SIM$rbya$ssb
years <- SIM$rbya$simyears
models <- SIM$rbya$srmodels$model
Ftarget <- SIM$rbya$Ftarget

Fval <- which(Ftarget == 0)
Fval <- which(Ftarget > .3)[1]
x <- ssbsim[Fval,,]
df <- data.frame(year = 1:nrow(x),
                 ssb = c(x),
                 sim = rep(1:ncol(x), each = nrow(x)),
                 model = rep(models, each = nrow(x)))
xyplot(ssb ~ year | model, groups = sim, data = df, type = "l", col = grey(0.5, alpha = 0.5))

fit <- density(x[x>1e-3], from = 0)
plot(fit$x,fit$y*mean(x>1e-3),col="red", type = "l")
lines(x = 0, y = mean(x<=1e-3), type = "h", lwd = 3)


## End(Not run)

## Not run: 
data(icesStocks)
FIT <- eqsr_fit(icesStocks$saiNS,
                nsamp = 1000,
                models = c("Ricker", "Segreg"))
SIM <-
  eqsim_run(
    FIT,
    bio.years = c(2004, 2013),
    sel.years = c(2004, 2013),
    Fcv = 0.24,
    Fphi = 0.42,
    Blim = 106000,
    Bpa = 200000,
    Fscan = seq(0, 1.2, len = 40)
   )

# extract tragectories
ssbsim <- SIM$rbya$ssb
years <- SIM$rbya$simyears
models <- SIM$rbya$srmodels$model
Ftarget <- SIM$rbya$Ftarget

Fval <- which(Ftarget == 0)
Fval <- which(Ftarget > .3)[1]
x <- ssbsim[Fval,,]
df <- data.frame(year = 1:nrow(x),
                 ssb = c(x),
                 sim = rep(1:ncol(x), each = nrow(x)),
                 model = rep(models, each = nrow(x)))
xyplot(ssb ~ year | model, groups = sim, data = df, type = "l", col = grey(0.5, alpha = 0.5))

fit <- density(x[x>1e-3], from = 0)
plot(fit$x,fit$y*mean(x>1e-3),col="red", type = "l")
lines(x = 0, y = mean(x<=1e-3), type = "h", lwd = 3)


## End(Not run)

Fits one or more stock recruitment relationship to data containted in an FLStock object. If more than one stock recruit relationship is provided, the models are weighted based on smooth AIC weighting (See Buckland et al., 1997).

Usage

eqsr_fit(
  stk,
  nsamp = 1000,
  models = c("Ricker", "Segreg", "Bevholt"),
  id.sr = FLCore::name(stk),
  remove.years = NULL,
  rshift = 0
)
eqsr_fit(
  stk,
  nsamp = 1000,
  models = c("Ricker", "Segreg", "Bevholt"),
  id.sr = FLCore::name(stk),
  remove.years = NULL,
  rshift = 0
)

Arguments

`stk`	FLStock object
`nsamp`	Number of samples (iterations) to take from the stock recruitment fit (default is 1000). If 0 (zero) then only the fits to the data are returned and no simulations are made.
`models`	A character vector containing stock recruitment models to use in the model averaging. User can set any combination of "Ricker", "Segreg", "Bevholt", "Smooth_hockey".
`id.sr`	A character vector specifying an id or name for the stock recruitment fit being run. The default is to use the slot "name" in the stk parameter is provided
`remove.years`	A vector specifying the years to remove from the model fitting.
`rshift`	lag ssb by aditional years (default = 0). As an example, for some herring stocks, age 1 (1 winter ring) fish were spawned 2 years previously, in this case, rshift = 1.

Value

A list containing the following objects:

'sr.sto' data.frame containing the alpha (a), beta (b), cv and model names. The number of rows correspond to the value set of 'nsamp' in the function call.
'sr.det' The parameters in the stock recruitment model corresponding to the "best fit" of any given model.
'stk' An FLStock object, same as provided as input by the user.
'rby' A data.frame containing the recruitment (rec), spawning stock biomass (ssb) and year used in the fitting of the data.
'id.sr' A string containing run name (taken from the 'id.sr' argument)

References

Buckland, S.T., K.P. Burnham & N.H. Augustin (1997). Model selection: An integral part of inference. Biometrics 53, 603-618. DOI: 10.2307/2533961

Examples

data(icesStocks)
FIT <- eqsr_fit(icesStocks$saiNS,
                nsamp = 0,
                models = c("Ricker", "Segreg"))

# summary of individual fits
FIT$sr.det
eqsr_plot(FIT)

# fit a bounded segmented regression
Segreg_bounded  <- function(ab, ssb) {
  ab$b <- min_ssb + ab$b
  Segreg(ab, ssb)
}
min_ssb <- min(FLCore::ssb(icesStocks$saiNS))

FIT <- eqsr_fit(icesStocks$saiNS,
                nsamp = 0,
                models = c("Segreg", "Segreg_bounded"))

# summary of individual fits
FIT$sr.det
FIT$sr.det$b[2] + min_ssb
eqsr_plot(FIT)

## Not run: 
FIT <- eqsr_fit(icesStocks$saiNS,
                nsamp = 2000,
                models = c("Segreg", "Segreg_bounded"))

# summary of individual fits
FIT$sr.det
eqsr_plot(FIT)

## End(Not run)

data(icesStocks)
FIT <- eqsr_fit(icesStocks$saiNS,
                nsamp = 0,
                models = c("Ricker", "Segreg"))

# summary of individual fits
FIT$sr.det
eqsr_plot(FIT)

# fit a bounded segmented regression
Segreg_bounded  <- function(ab, ssb) {
  ab$b <- min_ssb + ab$b
  Segreg(ab, ssb)
}
min_ssb <- min(FLCore::ssb(icesStocks$saiNS))

FIT <- eqsr_fit(icesStocks$saiNS,
                nsamp = 0,
                models = c("Segreg", "Segreg_bounded"))

# summary of individual fits
FIT$sr.det
FIT$sr.det$b[2] + min_ssb
eqsr_plot(FIT)

## Not run: 
FIT <- eqsr_fit(icesStocks$saiNS,
                nsamp = 2000,
                models = c("Segreg", "Segreg_bounded"))

# summary of individual fits
FIT$sr.det
eqsr_plot(FIT)

## End(Not run)

Plot Simulated Predictive Distribution of Recruitment

Description

Plot Simulated Predictive Distribution of Recruitment

Usage

eqsr_plot(
  fit,
  n = 20000,
  x.mult = 1.1,
  y.mult = 1.4,
  ggPlot = FALSE,
  Scale = 1
)
eqsr_plot(
  fit,
  n = 20000,
  x.mult = 1.1,
  y.mult = 1.4,
  ggPlot = FALSE,
  Scale = 1
)

Arguments

`fit`	an fitted stock recruit model returned from `eqsr_fit`
`n`	Number of random recruitment draws to plot
`x.mult`	max value for the y axis (ssb) as a multiplier of maximum observed ssb
`y.mult`	max value for the x axis (rec) as a multiplier of maismum observed rec
`ggPlot`	Flag, if FALSE (default) plot using base graphics, if TRUE do a ggplot
`Scale`	Numeric value for scaling varibles in plot.

Value

NULL produces a plot

Examples


## Not run: 
data(icesStocks)
FIT <- eqsr_fit(icesStocks$saiNS,
                nsamp = 1000,
                models = c("Ricker", "Segreg"))

eqsr_plot(FIT, n = 20000)

# Scale argument only available for ggPlot = TRUE
eqsr_plot(FIT, n = 20000, ggPlot = TRUE, Scale = 1000)

## End(Not run)

## Not run: 
data(icesStocks)
FIT <- eqsr_fit(icesStocks$saiNS,
                nsamp = 1000,
                models = c("Ricker", "Segreg"))

eqsr_plot(FIT, n = 20000)

# Scale argument only available for ggPlot = TRUE
eqsr_plot(FIT, n = 20000, ggPlot = TRUE, Scale = 1000)

## End(Not run)

icesStocks

Description

A list FLStock object for various stocks

Usage

icesStocks
icesStocks

Format

a list

Author(s)

Source

Get starting values for models

Description

Starting values for hockey stick models

Usage

initial(model, data)
initial(model, data)

Arguments

`model`	XXX
`data`	XXX

Value

vector of starting values

the log-likelihood of the rectuit function

Description

the log-likelihood of the rectuit function

Usage

llik(param, data, model, logpar = FALSE)
llik(param, data, model, logpar = FALSE)

Arguments

`param`	the model parameters
`data`	the rec and ssb data
`model`	the stock recruit model to use
`logpar`	are the parameters on the log scale

Value

the log-likelihood

Progress function

Description

Non exported function, plots the prgress of an iterative procedure using "[=> ]", "[==> ]", etc.

Usage

loader(p)
loader(p)

Arguments

p

Value

stock recruitment function

Description

stock recruitment function

Usage

Ricker(ab, ssb)
Ricker(ab, ssb)

Arguments

`ab`	the model parameters
`ssb`	a vector of ssb

Value

log recruitment according to model

stock recruitment function

Description

stock recruitment function

Usage

Segreg(ab, ssb)
Segreg(ab, ssb)

Arguments

`ab`	the model parameters
`ssb`	a vector of ssb

Value

log recruitment according to model

stock recruitment function

Description

stock recruitment function

Usage

segreg2(ab, ssb)
segreg2(ab, ssb)

Arguments

`ab`	the model parameters
`ssb`	a vector of ssb

Value

log recruitment according to model

stock recruitment function

Description

stock recruitment function

Usage

Smooth_hockey(ab, ssb, gamma = 0.1)
Smooth_hockey(ab, ssb, gamma = 0.1)

Arguments

`ab`	the model parameters
`ssb`	a vector of ssb
`gamma`	a smoother parameter

Value

log recruitment according to model

Package 'msy'

Help Index

Estimation of equilibrium reference points for fisheries

Description

Details

Author(s)

References

stock recruitment function

Description

Usage

Arguments

Value

stock recruitment function

Description

Usage

Arguments

Value

Plots of the results from eqsim

Description

Usage

Arguments

Author(s)

Plots of the results from eqsim

Description

Usage

Arguments

Author(s)

Calculate Fmsy range

Description

Usage

Arguments

Simulates the Equilibrium Results for a Population.

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Stock recruitment fitting

Description

Usage

Arguments

Value

References

See Also

Examples

Plot Simulated Predictive Distribution of Recruitment

Description

Usage

Arguments

Value

See Also

Examples

icesStocks

Description

Usage

Format

Author(s)

Source

Get starting values for models

Description

Usage

Arguments

Value

the log-likelihood of the rectuit function

Description

Usage

Arguments

Value

Progress function

Description

Usage

Arguments

stock recruitment function

Description

Usage

Arguments

Value