Title: Length-Based Spawning Potential Ratio
Version: 0.1.6
Description: Simulate expected equilibrium length composition, yield-per-recruit, and the spawning potential ratio (SPR) using the length-based SPR (LBSPR) model. Fit the LBSPR model to length data to estimate selectivity, relative apical fishing mortality, and the spawning potential ratio for data-limited fisheries. See Hordyk et al (2016) <doi:10.1139/cjfas-2015-0422> for more information about the LBSPR assessment method.
URL: https://github.com/AdrianHordyk/LBSPR
BugReports: https://github.com/AdrianHordyk/LBSPR/issues
Depends: R (≥ 3.2.4)
License: GPL-3
Imports: dplyr, ggplot2, graphics, gridExtra, methods, plotrix, Rcpp, RColorBrewer, shiny, tidyr
RoxygenNote: 7.1.1
Encoding: UTF-8
LinkingTo: Rcpp
Suggests: colorspace, knitr, scales, shinyBS, rmarkdown
VignetteBuilder: knitr
NeedsCompilation: yes
Packaged: 2021-10-06 16:24:52 UTC; User
Author: Adrian Hordyk [aut, cre]
Maintainer: Adrian Hordyk <ar.hordyk@gmail.com>
Repository: CRAN
Date/Publication: 2021-10-06 16:40:02 UTC

Report the location of the Data Files

Description

A function that returns the location of the example CSV files

Usage

DataDir()

Author(s)

A. Hordyk modified (i.e., stolen) from T. Carruthers' code (DLMtool package)

Kalman filter and Rauch-Tung-Striebel smoother

Description

A function that applies a filter and smoother to estimates

Usage

FilterSmooth(RawEsts, R = 1, Q = 0.1, Int = 100)

Arguments

RawEsts

a vector of estimated values

R

variance of sampling noise

Q

variance of random walk increments

Int

covariance of initial uncertainty

Value

a vector of smoothed values

LBSPR Optimization function for age-based selectivity model

Description

Internal optimization function

Usage

LBSPR_NLLabsel(
  starts,
  x,
  P,
  LMids,
  LBins,
  LDat,
  MK,
  Linf,
  FecB,
  L50,
  L95,
  maxsd,
  CVLinf,
  Nage,
  usePen
)

Arguments

starts

a vector of starting parameters, relative SL50 (SL50/Linf), deltaSL (SL95-SL50)/Linf, and F/M (in log space)

x

vector of relative ages

P

numeric value indicating proportion of cohort remaining at maximum age

LMids

a vector of the midpoints of the length classes

LBins

a vector of length classes

LDat

a vector of lenght frequencies. Must be same length as LMids

MK

the M/K value

Linf

the Linf value for the population as a hole

FecB

exponent of the length-fecundity relationship

L50

length at 50 per cent maturity

L95

length at 95 per cent maturity

maxsd

numeric value - maximum number of standard deviations of length-at-age dist

CVLinf

CV of length-at-age

Nage

number of pseudo age-classes

usePen

logical to use penalty for extreme estimates of selectivity

Value

negative log-likelihood value

Author(s)

A. Hordyk

LBSPR Optimization function for GTG model

Description

Internal optimization function

Usage

LBSPR_NLLgtg(
  starts,
  LMids,
  LBins,
  LDat,
  gtgLinfs,
  MKMat,
  MK,
  Linf,
  ngtg,
  recP,
  usePen
)

Arguments

starts

a vector of starting parameters, relative SL50 (SL50/Linf), deltaSL (SL95-SL50)/Linf, and F/M (in log space)

LMids

a vector of the midpoints of the length classes

LBins

a vector of length classes

LDat

a vector of lenght frequencies. Must be same length as LMids

gtgLinfs

a vector of Linfs for the growth-type-groups

MKMat

a matrix of M/K for each GTG and length-class

MK

the M/K value

Linf

the Linf value for the population as a hole

ngtg

the number of growth-type-groups

recP

a vector of recruitment by GTG

usePen

logical to use penalty for extreme estimates of selectivity

Value

negative log-likelihood value

Author(s)

A. Hordyk

Fit LBSPR model to length data

Description

A function that fits the LBSPR model to length data

Usage

LBSPRfit(
  LB_pars = NULL,
  LB_lengths = NULL,
  yrs = NA,
  Control = list(),
  pen = TRUE,
  verbose = TRUE,
  useCPP = TRUE,
  ...
)

Arguments

LB_pars

an object of class 'LB_pars' that contains the life history information

LB_lengths

an object of class 'LB_lengths' that contains the length data

yrs

index of years to include. If NA the model is run on all years

Control

a list of control options for the LBSPR model.

pen

apply a penalty if estimate of selectivity is very high?

verbose

display messages?

useCPP

use cpp optimization code?

...

additional parameters to pass to FilterSmooth

Details

The Control options are:

modtype

Model Type: either Growth-Type-Group Model (default: "GTG") or Age-Structured ("absel")

maxsd

Maximum number of standard deviations for length-at-age distribution (default is 2)

ngtg

Number of groups for the GTG model. Default is 13

P

Proportion of survival of initial cohort for maximum age for Age-Structured model. Default is 0.01

Nage

Number of pseudo-age classes in the Age Structured model. Default is 101

maxFM

Maximum value for F/M. Estimated values higher than this are trunctated to maxFM. Default is 4

Value

a object of class 'LB_obj'

Author(s)

A. Hordyk

Examples

## Not run: 
MyFit <- LBSPRfit(LBparameters, LBlengths)
MyFit@Ests

## End(Not run)

Internal function to fit LBSPR model to length data

Description

An internal function that fits the LBSPR model to a single year of length data

Usage

LBSPRfit_(
  yr = 1,
  LB_pars = NULL,
  LB_lengths = NULL,
  Control = list(),
  pen = TRUE,
  useCPP = TRUE,
  verbose = TRUE
)

Arguments

yr

index of the year column to fit model to

LB_pars

an object of class 'LB_pars' that contains the life history information

LB_lengths

an object of class 'LB_lengths' that contains the length data

Control

a list of control options for the LBSPR model.

pen

apply a penalty if estimate of selectivity is very high?

useCPP

use cpp optimization code?

verbose

display messages?

Details

The Control options are:

modtype

Model Type: either Growth-Type-Group Model (default: "GTG") or Age-Structured ("absel")

maxsd

Maximum number of standard deviations for length-at-age distribution (default is 2)

ngtg

Number of groups for the GTG model. Default is 13

P

Proportion of survival of initial cohort for maximum age for Age-Structured model. Default is 0.01

Nage

Number of pseudo-age classes in the Age Structured model. Default is 101

maxFM

Maximum value for F/M. Estimated values higher than this are trunctated to maxFM. Default is 4

Value

a object of class 'LB_obj'

Author(s)

A. Hordyk

Optimisation Routine for fitting LBSPR

Description

A function that calculate the negative log-likelihood of the LBSPR model

Usage

LBSPRopt(
  trypars,
  yr = 1,
  LB_pars = NULL,
  LB_lengths = NULL,
  Control = list(),
  pen = TRUE
)

Arguments

trypars

a vector of exploitation parameters in log space

yr

index of the year column to fit the model to

LB_pars

an object of class 'LB_pars' that contains the life history information

LB_lengths

an object of class 'LB_lengths' that contains the length data

Control

a list of control options for the LBSPR model.

pen

apply a penalty if estimate of selectivity is very high?

Details

The Control options are:

modtype

Model Type: either Growth-Type-Group Model (default: "GTG") or Age-Structured ("absel")

maxsd

Maximum number of standard deviations for length-at-age distribution (default is 2)

ngtg

Number of groups for the GTG model. Default is 13

P

Proportion of survival of initial cohort for maximum age for Age-Structured model. Default is 0.01

Nage

Number of pseudo-age classes in the Age Structured model. Default is 101

maxFM

Maximum value for F/M. Estimated values higher than this are trunctated to maxFM. Default is 4

Value

a NLL value

Author(s)

A. Hordyk

LBSPR Simulation Model

Description

Function that generates the expected equilbrium size composition given biological parameters, and fishing mortality and selectivity pattern.

Usage

LBSPRsim(LB_pars = NULL, Control = list(), verbose = TRUE)

Arguments

LB_pars

an object of class 'LB_pars' that contains the life history information

Control

a list of control options for the LBSPR model.

verbose

display messages?

Details

The Control options are:

modtype

Model Type: either Growth-Type-Group Model (default: "GTG") or Age-Structured ("absel")

maxsd

Maximum number of standard deviations for length-at-age distribution (default is 2)

ngtg

Number of groups for the GTG model. Default is 13

P

Proportion of survival of initial cohort for maximum age for Age-Structured model. Default is 0.01

Nage

Number of pseudo-age classes in the Age Structured model. Default is 101

maxFM

Maximum value for F/M. Estimated values higher than this are trunctated to maxFM. Default is 4

Value

a object of class 'LB_obj'

Author(s)

A. Hordyk

Examples

 LB_pars <- new("LB_pars")
 LB_pars@MK <- 1.5
 LB_pars@Linf <- 100
 LB_pars@L50 <- 50
 LB_pars@L95 <- 55
 LB_pars@SL50 <- 60
 LB_pars@SL95 <- 65
 LB_pars@FM <- 1
 Sim <- LBSPRsim(LB_pars)
 Sim@SPR

Internal LBSPR Simulation Model

Description

A internal function that generates the expected equilbrium size composition given biological parameters, and fishing mortality and selectivity pattern. Typically only used by other functions in the package.

Usage

LBSPRsim_(LB_pars = NULL, Control = list(), verbose = TRUE, doCheck = TRUE)

Arguments

LB_pars

an object of class 'LB_pars' that contains the life history information

Control

a list of control options for the LBSPR model.

verbose

display messages?

doCheck

check if the LB_pars object is valid? Switch off when calling function from a optimization routine.

Details

The Control options are:

modtype

Model Type: either Growth-Type-Group Model (default: "GTG") or Age-Structured ("absel")

maxsd

Maximum number of standard deviations for length-at-age distribution (default is 2)

ngtg

Number of groups for the GTG model. Default is 13

P

Proportion of survival of initial cohort for maximum age for Age-Structured model. Default is 0.01

Nage

Number of pseudo-age classes in the Age Structured model. Default is 101

maxFM

Maximum value for F/M. Estimated values higher than this are trunctated to maxFM. Default is 4

Value

a object of class 'LB_obj'

Author(s)

A. Hordyk

An S4 class containing length data

Description

An S4 class containing length data

Slots

LMids

A numeric vector containing the mid-points of the length bins

LData

A numeric matrix containing length data

L_units

Character descrbing units of the length measurements

Years

A numeric vector containing the year indices

NYears

A length-one numeric vector for number of years

Elog

A error log

An S4 class containing all parameters for the LBSPR model

Description

An S4 class containing all parameters for the LBSPR model

Slots

SPR

The Spawning Potential Ratio

Yield

Relative yield

YPR

Yield per recruit

SSB

Spawning stock biomass (relative only)

SSB0

Unfished spawning stock biomass

B0

Unfished biomass

LMids

A numeric vector containing the mid-points of the length bins

pLCatch

A numeric vector containg expected proportion for each length class in the catch

pLPop

A numeric vector containg expected proportion for each length class in the population

RelRec

Relative recruitment

Ests

A matrix of estimated values

Vars

A vector of estimated variance for SL50, SL95, F/M and SPR

NLL

A numeric NLL values

maxFM

A numeric of maximum estimated F/M value (note this is apical F)

SPRatsize

A vector of cumulative SPR at length (currently only works for GTG model)

fitLog

A vector of error logs for each fit. 0 means everything is okay.

An S4 class containing life history and other parameters

Description

An S4 class containing life history and other parameters

Slots

Species

Character vector of species name

MK

A length-one numeric vector for M/K ratio

M

An optional value for natural mortality (M)

Linf

A length-one numeric vector for Linf

L_units

Character describing units of length parameters

CVLinf

A length-one numeric vector for CV of length-at-age

L50

A length-one numeric vector for length at 50% maturity

L95

A length-one numeric vector for length at 95% maturity

Walpha

A length-one numeric vector for alpha parameter of length-weight relationship

Walpha_units

Character describing units for weight scaling parameter

Wbeta

A length-one numeric vector for beta parameter of length-weight relationship

FecB

A length-one numeric vector for beta parameter of length-fecundity relationship

Steepness

A length-one numeric vector for steepness of SRR

Mpow

A length-one numeric vector for M at length

R0

A length-one numeric vector for initial number of recruits (1 for per-recruit)

SL50

A length-one numeric vector for length at 50% selectivity

SL95

A length-one numeric vector for length at 95% selectivity

MLL

Minimum legal length (inflection point)

sdLegal

Standard deviation of MLL curve

fDisc

Fraction discarded that die

FM

A length-one numeric vector for F/M ratio (note this is apical F)

SPR

A length-one numeric vector for SPR

BinMin

A length-one numeric vector for minimum length bin

BinMax

A length-one numeric vector for maximum length bin

BinWidth

A length-one numeric vector for width of length bins

Run a Shiny Application

Description

Shiny runs one of the Shiny Applications that are included in the package

Usage

Shiny(app)

Arguments

app

The name of the Shiny application to run. Currently the available Shiny apps are "LBSPR" and "Sim"

References

Modified from Deal Attali's code: https://deanattali.com/2015/04/21/r-package-shiny-app/

Calculate Relative Yield, YPR, SPR, SSB, and Recruitment curves for F/M

Description

A function that takes a LB_pars or LB_obj object and returns a data frame of values for relative Yield, YPR, SPR, SSB, and Recruitment at different values of F/M

Usage

calcCurves(LB_obj)

Arguments

LB_obj

An object of class 'LB_obj' or class 'LB_pars' that contains the life history and fishing information

Value

a dataframe with YPR, Yield, SSB, Rec, and FM

Author(s)

A. Hordyk

Calculate F/M given SPR and other parameters

Description

A internal function that optimizes for F/M when SPR is provided in the simulation parameters.

Usage

getFMfun(FM, LB_pars, Control = list())

Arguments

FM

a F/M value

LB_pars

an object of class 'LB_pars' that contains the life history information

Control

a list of control options for the LBSPR model.

Details

The Control options are:

modtype

Model Type: either Growth-Type-Group Model (default: "GTG") or Age-Structured ("absel")

maxsd

Maximum number of standard deviations for length-at-age distribution (default is 2)

ngtg

Number of groups for the GTG model. Default is 13

P

Proportion of survival of initial cohort for maximum age for Age-Structured model. Default is 0.01

Nage

Number of pseudo-age classes in the Age Structured model. Default is 101

maxFM

Maximum value for F/M. Estimated values higher than this are trunctated to maxFM. Default is 4

Value

sum of squares value

Author(s)

A. Hordyk

Create a new LB_lengths object

Description

Function

Usage

## S4 method for signature 'LB_lengths'
initialize(
  .Object,
  file = "none",
  LB_pars = NULL,
  dataType = c("raw", "freq"),
  header = FALSE,
  verbose = TRUE,
  ...
)

Arguments

.Object

class of object to be created

file

file path and name to CSV containing parameters. Alternatively it can be a matrix or vector of length data

LB_pars

a object of class LB_pars

dataType

is the length data individual measurements (raw) or a length frequency (freq)?

header

is there a header?

verbose

display a message?

...

optional additional arguments passed to read.csv

Value

a object of class 'LB_lengths'

Author(s)

A. Hordyk

Create a new LB_obj object

Description

Function

Usage

## S4 method for signature 'LB_obj'
initialize(.Object, defaults = FALSE, verbose = FALSE)

Arguments

.Object

class of object to be created

defaults

use defaults?

verbose

display a message?

Value

a object of class 'LB_obj'

Author(s)

A. Hordyk

Create a new LB_pars object

Description

Function

Usage

## S4 method for signature 'LB_pars'
initialize(.Object, file = "none", defaults = TRUE, verbose = TRUE)

Arguments

.Object

class of object to be created

file

use 'example' to create example LB_pars object. File path and name to CSV containing parameters. Import CSV currently not working

defaults

use defaults for some parameters?

verbose

display a message?

Value

a object of class 'LB_pars'

Author(s)

A. Hordyk

Plot the Relative Yield, YPR, SPR, SSB, and Recruitment curves

Description

A function that plots the Relative Yield, YPR, SPR, SSB, and Recruitment curves

Usage

plotCurves(
  LB_obj,
  X = c("FM", "SSB", "SPR"),
  Y = c("SPR", "SSB", "Yield"),
  size.axtex = 12,
  size.title = 14,
  size.leg = 12,
  size.pt = 4,
  inc.pts = TRUE
)

Arguments

LB_obj

An object of class 'LB_obj' that contains the life history and fishing information

X

a character value indicating what to plot on the x-axis: F/M ("FM") or SSB ("SSB")

Y

a character value indicating what to plot on the y-axis: SPR, SSB, Yield, YPR or Rec(multiple okay)

size.axtex

size of the axis text

size.title

size of axis title

size.leg

size of legend text

size.pt

size of the points on the plots

inc.pts

Include points on the plots?

Value

a ggplot object

Author(s)

A. Hordyk

Plot LBSPR model estimates

Description

A function that plots the estimates of the LBSPR with a smoother line

Usage

plotEsts(
  LB_obj = NULL,
  pars = c("Sel", "FM", "SPR"),
  Lwd = 2.5,
  ptCex = 1.25,
  axCex = 1.45,
  labCex = 1.55,
  doSmooth = TRUE,
  incL50 = FALSE,
  CIcol = "darkgray",
  L50col = "gray"
)

Arguments

LB_obj

an object of class 'LB_obj' that contains the life history and fishing information

pars

a character vectors specifying which plots to create

Lwd

line width

ptCex

size of plotted points

axCex

size of the axis

labCex

size of axis label

doSmooth

apply the smoother?

incL50

include L50 line?

CIcol

colour of the confidence interval bars

L50col

colour of L50 line (if included)

Author(s)

A. Hordyk

Plot the maturity-at-length and selectivity-at-length curves

Description

A function that plots the maturity-at-length and selectivity-at-length curves

Usage

plotMat(
  LB_obj = NULL,
  size.axtex = 12,
  size.title = 14,
  size.leg = 12,
  useSmooth = TRUE,
  Title = NULL
)

Arguments

LB_obj

an object of class 'LB_obj' that contains the life history and fishing information

size.axtex

size of the axis text

size.title

size of axis title

size.leg

size of legend text

useSmooth

use the smoothed estimates?

Title

optional character string for plot title

Value

a ggplot object

Author(s)

A. Hordyk

Circle of estimated SPR and target and limit points

Description

A function that creates a circle plot showing the estimated SPR relative to the target and limit reference points

Usage

plotSPRCirc(
  LB_obj = NULL,
  SPRTarg = 0.4,
  SPRLim = 0.2,
  useSmooth = TRUE,
  Title = FALSE,
  Leg = TRUE,
  limcol = "#ff1919",
  targcol = "#f2ff02",
  abtgcol = "#32ff36",
  labcol = NULL,
  bgcol = "#FAFAFA",
  labcex = 2,
  texcex = 1.3
)

Arguments

LB_obj

an object of class 'LB_obj' that contains the life history and fishing information

SPRTarg

a numeric value specifying the SPR target

SPRLim

a numeric value specifying the SPR limit

useSmooth

use the smoothed estimates? Usually would want to do this

Title

include the title?

Leg

include the legend?

limcol

colour for SPR Limit (hex; default is red)

targcol

colour for SPR target (hex; default is yellow)

abtgcol

colour for above SPR target (hex; default is green)

labcol

optional fixed colour for estimated SPR label

bgcol

colour for the background

labcex

size for the estimated SPR label

texcex

size for estimated other labels

Author(s)

A. Hordyk

General plotting function for simulated data

Description

A general function that plots the simulation object. Includes four different plots: equilbrium size structure, maturity and selectivity curves, growth curves, and relative Yield, YPR, SPR, SSB, and Recruitment curves.

Usage

plotSim(
  LB_obj = NULL,
  type = c("all", "len.freq", "growth", "maturity.select", "yield.curve"),
  lf.type = c("catch", "pop"),
  growth.type = c("LAA", "WAA"),
  y.type = c("SPR", "SSB", "Yield", "YPR"),
  x.type = c("FM", "SSB", "SPR"),
  perRec = FALSE,
  inc.SPR = TRUE,
  Cols = NULL,
  size.axtex = 12,
  size.title = 14,
  size.SPR = 4,
  size.leg = 12,
  inc.pts = TRUE,
  size.pt = 4
)

Arguments

LB_obj

an object of class 'LB_obj' that contains the life history and fishing information

type

a character value indicating which plots to include: "all", "len.freq", "growth", "maturity.select", "yield.curve"

lf.type

a character value indicating if the catch or pop (population) should be plotted for the length frequency

growth.type

should growth be plotted as length-at-age ("LAA") or weight-at-age ("WAA")

y.type

what curves should be plotted on y-axis? "SPR", "SSB", "Yield", "YPR"

x.type

what curves should be plotted on x-axis? "FM", "SSB", "SPR"

perRec

a logical to indicate if plot should be per-recruit (ignore steepness) or not (zero recruitment if SPR below replacement level)

inc.SPR

a logical to indicate if SPR value should be printed in top right corner of plot

Cols

optional character vector of colours for the plot

size.axtex

size of the axis text

size.title

size of axis title

size.SPR

size of SPR text

size.leg

size of legend text

inc.pts

Include points on the plots?

size.pt

size of the points on the plots

Value

a ggplot object

Author(s)

A. Hordyk

Examples

 LB_pars <- new("LB_pars")
 LB_pars@MK <- 1.5
 LB_pars@Linf <- 100
 LB_pars@L50 <- 50
 LB_pars@L95 <- 55
 LB_pars@SL50 <- 60
 LB_pars@SL95 <- 65
 LB_pars@FM <- 1
 Sim <- LBSPRsim(LB_pars)
 plotSim(Sim)

Plot the size data and model fits

Description

A function that plots size data and the fitted LBSPR model

Usage

plotSize(
  LB_obj = NULL,
  size.axtex = 12,
  size.title = 14,
  Title = NULL,
  scales = c("fixed", "free_x", "free_y", "free"),
  inc.text = FALSE,
  warn.size = 0.8
)

Arguments

LB_obj

an object of class 'LB_obj' that contains the life history and fishing information

size.axtex

size of the axis text

size.title

size of axis title

Title

optional character string for plot title

scales

argument to ggplot2 function. Are scales shared across all facets (the default, "fixed"), or do they vary across rows ("free_x"), columns ("free_y"), or both rows and columns ("free")

inc.text

Include text on plotting warning of high F or selectivity estimates?

warn.size

numeric. Size of font for the warnings

Value

a ggplot object

Author(s)

A. Hordyk

Plot sampled length structure against target simulated size composition

Description

A function that plots the observed size structure against the expected size composition at the target SPR

Usage

plotTarg(
  LB_pars = NULL,
  LB_lengths = NULL,
  yr = 1,
  Cols = NULL,
  title = NULL,
  targtext = TRUE,
  size.axtex = 12,
  size.title = 14,
  scales = c("fixed", "free_x", "free_y", "free")
)

Arguments

LB_pars

an object of class 'LB_pars' that contains the life history and fishing information

LB_lengths

an object of class 'LB_lengths' that contains the observed size data

yr

index for sampled length data (defaults to 1)

Cols

optional character vector of colours for the plot

title

character - optional title for plot

targtext

logical - should the SPR target text be displayed as a subtitle?

size.axtex

size of the axis text

size.title

size of axis title

scales

argument to ggplot2 function. Are scales shared across all facets (the default, "fixed"), or do they vary across rows ("free_x"), columns ("free_y"), or both rows and columns ("free")

Value

a ggplot object

Author(s)

A. Hordyk