Version: 0.0.2
Date: 2026-1-13
Title: Fisheries Analysis and Modeling Simulator
Description: Simulates the dynamics of exploited fish populations using the Jones modification of the Beverton-Holt equilibrium yield equation to compute yield-per-recruit and dynamic pool models (Ricker 1975) https://publications.gc.ca/site/eng/480738/publication.html. Allows users to evaluate minimum, slot, and inverted length limits on exploited fisheries using specified life history parameters. Users can simulate population under a variety of conditional fishing mortality and conditional natural mortality. Calculated quantities include number of fish harvested and dying naturally, mean weight and length of fish harvested, number of fish that reach specified lengths of interest, total number of fish and biomass in the population, and stock density indices.
URL: https://github.com/fishR-Core-Team/rFAMS/
BugReports: https://github.com/fishR-Core-Team/rFAMS/issues
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Depends: R (≥ 4.1.0)
Imports: stats, purrr, FSA
Suggests: dplyr, ggplot2, metR, knitr, rmarkdown, testthat (≥ 3.0.0), zipfR, quarto, FSAdata, tidyr
Encoding: UTF-8
RoxygenNote: 7.3.3
Config/testthat/edition: 3
Config/Needs/website: quarto
NeedsCompilation: no
Packaged: 2026-01-20 14:51:23 UTC; jason.doll
Author: Jason C. Doll [aut, cre], Derek H. Ogle [aut]
Maintainer: Jason C. Doll <jcdoll20@hotmail.com>
Repository: CRAN
Date/Publication: 2026-02-10 21:30:02 UTC

Internal functions.

Description

Internal functions that are common to several functions in rFAMS.

Usage

.onAttach(libname, pkgname)

Main function to simulate expected yield using the Dynamic Pool model for a range of input parameters, including minimum length limits for harvest

Description

Estimate yield using the Beverton-Holt Yield-per-Recruit (YPR) model using ranges of values for conditional fishing mortality (cf), conditional natural mortality (cm), and minimum length limits for harvest (minLL).

Usage

dpmBH(
  simyears,
  minLL,
  cf,
  cm,
  rec,
  lhparms,
  matchRicker = FALSE,
  species = NULL,
  group = NULL
)

Arguments

simyears

A single numeric for the lower limit of minimum length limit for harvest in mm.

minLL

A single numeric representing the minimum length limit for harvest in mm.

cf

A matrix of conditional fishing mortality where each row represents a year and each column represents age. Ages are age-0 through maximum age.

cm

A matrix of conditional natural mortality where each row represents a year and each column represents age. Ages are age-0 through maximum age.

rec

A single numeric representing initial recruitment abundance.

lhparms

A named vector or list that contains values for each N0, tmax, Linf, K, t0, LWalpha, and LWbeta. See makeLH for definitions of these life history parameters. Also see details.

matchRicker

A logical that indicates whether the yield function should match that in Ricker (). Defaults to TRUE. The only reason to changed to FALSE is to try to match output from FAMS. See the "YPR_FAMSvRICKER" article.

species

is a single character to specify the species used in the simulation and will define the length for stock, quality, preferred, memorable, and trophy. Length categories are obtained from the FSA package, see the PSDlit documentation.

group

is a single character to specify the sub-group name of a species used in the simulation and will define the length for stock, quality, preferred, memorable, and trophy. Length categories are obtained from the FSA package, see the PSDlit documentation.

Details

Details

Value

A list with two data.frame object. The first list item contains a data.frame with the following calculated values in a summary by age:

For convenience the data.frame also contains the model input values (minLL, N0, N0, Linf, K, t0, LWalpha, LWbeta, and tmax).

The data.frame also contains a notes value which may contain abbreviations for "issues" that occurred when computing the results and were adjusted for. The possible abbreviates are as follows:

The second list item contains a data.frame with the following calculated values in a summary by year:

PSD-X are calculated based on the number of fish in each category (stock, quality, preferred, memorable, and trophy) at the beginning of the year. That is, the length at age during the start of the year is used to assign PSD-X categories at age. For example, if Quality size is 300mm, an age-1 fish at 275mm at the start of the year would not be counted as a quality sized fish, but an age-2 fish at 325mm at the start of the year would be counted as a quality sized fish.

Author(s)

Jason C. Doll, jason.doll@fmarion.edu

See Also

yprBH_func for estimating yield from single values of cf, cm, and minLL, and yprBH_minLL_fixed for simulating yield with multiple values of cf and cm but a fixed value for minLL.

Examples

#load required library
library(dplyr)
library(ggplot2)

# Setting a custom theme for plots (to make look nice)
# Optional for plotting
theme_FAMS <- function(...) {
  theme_bw() +
    theme(
      panel.grid.major=element_blank(),panel.grid.minor=element_blank(),
      axis.text=element_text(size=14,color="black"),
      axis.title=element_text(size=16,color="black"),
      axis.title.y=element_text(angle=90),
      axis.line=element_line(color="black"),
      panel.border=element_blank()
    )
}

# Example of simulating yield with the dynamic pool model,

lhparms <- makeLH(N0=100,tmax=30,Linf=1349.5,K=0.111,t0=0.065,
            LWalpha=-5.2147,LWbeta=3.153)
simyears <- 50
minLL <- 400
rec <- genRecruits(method = "fixed", Nrec = 100, simyears = simyears)
cm <- matrix(rep(c(rep(0,1), rep(0.18,(lhparms$tmax))), simyears),nrow=simyears,byrow=TRUE)
cf <- matrix(rep(c(rep(0,1), rep(0.33,(lhparms$tmax))), simyears),nrow=simyears,byrow=TRUE)

out<-dpmBH(simyears = simyears, minLL = minLL, cf = cf, cm = cm, rec = rec, lhparms = lhparms,
           matchRicker=FALSE,species="Striped Bass",group="landlocked")

#Use summary by year data frame to plot PSD vs year
ggplot(data=out[[2]],mapping=aes(x=year,y=PSD)) +
  geom_point() +
  geom_line() +
  labs(y="PSD",x="Year") +
  theme_FAMS()

#Use summary by year data frame to plot yield vs year
ggplot(data=out[[2]],mapping=aes(x=year,y=Yield_age_1plus)) +
  geom_point() +
  geom_line() +
  labs(y="Total yield (g)",x="Year") +
  theme_FAMS()

#Plot date using summary by age
#filter for year class = 1
plotdat<- out[[1]] |> filter(yc==1)
#Plot yield vs age
ggplot(data=plotdat,mapping=aes(x=age,y=yield)) +
  geom_point() +
  geom_line() +
  labs(y="Total yield (g)",x="Age") +
  theme_FAMS()

#Plot Number harvested vs age
ggplot(data=plotdat,mapping=aes(x=age,y=N_harvest)) +
  geom_point() +
  geom_line() +
  labs(y="Number harvested",x="Age") +
  theme_FAMS()


#Recruitment based on a normal distribution
rec <- genRecruits(method = "normal", simyears = simyears,
                   meanR = 1000, sdR = 500, MinR = 100, MaxR =2500)
cm <- matrix(rep(c(rep(0,1), rep(0.18,(lhparms$tmax))), simyears),nrow=simyears,byrow=TRUE)
cf <- matrix(rep(c(rep(0,1), rep(0.33,(lhparms$tmax))), simyears),nrow=simyears,byrow=TRUE)

out_2<-dpmBH(simyears = simyears, minLL = minLL, cf = cf, cm = cm, rec = rec, lhparms = lhparms,
             matchRicker=FALSE,species="Striped Bass",group="landlocked")

#Use summary by year data frame to plot PSD vs year
ggplot(data=out_2[[2]],mapping=aes(x=year,y=PSD)) +
  geom_point() +
  geom_line() +
  labs(y="PSD",x="Year") +
  theme_FAMS()

#Use summary by year data frame to plot yield vs year
ggplot(data=out_2[[2]],mapping=aes(x=year,y=Yield_age_1plus)) +
  geom_point() +
  geom_line() +
  labs(y="Total yield (g)",x="Year") +
  theme_FAMS()

#Plot date using summary by age
#Plot yield vs age for each year class
ggplot(data=out_2[[1]],mapping=aes(x=age,y=yield,group=yc,color=yc)) +
  geom_point() +
  geom_line() +
  labs(y="Total yield (g)",x="Age") +
  theme_FAMS()

#Plot Number harvested vs age
ggplot(data=out_2[[1]],mapping=aes(x=age,y=N_harvest,group=yc,color=yc)) +
  geom_point() +
  geom_line() +
  labs(y="Number harvested",x="Age") +
  theme_FAMS()

Simulate yield using the dynamic pool model.

Description

Estimate yield-at-age using the Beverton-Holt Yield-per-Recruit (YPR) model for a single year-class. This main function accepts a minimum length limit for harvest (minLL), a vector for conditional fishing mortality (cf), a vector of conditional natural mortality (cm), a vector of recruitment abundance (rec), and life history parameters (lhparams).

Usage

dpmBH_func(minLL, cf, cm, rec, lhparms, matchRicker = FALSE)

Arguments

minLL

A single numeric representing the minimum length limit for harvest in mm.

cf

A matrix of conditional fishing mortality where each row represents a year and each column represents age. Ages are age-0 through maximum age.

cm

A matrix of conditional natural mortality where each row represents a year and each column represents age. Ages are age-0 through maximum age.

rec

A single numeric representing initial recruitment abundance.

lhparms

A named vector or list that contains values for each N0, tmax, Linf, K, t0, LWalpha, and LWbeta. See makeLH for definitions of these life history parameters. Also see details.

matchRicker

A logical that indicates whether the yield function should match that in Ricker (). Defaults to TRUE. The only reason to changed to FALSE is to try to match output from FAMS. See the "YPR_FAMSvRICKER" article.

Details

Details will be filled out later

Value

A data.frame with the following calculated values:

For convenience the data.frame also contains the model input values (minLL, N0, N0, Linf, K, t0, LWalpha, LWbeta, and tmax).

The data.frame also contains a notes value which may contain abbreviations for "issues" that occurred when computing the results and were adjusted for. The possible abbreviates are as follows:

Author(s)

Jason C. Doll, jason.doll@fmarion.edu

References

Ricker, W.E. 1975. Computation and interpretation of biological statistics of fish populations. Technical Report Bulletin 191, Bulletin of the Fisheries Research Board of Canada. Was (is?) from https://waves-vagues.dfo-mpo.gc.ca/library-bibliotheque/1485.pdf.

Slipke, J.W., and M.J. Maceina. 2014. Fishery analysis and modeling simulator. v1.64. American Fisheries Society, Bethesda, MD.

Examples

lhparms <- makeLH(N0=100,tmax=30,Linf=1349.5,K=0.111,t0=0.065,LWalpha=-5.2147,LWbeta=3.153)

# simulate yield from a single year-class
cm <- rep(0.18,(lhparms$tmax+1))
cf <- c(rep(0,3), rep(0.33,(lhparms$tmax+1) - 3))

Res_1 <- dpmBH_func(minLL=400,cm=cm,cf=cf,rec=1000,lhparms=lhparms,matchRicker=FALSE)

Res_1

Compute meta-analytic estimates of instantaneous and conditional natural mortality

Description

Several methods may be used to estimate instantaneous (M) and conditional natural mortality (cm) from other types of data, especially those saved in the life history parameters vector/list from makeLH.

Usage

est_natmort(lhparms = NULL, method = "rFAMS", incl.avg = FALSE, ...)

Arguments

lhparms

A named vector or string returned by lhparms.

method

A string that indicates what methods to use to estimate M (see metaM).

incl.avg

A logical that indicates whether the average cm should be computed from the estimated M of all methods.

...

Option arguments for parameter values required by methods using parameters other than those in lhparms. See examples.

Details

The default methods to use are all of those listed in Mmethods that use some of the life history parameters required by makeLH. These methods are not all equally useful or robust, so the user may want to select a subset of them for use after learning more about them. See references in metaM.

Other methods that require parameters other than those required by makeLH can be used by providing the name of the method in method and the required parameters as arguments, as defined in metaM. See metaM for more details and the examples below for an example.

Value

A data.frame with the following items:

Author(s)

Derek Ogle

Examples

# An example lhparm as would be returned from makeLH
tmp <- list(N0=100,tmax=15,Linf=500,K=0.3,t0=-0.5,LWalpha=-5.16,LWbeta=3.1)

# All methods in metaM() that use those life history parameters
est_natmort(tmp)

# Same but including the average in the last row
est_natmort(tmp,incl.avg=TRUE)

# Selecting just one method
est_natmort(tmp,method="HoenigNLS")

# Selecting several methods
est_natmort(tmp,method=c("HoenigNLS","HoenigO","HoenigO2","HoenigLM"))

# A method that uses a parameter not usually in lhparms
est_natmort(tmp,method="QuinnDeriso",PS=0.05)

# Selecting all Hoenig methods using Mmethods from FSA
est_natmort(tmp,method=FSA::Mmethods("Hoenig"))

# Over-riding the Linf param in parameters list, but others from tmp
est_natmort(tmp,method="PaulyLNoT")              # Linf from tmp
est_natmort(tmp,Linf=1000/10,method="PaulyLNoT") # Linf from Linf= arg

Generate a vector of recruitment abundance for the dynamic pool model.

Description

These function is used to generate recruitment abundances across multiple years using different random function.

Usage

genRecruits(
  method = c("fixed", "uniform", "normal", "StrYC_Nth", "StrYC_randInt"),
  simyears = 50,
  Nrec = NULL,
  MinR = NULL,
  MaxR = NULL,
  meanR = NULL,
  sdR = NULL,
  Nthyr = NULL,
  sizeStr = NULL,
  avgFreq = NULL
)

Arguments

method

A single string to call the method of generating a vector of recruits. fixed generate recruitment based on a fixed value for each year of simyears, uniform generates recruitment based on random values from a unifrom distribution for each year of simyears, normal generates recruitment based on random values from a unifrom distribution for each year of simyears, StrYC_Nth generates recruitment based on a strong year class every Nth year, and StrYC_randInt generates recruitment based on a strong year classes at random intervals.

simyears

A single numeric that sets the number of years to simulate recruitment

Nrec

A single numeric that sets the fixed number of recruitment

MinR

A single numeric that sets the minimum recruitment abundance during simulations.

MaxR

A single numeric that sets the maximum recruitment abundance during simulations.

meanR

A single numeric that sets the mean recruitment abundance.

sdR

A single numeric that sets the standard deviation of recruitment abundance

Nthyr

A single numeric that sets the Nth year that a strong year class will occur

sizeStr

A single numeric that sets the multiplier for the strong year class relative to meanR

avgFreq

A single numeric that sets the average frequency of a strong year class.

Details

This function is used internally and not generally used interactively

Value

A vector that contains the given recruitment options that can be used directly in the dynamic pool model (e.g., dpmBH).

Author(s)

Jason C. Doll, jason.doll@fmarion.edu

Examples

# To be filled out later

Make a list or vector of life history parameters for yield-per-recruit analyses.

Description

Efficiently construct either a vector or list that contains the seven life history parameters required for Beverton-Holt yield-per-recruit analyses. The parameters can be given by the user through function arguments. Alternativvely, the von Bertalanffy parameters (Linf, K, and t0) may be extracted from an nls object created from fitting the von Bertalanffy equation to length-at-age data (object created outside this function). Similarly the log10-transformed weight-length model coefficients may be extracted from an lm object created from fitting the model to transformed weight-length data (object created outside this function). All parameter values are checked for sanity (e.g., Linf>0).

Usage

makeLH(N0, tmax, Linf, K, t0, LWalpha, LWbeta, restype = c("list", "vector"))

Arguments

N0

A single numeric that represents the number of fish in the population at the hypothetical age of t0.

tmax

A single whole number that represents maximum age in the population in years.

Linf

A single numeric that represents the point estimate of asymptotic mean length from the von Bertalanffy growth model OR an nls object created from fitting the von Bertalanffy equation to length-at-age data.

K

A single numeric that represents the point estimate of the Brody growth coefficient from the von Bertalanffy growth model.

t0

A single numeric that represents the point estimate of the x-intercept (i.e., theoretical age at a mean length of 0) from the von Bertalanffy growth model.

LWalpha

A single numeric that represents the point estimate of alpha from the length-weight regression on the log10 scale OR an lm object created from fitting the model to log10-transformed weight-length data.

LWbeta

A single numeric that represents the point estimate of beta from the length-weight regression on the log10 scale.

restype

A character that indicates the type of output (list or vector) returned by the function.

Details

Use of this function for putting life history parameters into a list or vector is recommended as (i) values for Linf, K, t0, LWalpha, and LWbeta can be extracted from objects from appropriate model fitting and (ii) checks for impossible or improbable values for each parameter are performed; i.e.,

Value

A named list or vector (depending on restype) that contains the given (or extracted) life history parameters values that can be used directly in the yield-per-recruit calculation functions (e.g., yprBH_SlotLL).

Author(s)

Derek Ogle 

# Best practice for entering life history parameter values
LH <- makeLH(N0=100,tmax=15,Linf=600,K=0.30,t0=-0.6,
             LWalpha=-5.453,LWbeta=3.10)

# Works but no checks on the values
LH <- list(N0=100,tmax=15,Linf=600,K=0.30,t0=-0.6,
           LWalpha=-5.453,LWbeta=3.10)

If a list is returned then values will be displayed with the number of decimals provided by the user. If a vector is returned then the number of decimals displayed will be the same for each value and will match the value supplied by the user with the most decimals. Thus, a list is preferred as it will be easier to match what was given to what was expected to be given.

Examples

library(FSA)
library(FSAdata)

# ----- Simple examples with explicity arguments for each -------------------
makeLH(N0=100,tmax=15,Linf=500,K=0.3,t0=-0.5,LWalpha=-5.613,LWbeta=3.1)
makeLH(N0=100,tmax=15,Linf=500,K=0.3,t0=-0.5,LWalpha=-5.613,LWbeta=3.1,
       restype="vector")

# ----- Example of extracting values from model fits ------------------------
# N0 and tmax provided as arguments ... Linf, K, and t0 extracted from nls
#   output and LWalpha and LWbeta extracted from lm output. Note that nls
#   and lm output here are just examples of the function, they should be
#   calculated for the same species from the same waterbody, etc.

## get some LVB results (as an example)
data(SpotVA1,package="FSA")
SpotVA1 <- SpotVA1 |>
  dplyr::mutate(tl=tl*25.4)
vb1 <- FSA::vbFuns()
fit1 <- nls(tl~vb1(age,Linf,K,t0),data=SpotVA1,
            start=FSA::vbStarts(tl~age,data=SpotVA1))

## get some LW results (as an example)
data(BluegillLM,package="FSAdata")
BluegillLM <- BluegillLM |>
  dplyr::mutate(logW=log10(wght),
                logL=log10(tl))
fit2 <- lm(logW~logL,data=BluegillLM)

makeLH(N0=100,tmax=15,Linf=fit1,LWalpha=fit2)

Main function to simulate expected yield using the Beverton-Holt Yield Per Recruit model for a slot limit

Description

Main wrapper function to estimate yield using the Beverton-Holt YPR model. This main function accepts a range of values for cf, cm, recruitment length, lower slot limit length, and upper slot limit length.

Usage

yprBH_SlotLL(
  recruitmentTL,
  lowerSL,
  upperSL,
  cfunder,
  cfin,
  cfabove,
  cmmin,
  cmmax,
  cminc,
  loi = NA,
  lhparms,
  matchRicker = FALSE
)

Arguments

recruitmentTL

A numeric representing the minimum length limit for recruiting to the fishery in mm.

lowerSL

A numeric representing the length of the lower slot limit in mm.

upperSL

A numeric representing the length of the upper slot limit in mm.

cfunder

Single value, conditional fishing mortality under the lower slot limit.

cfin

Single value, conditional fishing mortality within the lower and upper slot limit.

cfabove

Single value, conditional fishing mortality over the upper slot limit.

cmmin

Single value, minimum conditional natural mortality

cmmax

Single value, maximum conditional natural mortality

cminc

Single value, increment to cycle from minimum to maximum conditional natural mortality

loi

A numeric vector for lengths of interest. Used to determine number of fish that reach desired lengths.

lhparms

A named vector or list that contains values for each N0, tmax, Linf, K, t0, LWalpha, and LWbeta. See makeLH for definitions of these life history parameters. Also see details.

matchRicker

A logical that indicates whether the yield function should match that in Ricker (). Defaults to TRUE. The only reason to changed to FALSE is to try to match output from FAMS. See the "YPR_FAMSvRICKER" article.

Details

Details will be filled out later

Value

A data.frame with the following calculated values:

Author(s)

Jason C. Doll, jason.doll@fmarion.edu

Examples

#Load other required packages for organizing output and plotting
library(ggplot2)
library(dplyr)
library(tidyr)

# Custom theme for plots (to make look nice)
theme_FAMS <- function(...) {
  theme_bw() +
  theme(
    panel.grid.major=element_blank(),panel.grid.minor=element_blank(),
    axis.text=element_text(size=14,color="black"),
    axis.title=element_text(size=16,color="black"),
    axis.title.y=element_text(angle=90),
    axis.line=element_line(color="black"),
    panel.border=element_blank()
  )
}

# Life history parameters to be used below
LH <- makeLH(N0=100,tmax=15,Linf=592,K=0.20,t0=-0.3,LWalpha=-5.528,LWbeta=3.273)

#Estimate yield
 Res_1 <- yprBH_SlotLL(recruitmentTL=200,lowerSL=250,upperSL=325,
                       cfunder=0.25,cfin=0.6,cfabove=0.15,cmmin=0.3,cmmax=0.6,cminc=0.05,
                       loi=c(200,250,300,325,350),lhparms=LH)

 Res_1

# Plot results
# Total Yield vs Conditional Natural Mortality (cm)
ggplot(data=Res_1,mapping=aes(x=cm,y=TotalYield)) +
  geom_point() +
  geom_line() +
  labs(y="Total Yield (g)",x="Conditional Natural Mortality (cm)") +
  theme_FAMS()


# Yield under, in, and above the slot limit vs Conditional Natural Mortality (cm)
# Select columns for plotting
plot_data <- Res_1 %>%
  select(cm, yieldUnder, yieldIn, yieldAbove) %>%
  pivot_longer(!cm, names_to="YieldCat",values_to="Yield")

# Generate plot
ggplot(data=plot_data,mapping=aes(x=cm,y=Yield,group=YieldCat,color=YieldCat)) +
  geom_point() +
  scale_color_discrete(name="Yield",labels=c("Above SL","In SL","Under SL"))+
  geom_line() +
  labs(y="Total Yield (g)",x="Conditional Natural Mortality (cm)") +
  theme_FAMS() +
  theme(legend.position = "top")+
  guides(color=guide_legend(title="Yield"))

Simulate expected yield using the Beverton-Holt Yield-per-Recruit model for single input parameters

Description

Estimate yield using the Beverton-Holt Yield-per-Recruit (YPR) model. This main function accepts only single values for conditional fishing mortalitiy (cf), conditional natural mortality (cm), and a minimum length limit for harvest (minLL).

Usage

yprBH_func(minLL, cf, cm, loi = NA, lhparms, matchRicker = FALSE)

Arguments

minLL

A single numeric representing the minimum length limit for harvest in mm.

cf

A single numeric representing conditional fishing mortality.

cm

A single numeric representing conditional natural mortality.

loi

A numeric vector for lengths of interest. Used to determine number of fish that reach desired lengths.

lhparms

A named vector or list that contains values for each N0, tmax, Linf, K, t0, LWalpha, and LWbeta. See makeLH for definitions of these life history parameters. Also see details.

matchRicker

A logical that indicates whether the yield function should match that in Ricker (). Defaults to TRUE. The only reason to changed to FALSE is to try to match output from FAMS. See the "YPR_FAMSvRICKER" article.

Details

Details will be filled out later

Value

A data.frame with the following calculated values:

For convenience the data.frame also contains the model input values (minLL, cf, cm, N0, Linf, K, t0, LWalpha, LWbeta, and tmax).

The data.frame also contains a notes value which may contain abbreviations for "issues" that occurred when computing the results and were adjusted for. The possible abbreviates are as follows:

Author(s)

Jason C. Doll, jason.doll@fmarion.edu

References

Ricker, W.E. 1975. Computation and interpretation of biological statistics of fish populations. Technical Report Bulletin 191, Bulletin of the Fisheries Research Board of Canada. Was (is?) from https://waves-vagues.dfo-mpo.gc.ca/library-bibliotheque/1485.pdf.

Slipke, J.W., and M.J. Maceina. 2014. Fishery analysis and modeling simulator. v1.64. American Fisheries Society, Bethesda, MD.

See Also

yprBH_minLL_fixed and yprBH_minLL_var for simulating yield with multiple values of cf, cm, and minLL.

Examples

#' # Life history parameters to be used below
LH <- makeLH(N0=100,tmax=15,Linf=592,K=0.20,t0=-0.3,LWalpha=-5.528,LWbeta=3.273)

# Estimate yield with fixed parameters
Res_1 <- yprBH_func(minLL=355,cf=0.45,cm=0.25,
                    loi=c(200,250,300,325,350),lhparms=LH)
Res_1

Main function to simulate expected yield using the Beverton-Holt Yield-per-Recruit model for a range of input parameters

Description

Estimate yield using the Beverton-Holt Yield-per-Recruit (YPR) model using a range of values for conditional fishing (cf) and natural (cm) mortality and a single fixed minimum length limit for harvest (minLL).

Usage

yprBH_minLL_fixed(
  minLL,
  cfmin,
  cfmax,
  cfinc,
  cmmin,
  cmmax,
  cminc,
  loi = NA,
  lhparms,
  matchRicker = FALSE
)

Arguments

minLL

The minimum length limit for harvest in mm

cfmin

A single numeric for minimum conditional fishing mortality.

cfmax

A single numeric for maximum conditional fishing mortality.

cfinc

A single numeric for increment to cycle from minimum to maximum conditional fishing mortality.

cmmin

A single numeric for minimum conditional natural mortality.

cmmax

A single numeric for maximum conditional natural mortality.

cminc

A single numeric for increment to cycle from minimum to maximum conditional natural mortality.

loi

A numeric vector for lengths of interest. Used to determine number of fish that reach desired lengths.

lhparms

A named vector or list that contains values for each N0, tmax, Linf, K, t0, LWalpha, and LWbeta. See makeLH for definitions of these life history parameters. Also see details.

matchRicker

A logical that indicates whether the yield function should match that in Ricker (). Defaults to TRUE. The only reason to changed to FALSE is to try to match output from FAMS. See the "YPR_FAMSvRICKER" article.

Details

Details will be filled out later

Value

A data.frame with the following calculated values:

For convenience the data.frame also contains the model input values (minLL; cf derived from cfmin, cfmax, and cfinc; cm derived from cmmin, cmmax, and cminc; N0; Linf; K; t0; LWalpha; LWbeta; and tmax).

The data.frame also contains a notes value which may contain abbreviations for "issues" that occurred when computing the results and were adjusted for. The possible abbreviates are defined under "values" in the documentation for yprBH_func.

Author(s)

Jason C. Doll, jason.doll@fmarion.edu

See Also

yprBH_func for estimating yield from single values of cf, cm, and minLL, and yprBH_minLL_var for simulating yield with multiple values of cf, cm, and minLL.

Examples

# Life history parameters to be used below
LH <- makeLH(N0=100,tmax=15,Linf=592,K=0.20,t0=-0.3,LWalpha=-5.528,LWbeta=3.273)

# Estimate yield for multiple values of minLL, cf, and cm
# # This is a minimal example, lengthinc, cfinc, cminc would likely be smaller
# #   to produce finer-scaled results
Res_1 <- yprBH_minLL_fixed(minLL=200,
                         cfmin=0.1,cfmax=0.9,cfinc=0.1,
                         cmmin=0.1,cmmax=0.9,cminc=0.1,
                         loi=c(200,250,300,350),lhparms=LH)

# Load other required packages for organizing output and plotting
library(dplyr)    ## for filter
library(ggplot2)  ## for ggplot et al.
library(tidyr)    ## for pivot_longer

# Custom theme for plots (to make look nice)
theme_FAMS <- function(...) {
  theme_bw() +
  theme(
    panel.grid.major=element_blank(),panel.grid.minor=element_blank(),
    axis.text=element_text(size=14,color="black"),
    axis.title=element_text(size=16,color="black"),
    axis.title.y=element_text(angle=90),
    axis.line=element_line(color="black"),
    panel.border=element_blank()
  )
}

# Yield curve (yield vs exploitation)
# Extract results for cm=0.40
plot_dat <- Res_1 |> dplyr::filter(cm==0.40)

ggplot(data=plot_dat,mapping=aes(x=u,y=yield)) +
  geom_point() +
  geom_line() +
  labs(y="Yield (g)",x="Exploitation (u)") +
  theme_FAMS()

#Plot number of fish reaching 300 mm as a function of exploitation with cm = 0.40
ggplot(data=plot_dat,mapping=aes(x=u,y=`N at 300 mm`)) +
  geom_point() +
  geom_line() +
  labs(y="Number of fish at 300 mm",x="Exploitation (u)") +
  theme_FAMS()
# Plot number of fish reaching 300 mm as a function of exploitation with cm = 0.40
# Select columns for plotting and convert to long
plot_data_long <- plot_dat %>%
  select(u,`N at 200 mm`, `N at 250 mm`, `N at 300 mm`, `N at 350 mm`) %>%
  pivot_longer(!u, names_to="loi",values_to="number")

# Generate plot
ggplot(data=plot_data_long,mapping=aes(x=u,y=number,group=loi,color=loi)) +
  geom_point() +
  scale_color_discrete(name="Yield",labels=c("N at 200 mm",
                       "N at 250 mm", "N at 300 mm", "N at 350 mm"))+
  geom_line() +
  labs(y="Number of fish",x="Exploitation (u)") +
  theme_FAMS() +
  theme(legend.position = "top")+
  guides(color=guide_legend(title="Length of interest"))

Main function to simulate expected yield using the Beverton-Holt Yield-per-Recruit model for a range of input parameters, including minimum length limits for harvest

Description

Estimate yield using the Beverton-Holt Yield-per-Recruit (YPR) model using ranges of values for conditional fishing mortality (cf), conditional natural mortality (cm), and minimum length limits for harvest (minLL).

Usage

yprBH_minLL_var(
  lengthmin,
  lengthmax,
  lengthinc,
  cfmin,
  cfmax,
  cfinc,
  cmmin,
  cmmax,
  cminc,
  loi = NA,
  lhparms,
  matchRicker = FALSE
)

Arguments

lengthmin

A single numeric for the lower limit of minimum length limit for harvest in mm.

lengthmax

A single numeric for the upper limit of minimum length limit for harvest in mm.

lengthinc

A single numeric for the increment to cycle from lower to upper minimum length limit for harvest in mm.

cfmin

A single numeric for minimum conditional fishing mortality.

cfmax

A single numeric for maximum conditional fishing mortality.

cfinc

A single numeric for increment to cycle from minimum to maximum conditional fishing mortality.

cmmin

A single numeric for minimum conditional natural mortality.

cmmax

A single numeric for maximum conditional natural mortality.

cminc

A single numeric for increment to cycle from minimum to maximum conditional natural mortality.

loi

A numeric vector for lengths of interest. Used to determine number of fish that reach desired lengths.

lhparms

A named vector or list that contains values for each N0, tmax, Linf, K, t0, LWalpha, and LWbeta. See makeLH for definitions of these life history parameters. Also see details.

matchRicker

A logical that indicates whether the yield function should match that in Ricker (). Defaults to TRUE. The only reason to changed to FALSE is to try to match output from FAMS. See the "YPR_FAMSvRICKER" article.

Details

Details will be filled out later

Value

A data.frame with the following calculated values:

For convenience the data.frame also contains the model input values (minLL derived from lengthmin, lengthmax, and lengthinc; cf derived from cfmin, cfmax, and cfinc; cm derived from cmmin, cmmax, and cminc; N0; Linf; K; t0; LWalpha; LWbeta; and tmax).

The data.frame also contains a notes value which may contain abbreviations for "issues" that occurred when computing the results and were adjusted for. The possible abbreviates are defined under "values" in the documentation for yprBH_func.

Author(s)

Jason C. Doll, jason.doll@fmarion.edu

See Also

yprBH_func for estimating yield from single values of cf, cm, and minLL, and yprBH_minLL_fixed for simulating yield with multiple values of cf and cm but a fixed value for minLL.

Examples

# Life history parameters to be used below
LH <- makeLH(N0=100,tmax=15,Linf=592,K=0.20,t0=-0.3,LWalpha=-5.528,LWbeta=3.273)

# Estimate yield for multiple values of minLL, cf, and cm
# # This is a minimal example, lengthinc, cfinc, cminc would likely be smaller
# #   to produce finer-scaled results.
Res_1 <- yprBH_minLL_var(lengthmin=200,lengthinc=50,lengthmax=550,
                       cfmin=0.1,cfmax=0.9,cfinc=0.1,
                       cmmin=0.1,cmmax=0.9,cminc=0.1,
                       loi=c(400,450,500,550),lhparms=LH)

# Load other required packages for organizing output and plotting
library(dplyr)    ## for filter
library(ggplot2)  ## for ggplot et al.
library(metR)     ## geom_text_contour

# Custom theme for plots (to make look nice)
theme_FAMS <- function(...) {
  theme_bw() +
  theme(
    panel.grid.major=element_blank(),panel.grid.minor=element_blank(),
    axis.text=element_text(size=14,color="black"),
    axis.title=element_text(size=16,color="black"),
    axis.title.y=element_text(angle=90),
    axis.line=element_line(color="black"),
    panel.border=element_blank()
  )
}

# Yield curve (yield vs exploitation)
# Extract results for cm=0.40 and minimum length limit=400
plot_dat <- Res_1 |> dplyr::filter(cm==0.40,minLL==400)

ggplot(data=plot_dat,mapping=aes(x=u,y=yield)) +
  geom_point() +
  geom_line() +
  labs(y="Yield (g)",x="Exploitation (u)") +
  theme_FAMS()

# Yield curves by varying minimum lengths, using cm=40
plot_dat <- Res_1 |> filter(cm==0.40)

ggplot(data=plot_dat,mapping=aes(y=yield,x=u,
                                 group=minLL,color=minLL)) +
  geom_line(linewidth=1) +
  scale_color_gradient2(high="black") +
  labs(y="Yield (g)",x="Exploitation (u)",color="Min Length Limit") +
  theme_FAMS()

# Yield isopleths for varying minLL and exploitation with cm=0.40
# # Using same data as previous example
ggplot(data=plot_dat,mapping=aes(x=u,y=minLL,z=yield)) +
  geom_contour2(aes(label = after_stat(level))) +
  xlab("Exploitation (u)") +
  ylab("Minimum length limit (mm)") +
  theme_FAMS()

# Same as previous but using number harvested isopleths
ggplot(data=plot_dat,mapping=aes(x=u,y=minLL,z=Nharvest)) +
  geom_contour2(aes(label = after_stat(level))) +
  xlab("Exploitation (u)")+
  ylab("Minimum length limit (mm)")+
  theme_FAMS()

Function to simulate expected yield using the Beverton-Holt Yield Per Recruit model for single input parameters

Description

Function to estimate yield using the Beverton-Holt YPR model. This main function accepts only single values for cf, cm, and minlength. Use the wrapper ypr() function for specifying range of cf, cm, and minlength

Usage

yprBH_slot_func(
  recruitmentTL,
  lowerSL,
  upperSL,
  cfunder,
  cfin,
  cfabove,
  cm,
  loi = NA,
  lhparms,
  matchRicker = FALSE
)

Arguments

recruitmentTL

A numeric representing the minimum length limit for recruiting to the fishery in mm.

lowerSL

A numeric representing the length of the lower slot limit in mm.

upperSL

A numeric representing the length of the upper slot limit in mm.

cfunder

Single value, conditional fishing mortality under the lower slot limit.

cfin

Single value, conditional fishing mortality within the lower and upper slot limit.

cfabove

Single value, conditional fishing mortality over the upper slot limit.

cm

A numeric representing conditional natural mortality

loi

A numeric vector for lengths of interest. Used to determine number of fish that reach desired lengths.

lhparms

A named vector or list that contains values for each N0, tmax, Linf, K, t0, LWalpha, and LWbeta. See makeLH for definitions of these life history parameters. Also see details.

matchRicker

A logical that indicates whether the yield function should match that in Ricker (). Defaults to TRUE. The only reason to changed to FALSE is to try to match output from FAMS. See the "YPR_FAMSvRICKER" article.

Details

Details will be filled out later

Value

the following calculated and input values in a data.frame

Author(s)

Jason C. Doll, jason.doll@fmarion.edu

Examples

# Life history parameters to be used below
LH <- makeLH(N0=100,tmax=15,Linf=592,K=0.20,t0=-0.3,LWalpha=-5.528,LWbeta=3.273)

# Estimate yield with fixed parameters
Res_1 <- yprBH_slot_func(recruitmentTL=200,lowerSL=250,upperSL=325,
                       cfunder=0.25,cfin=0.6,cfabove=0.15,cm=0.4,
                       loi=c(200,250,300,325,350),lhparms=LH)
Res_1