ss3sim

• Badges
• Installation
• The ss3sim simulation setup
• How ss3sim works
• Example output from an ss3sim simulation
• Citing ss3sim
• Contributing to ss3sim
• Code of conduct

Badges

main:

ss3sim is an R package that simplifies the steps needed to generate beautiful simulation output from the widely-used Stock Synthesis (SS3) statistical age-structured stock assessment framework. To learn more, read on or check out the vignettes.

Installation

Install the CRAN version of ss3sim with:

install.packages("ss3sim")

Or, install the development version from GitHub:

# install.packages("devtools")
devtools::install_github(
  "ss3sim/ss3sim",
  ref = "main",
  build_vignettes = TRUE, dependencies = TRUE
)
library(ss3sim)

A note: As of April 9, 2021, use of parallel master and development branches in the GitHub ss3sim repository has ended. The default branch is now called main, and feature branches will be used for new development. Once tested, feature branches should be merged into main. See issue #305 for more details.

We suggest using the GitHub version because it comes with the SS3 executable/binary. If you are using the CRAN version, you will need to install the binary and place it in your system path. See the Introduction vignette for more details on how to get the latest version of SS3 and place it in your path.

You can read the help files and access the vignettes for reproducible examples of ss3sim simulations with

?ss3sim
browseVignettes("ss3sim")
vignette("introduction", "ss3sim")

The ss3sim simulation setup

An ss3sim simulation requires three types of input:

1. a base model of the underlying truth (an SS3 operating model; OM),
2. a base model of how you will assess that truth (an SS3 estimation model; EM), and
3. a data frame specifying how you want to manipulate (1) and (2) from their base-model configurations.

You can find examples of an SS3 OM and EM within the package data. An example data frame for (3) is also available within the package via ss3sim::setup_scenarios_defaults(). Adding columns to this default scenario data frame will enable the manipulation of additional components of the OM, sampling procedure, and the EM. Adding rows to this default scenario data frame will lead to more scenarios, where a scenario is the result of the combination of specifications in that row, i.e., how you manipulate the OM and the EM. There will be many folders inside each scenario folder, where each of these folders are iterations. Iterations within a scenario differ only by the seed used within R to define the randomness of that iteration.

An illustration of the input and output file and folder structure.

How ss3sim works

ss3sim works by converting simulation arguments (e.g., a given natural mortality trajectory) into manipulations of SS3 configuration files. It takes care of running the operating and estimation models as well as making these manipulations at the appropriate stage in the simulation.

ss3sim functions are divided into three types:

1. change and sample functions that manipulate SS3 configuration files. These manipulations generate an underlying "truth" (operating models) and control our assessment of those models (estimation models).

2. run functions that conduct simulations. These functions generate a folder structure, call manipulation functions, run SS3 as needed, and save the output.

3. get functions for synthesizing the output.

Example output from an ss3sim simulation

This example shows a crossed simulation in which we considered (1) the effect of fixing natural mortality (M) at its true value from the OM (0.2; case E0) or estimating M (case E1) and (2) the effect of high survey effort (sigma_survey = 0.1; case D0) or low survey effort (sigma_survey = 0.4; case D1). Upper panels (blue) show time series of relative error in spawning stock biomass (SSB). Lower panels (gray) show the distribution of relative error across four scalar variables: depletion, M, SSB at maximum sustainable yield (SSB_MSY), and fishing mortality (F) in the terminal year. We show the values across simulation iterations with dots and the distributions with beanplots (kernel density smoothers).

Citing ss3sim

If you use ss3sim in a publication, please cite ss3sim as shown by

citation("ss3sim")
toBibtex(citation("ss3sim"))

and add your publication to the list of publications in the wiki.

Contributing to ss3sim

Interested in contributing to ss3sim? We recognize contributions come in many forms, including but not limited to code, reporting issues, creating examples and/or documentation.

We strive to follow the NMFS Fisheries Toolbox Contribution Guide. We also have included ss3sim-specific code contribution information in the Developers page of the ss3sim wiki. Note that these are guidelines, not rules, and we are open to collaborations in other ways that may work better for you. Please feel free to reach out to us by opening an issue in this repository or by emailing the maintainer (call maintainer("ss3sim") in R to view the current maintainer's name and email address).

Note that contributors are expected to uphold the code of conduct.

Code of conduct

This project and everyone participating in it is governed by the NMFS Fisheries Toolbox Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected]. Note that the maintainers of ss3sim do not have access to this email account, so unacceptable behavior of maintainers can also be reported here.

The NFMS Fisheries Toolbox Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq

Disclaimer

"The United States Department of Commerce (DOC) GitHub project code is provided on an 'as is' basis and the user assumes responsibility for its use. DOC has relinquished control of the information and no longer has responsibility to protect the integrity, confidentiality, or availability of the information. Any claims against the Department of Commerce stemming from the use of its GitHub project will be governed by all applicable Federal law. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by the Department of Commerce. The Department of Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used in any manner to imply endorsement of any commercial product or activity by DOC or the United States Government."

U.S. Department of Commerce | National Oceanographic and Atmospheric Administration | NOAA Fisheries