Help for package openMSE

Title:

Easily Install and Load the 'openMSE' Packages

Version:

1.0.1

Description:

The 'openMSE' package is designed for building operating models, doing simulation modelling and management strategy evaluation for fisheries. 'openMSE' is an umbrella package for the 'MSEtool' (Management Strategy Evaluation toolkit), 'DLMtool' (Data-Limited Methods toolkit), and SAMtool (Stock Assessment Methods toolkit) packages. By loading and installing 'openMSE', users have access to the full functionality contained within these packages. Learn more about 'openMSE' at https://openmse.com/.

License:

GPL-3

URL:

https://openmse.com/, https://github.com/Blue-Matter/openMSE, https://openMSE.openMSE.com

BugReports:

https://github.com/Blue-Matter/openMSE/issues

Encoding:

UTF-8

LazyData:

true

RoxygenNote:

7.3.2

Depends:

R (≥ 4.0.0), MSEtool (≥ 3.7.0), DLMtool (≥ 6.0.0), SAMtool

Imports:

crayon, dplyr, purrr, ggplot2, grid, tidyr

NeedsCompilation:

Packaged:

2024-09-24 16:17:35 UTC; User

Author:

Adrian Hordyk

[aut, cre], Quang Huynh [aut], Tom Carruthers [aut]

Maintainer:

Adrian Hordyk <adrian@bluematterscience.com>

Repository:

CRAN

Date/Publication:

2024-09-24 16:30:02 UTC

At-Age Time Series Variables

Description

At-Age Time Series Variables

Usage

At_Age_TS_Variables

Format

An object of class data.frame with 6 rows and 3 columns.

Time Series Variables

Description

Time Series Variables

Usage

TS_Variables

Format

An object of class data.frame with 21 rows and 3 columns.

Run an example MSE

Description

Run an example MSE using three data-limited management procedures from DLMtool and one stock assessment model from SAMtool.

Usage

demo()

Details

The MSE is run and three example performance metrics plots are produced: a trade-off plot, a projection plot, and a Kobe plot.

An MSE about is invisibly returned, and can be explored further (e.g., summary(MSE)).

Value

Invisibly returns an MSE object, and produces example plots of performance metrics.

Examples


MSE <- demo()

Create a data.frame with estimated values from a `SAMtool` assessment method used in an MSE

Description

Create a data.frame with estimated values from a SAMtool assessment method used in an MSE

Usage

get_Assess_Estimates(x, model = "Model 1")

## S3 method for class 'MSE'
get_Assess_Estimates(x, model = "Model 1")

## S3 method for class 'list'
get_Assess_Estimates(x, model = NULL)

## S3 method for class 'MMSE'
get_Assess_Estimates(x, model = NULL)

Arguments

x

An object of class MSE or a list of MSE objects, where MSE includes management procedures that use SAMtool stock assessment functions that return estimated values in MSE@PPD.

model

An optional name for the model. If x is a list of objects, model will be taken from names(x). If names(x) is NULL, model will be given sequential numerical values (e.g., ⁠Model 1⁠, ⁠Model 2⁠, ...)

Value

A data.frame with columns:

`Year_assess`	The year the assessment was run in the MSE
`Year_est`	The year corresponding with the estimated value
`Variable`	The estimated variable
`Value`	The estimated value
`MP`	The name of the management procedure
`Simulation`	The simulation number
`Model`	The name of model

Get Life History Parameters

Description

Extracts the life-history parameters: Linf, K, L50, and ageM

Usage

get_LifeHistory(x, model = "Model 1", ...)

## S3 method for class 'Hist'
get_LifeHistory(x, model = "Model 1", ...)

## S3 method for class 'list'
get_LifeHistory(x, model = "Model 1", ...)

## S3 method for class 'MSE'
get_LifeHistory(x, model = "Model 1", ...)

## S3 method for class 'MMSE'
get_LifeHistory(x, model = "Model 1", ...)

Arguments

x

An object of class Hist, MSE, or a list of Hist or MSE objects

model

...

additiona arguments (not used)

Value

A data.frame

Extract the meta-data from a `Hist` or `MSE` object

Description

Extract the meta-data from a Hist or MSE object

Usage

get_Metadata(x)

## S3 method for class 'Hist'
get_Metadata(x)

## S3 method for class 'MSE'
get_Metadata(x)

## S3 method for class 'list'
get_Metadata(x)

## S3 method for class 'MMSE'
get_Metadata(x)

Arguments

x

An object of class Hist, MSE, or a list of Hist or MSE objects

Details

If x is a list of objects, each object must have identical structure, i.e., same number of simulations, same number of age-classes, historical and projection years, management procedures, etc

Value

A named list with elements:

`nsim`	The number of simulations
`nage`	The number of age classes
`Ages`	The age classes
`nyear`	The number of historical years
`Hist.Years`	A data.frame with the historical years in the `Year` column
`proyears`	The number of projection years
`Pro.Years`	A data.frame with the projection years in the `Year` column
`All.Years`	A data.frame with the historical and the projection years in the `Year` column
`nMPs`	The number of MPs (if `x` is an object of class `MSE`)
`MPs`	The MPs (if `x` is an object of class `MSE`)

Create a data.frame with Historical and Projection years

Description

Create a data.frame with Historical and Projection years

Usage

get_Years(x)

## S3 method for class 'MSE'
get_Years(x)

## S3 method for class 'MMSE'
get_Years(x)

## S3 method for class 'Hist'
get_Years(x)

## S3 method for class 'multiHist'
get_Years(x)

Arguments

x

An object of class Hist, MSE, or a list of Hist or MSE objects

Value

A data.frame with years and period (Historical or Projection)

Create a data.frame with at-age schedules by simulation and year

Description

Note that the Selectivity and Retention curves in these plots are from the operating model. If an MP changes the selectivity/retention, this is not shown in these plots.

Usage

get_at_Age(x, model = "Model 1", ...)

## S3 method for class 'Hist'
get_at_Age(x, model = "Model 1", ...)

## S3 method for class 'list'
get_at_Age(x, model = "Model 1", ...)

## S3 method for class 'MSE'
get_at_Age(x, model = "Model 1", ...)

## S3 method for class 'multiHist'
get_at_Age(x, model = "Model 1", ...)

## S3 method for class 'MMSE'
get_at_Age(x, model = "Model 1", ...)

Arguments

x

An object of class Hist, MSE, or a list of Hist or MSE objects

model

...

additional arguments

Value

A data.frame

Create a data.frame with at-length selectivity and retention schedules by simulation and year

Description

Note that the Selectivity and Retention curves in these plots are from the operating model. If an MP changes the selectivity/retention, this is not shown in these plots.

Usage

get_at_Length(x, model = "Model 1", ...)

## S3 method for class 'multiHist'
get_at_Length(x, model = "Model 1", ...)

Arguments

x

An object of class Hist, MSE, or a list of Hist or MSE objects

model

...

additional arguments

Value

A data.frame

Create a data.frame with time-series information by simulation and year

Description

Create a data.frame with time-series information by simulation and year

Usage

get_at_age_ts(
  x,
  variable = "Spawning Biomass",
  model = "Model 1",
  scale = NULL
)

Arguments

x

An object of class Hist, MSE, or a list of Hist or MSE objects

variable

A character string with a valid name for a time-series variable. Use valid_ts_variables() for valid variable names.

model

scale

An optional function with a single numeric argument that returns transformed or scaled numeric values. See lb2kg and kg2lb for example. Can be a list of functions for list objects (NA for no transformation)

Create a data.frame with time-series information by simulation and year

Description

Create a data.frame with time-series information by simulation and year

Usage

get_ts(x, variable = "Spawning Biomass", model = "Model 1", scale = NULL)

valid_ts_variables()

valid_at_age_ts_variables()

## S3 method for class 'Hist'
get_ts(x, variable = "Spawning Biomass", model = "Model 1", scale = NULL)

## S3 method for class 'MSE'
get_ts(x, variable = "Spawning Biomass", model = "Model 1", scale = NULL)

## S3 method for class 'list'
get_ts(x, variable = "Spawning Biomass", model = "Model 1", scale = NULL)

## S3 method for class 'multiHist'
get_ts(x, variable = "Spawning Biomass", model = "Model 1", scale = NULL)

## S3 method for class 'MMSE'
get_ts(x, variable = "Spawning Biomass", model = "Model 1", scale = NULL)

get_Biomass(x, model = "Model 1", ...)

get_Landings(x, model = "Model 1", ...)

get_Removals(x, model = "Model 1", ...)

get_Recruits(x, model = "Model 1", ...)

get_SSB(x, model = "Model 1", ...)

get_SB_SBMSY(x, model = "Model 1", ...)

get_F(x, model = "Model 1", ...)

get_Biomass_at_Age(x, model = "Model 1", ...)

get_Number_at_Age(x, model = "Model 1", ...)

get_SSB_at_Age(x, model = "Model 1", ...)

Arguments

x

An object of class Hist, MSE, or a list of Hist or MSE objects

variable

A character string with a valid name for a time-series variable. Use valid_ts_variables() for valid variable names.

model

scale

...

named arguments passed to get_ts

Convert numeric values to a different scale

Description

Convert numeric values to a different scale

Usage

lb2kg(x)

lb2mt(x)

kg2lb(x)

kg2_1000lb(x)

kg2mt(x)

inch2mm(x)

inch2cm(x)

mm2inch(x)

cm2inch(x)

divide_1000(x)

divide_100(x)

divide_10(x)

multiply_1000(x)

multiply_100(x)

multiply_10(x)

Arguments

x

A vector of numeric values

Value

The vector of numeric values converted to the appropriate scale

Functions

lb2kg(): Convert from pounds to kilograms
lb2mt(): Convert from pounds to metric tons
kg2lb(): Convert from kilograms to pounds
kg2_1000lb(): Convert from kilograms to 1000 pounds
kg2mt(): Convert from kilograms to metric tons
inch2mm(): Convert from inches to millimeters
inch2cm(): Convert from inches to centimeters
mm2inch(): Convert from millimeters to inches
cm2inch(): Convert from centimeters to inches
divide_1000(): Divide values by 1000
divide_100(): Divide values by 100
divide_10(): Divide values by 10
multiply_1000(): Multiply values by 1000
multiply_100(): Multiply values by 100
multiply_10(): Multiply values by 10

Examples

lb2kg(1:10)
kg2lb(1:10)

Plots the median and quantiles of a time-series

Description

Plots the median and quantiles of a time-series

Usage

plot_TS(
  x,
  xlab = "Year",
  ylab = "Spawning Biomass",
  title = "",
  quantiles = c(0.025, 0.975),
  scale = NULL,
  alpha = 0.1,
  lwd = 1,
  use_theme = NULL,
  colpalette = "Dark2",
  facet = TRUE,
  inc.Legend = !facet,
  inc.Hist = FALSE,
  print = TRUE,
  get_function = get_SSB,
  years = NULL,
  ...
)

plot_SSB(x, ...)

plot_Biomass(x, ylab = "Biomass", ...)

plot_Landings(x, ylab = "Landings", ...)

plot_Removals(x, ylab = "Removals", ...)

plot_Recruits(x, ylab = "Recruits", ...)

plot_F(x, ylab = "Fishing Mortality (F)", ...)

plot_LifeHistory(
  x,
  xlab = "Year",
  ylab = "Median (quantiles)",
  title = "",
  quantiles = c(0.025, 0.975),
  scale = NULL,
  alpha = 0.1,
  lwd = 1,
  use_theme = NULL,
  colpalette = "Dark2",
  facet = TRUE,
  inc.Legend = !facet,
  inc.Hist = FALSE,
  print = TRUE
)

Arguments

x

An object of class Hist, MSE, or a list of Hist or MSE objects

xlab

X-axis label (default 'Year')

ylab

Y-axes label

title

Optional title

quantiles

Lower and upper quantiles to calculate. Numeric vector of length 2.

scale

alpha

Transparency parameter

lwd

Line width

use_theme

Optional ggplot theme

colpalette

Color palette from RColorBrewer

facet

Logical. Facet the plot?

inc.Legend

Logical. Include legend?

inc.Hist

Logical. For MSE results, include the historical period?

print

Logical. Print the plot?

get_function

get_ function to extract time-series information from x

years

Optional numeric vector specifying the years to plot. Default is all years.

...

Named arguments passed to plot_TS

Value

A named list with:

`p`	The `ggplot` object
`df`	Data.frame with the summary statistics (median and quantiles)

Functions

plot_SSB(): Plot the Spawning Biomass
plot_Biomass(): Plot the Total Biomass
plot_Landings(): Plot the Landings (biomass)
plot_Removals(): Plot the Removals (biomass)
plot_Recruits(): Plot the Recruits (numbers)
plot_F(): Plot the Recruits (numbers)
plot_LifeHistory(): Plot the Life-History parameters

Plot at-Age schedules

Description

Plots Length, Weight, Maturity, Natural-Mortality, Selectivity, and Retention-at-Age schedules.

Usage

plot_at_Age(
  x,
  quantiles = c(0.025, 0.975),
  scale = NULL,
  variable = "Length",
  xlab = "Age (Year)",
  ylab = NULL,
  title = "",
  years = NULL,
  alpha = 0.1,
  lwd = 1,
  use_theme = NULL,
  colpalette = "Dark2",
  print = TRUE
)

plot_Length(x, ...)

plot_Weight(x, ...)

plot_Maturity(x, ...)

plot_N.Mortality(x, ...)

plot_Select(x, ...)

plot_Retention(x, ...)

plot_Select_Maturity(x, ...)

Arguments

x

An object of class Hist, MSE, or a list of Hist or MSE objects

quantiles

Lower and upper quantiles to calculate. Numeric vector of length 2.

scale

variable

String. One of 'Length', 'Weight', 'N.Mortality','Maturity', 'Select', 'Retention'

xlab

X-axis label (default 'Age (Year)')

ylab

Y-axes label

title

Optional title

years

Optional numeric vector specifying the years to plot. Default is the first and last historical year, and the last projection year

alpha

Transparency parameter

lwd

Line width

use_theme

Optional ggplot theme

colpalette

Color palette from RColorBrewer

print

Logical. Print the plot?

...

Named arguments passed to plot_at_Age

Details

Note that the Selectivity and Retention curves in these plots are from the operating model. If an MP changes the selectivity/retention, this is not shown in these plots.

Value

A named list with:

`p`	The `ggplot` object
`df`	Data.frame with the summary statistics (median and quantiles)

Functions

plot_Length(): Plot Length-at-Age
plot_Weight(): Plot Weight-at-Age
plot_Maturity(): Plot Maturity-at-Age
plot_N.Mortality(): Plot N.Mortality-at-Age
plot_Select(): Plot Selectivity-at-Age
plot_Retention(): Plot Retention -at-Age
plot_Select_Maturity(): Plot Selectivity-, Retention-, and Maturity-at-Age

A ggplot2 theme

Description

A simple theme for ggplot2 that loosely resembles nicely themed plots from base graphics.

Usage

theme_default(
  base_size = 11,
  base_family = "",
  text_col = "grey20",
  panel_border_col = "grey70"
)

Arguments

base_size

Base font size.

base_family

Base font family.

text_col

Color for text.

panel_border_col

Color for panel borders.

Examples

p <- ggplot2::ggplot(mtcars) +
  ggplot2::geom_point(ggplot2::aes(x = wt, y = mpg, colour = factor(gear))) +
  ggplot2::facet_wrap(~am)
p + theme_default()

Open the openMSE Documentation website

Description

Opens the openMSE Documentation website (requires internet connection)

Usage

userguide()

Value

Nothing is returned. Opens the 'openMSE.com' in the web browser

Examples

userguide()

At-Age Time Series Variables

Description

Usage

Format

Time Series Variables

Description

Usage

Format

Run an example MSE

Description

Usage

Details

Value

Examples

Create a data.frame with estimated values from a SAMtool assessment method used in an MSE

Description

Usage

Arguments

Value

Get Life History Parameters

Description

Usage

Arguments

Value

Extract the meta-data from a Hist or MSE object

Description

Usage

Arguments

Details

Value

Create a data.frame with Historical and Projection years

Description

Usage

Arguments

Value

Create a data.frame with at-age schedules by simulation and year

Description

Usage

Arguments

Value

Create a data.frame with at-length selectivity and retention schedules by simulation and year

Description

Usage

Arguments

Value

Create a data.frame with time-series information by simulation and year

Description

Usage

Arguments

Create a data.frame with time-series information by simulation and year

Description

Usage

Arguments

Convert numeric values to a different scale

Description

Usage

Arguments

Value

Functions

Examples

Plots the median and quantiles of a time-series

Description

Usage

Arguments

Value

Functions

Plot at-Age schedules

Description

Usage

Arguments

Details

Value

Functions

A ggplot2 theme

Description

Usage

Arguments

Examples

Open the openMSE Documentation website

Description

Create a data.frame with estimated values from a `SAMtool` assessment method used in an MSE

Extract the meta-data from a `Hist` or `MSE` object