ss3sim
ss3sim is an R package that facilitates flexible, rapid, and reproducible fisheries stock assessment simulation testing with the widely-used Stock Synthesis 3 (SS3) statistical age-structured stock assessment framework.
Contents
- Installing the ss3sim R package
- The ss3sim simulation setup
- How ss3sim works
- Example output from an ss3sim simulation
- Papers published using ss3sim
- Citing ss3sim
Installing the ss3sim R package
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") # without vignettes (faster)
devtools::install_github("ss3sim/ss3sim", build_vignettes = TRUE) # with vignettes
There has been substantial work on the GitHub version since the latest CRAN release, so we'd suggest using the GitHub version.
If you would like to run simulations in parallel, then also run:
install.packages(c("doParallel", "foreach"))
You can then load ss3sim with:
library("ss3sim")
You can read the help files with:
?ss3sim
and access the vignettes for reproducible examples of ss3sim simulations with:
browseVignettes("ss3sim")
If you're using the GitHub version of ss3sim then the SS3 executables/binaries are included in the package and your installation is complete. If you're using the CRAN version, you'll need to install these binaries and place them in your system path. ss3sim requires a specific version of the SS3 binary/executable. With the permission of Rick Methot, we have hosted those files here. See the Introduction vignette with vignette("introduction", "ss3sim")
.
In addition to the vignette, we published a paper in PLOS ONE, which describes the package.
The ss3sim simulation setup
An ss3sim simulation requires three types of input:
- a base model of the underlying truth (an SS3 operating model)
- a base model of how you will assess that truth (an SS3 estimation model),
- a set of cases that deviate from these base models that you want to compare (configuration arguments provided as plain-text control files).
You can find examples of these SS3 operating and estimation models within the package data. Plain-text case files for some current simulation projects run by the developers of the package are also available along with the case files for the examples used in the paper and vignette.
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:
-
change
andsample
functions that manipulate SS configuration files. These manipulations generate an underlying "truth" (operating models) and control our assessment of those models (estimation models). -
run
functions that conduct simulations. These functions generate a folder structure, call manipulation functions, run SS3 as needed, and save the output. -
get
functions for synthesizing the output.
Example output from an ss3sim simulation
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 (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 (grey) 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).
Papers published using ss3sim
Johnson, K.F., E. Councill, J.T. Thorson, E. Brooks, R.D. Methot, and A.E. Punt. 2016. Can autocorrelated recruitment be estimated using integrated assessment models and how does it affect population forecasts? Fisheries Research 183:222–232. http://doi.org/10.1016/j.fishres.2016.06.004. (code repository).
Kuriyama, P. T., K. Ono, F. Hurtado-Ferro, A. C. Hicks, I. G. Taylor, R. R. Licandeo, K. F. Johnson, S. C. Anderson, C. C. Monnahan, M. B. Rudd, C. C. Stawitz, and J. L. Valero. 2016. An empirical weight-at-age approach reduces estimation bias compared to modeling parametric growth in integrated, statistical stock assessment models when growth is time varying. Fisheries Research. 180:119–127. http://doi.org/10.1016/j.fishres.2015.09.007. (code repository).
Monnahan, C. C., K. Ono, S. C. Anderson, M. B. Rudd, A. C. Hicks, F. Hurtado-Ferro, K. F. Johnson, P. T. Kuriyama, R. R. Licandeo, C. C. Stawitz, I. G. Taylor, and J. L. Valero. 2016. The effect of length bin width on growth estimation in integrated age-structured stock assessments. Fisheries Research. 180:103–112 http://doi.org/10.1016%2Fj.fishres.2015.11.002. (code repository).
Johnson, K.F., C.C. Monnahan, C.R. McGilliard, K.A. Vert-pre, S.C. Anderson, C.J. Cunningham, F. Hurtado-Ferro, R.R. Licandeo, M.L. Muradian, K. Ono, C.S. Szuwalski, J.L. Valero, A.R. Whitten, A.E. Punt. 2015. Time-varying natural mortality in fisheries stock assessment models: identifying a default approach. 2015. ICES Journal of Marine Science 72 (1): 137-150 http://doi.org/10.1093/icesjms/fsu055. (PDF; code repository).
Hurtado-Ferro, F., C.S. Szuwalski, J.L. Valero, S.C. Anderson, C.J. Cunningham, K.F. Johnson, R.R. Licandeo, C.R. McGilliard, C.C. Monahan, M.L. Muradian, K. Ono, K.A. Vert-Pre, A.R. Whitten, A.E. Punt. 2015. Looking in the rear-view mirror: bias and retrospective patterns in integrated, age-structured stock assessment models. ICES Journal of Marine Science. 72 (1): 99-110 http://doi.org/10.1093/icesjms/fsu198.
Ono, K., R. Licandeo, M.L. Muradian, C.J. Cunningham, S.C. Anderson, F. Hurtado-Ferro, K.F. Johnson, C.R. McGilliard, C.C. Monnahan, C.S. Szuwalski, J.L. Valero, K.A. Vert-pre, A.R. Whitten, A.E. Punt. 2015. The importance of length and age composition data in statistical catch-at-age models for marine species. ICES Journal of Marine Science. 72 (1): 31-43. http://doi.org/10.1093/icesjms/fsu007 (PDF).
Anderson, S.C., C.C. Monnahan, K.F. Johnson, K. Ono, J.L. Valero. ss3sim: An R package for fisheries stock assessment simulation with Stock Synthesis. 2014. PLOS ONE. 9(4): e92725. http://doi.org/10.1371/journal.pone.0092725 (PDF).
Citing ss3sim
If you use ss3sim in a publication, please cite ss3sim as shown by citation("ss3sim")
:
Anderson, SC, Monnahan, CC, Johnson, KF, Ono, K, Valero, JL, Cunningham, CJ, Hurtado-Ferro, F, Kuriyama, P, Licandeo, R, McGilliard, CR, Rudd, M, Szuwalski, CS, Taylor, IG, Vert-pre, KA, and Whitten, AR (2015). ss3sim: Fisheries Stock Assessment Simulation Testing with Stock Synthesis. R package version 0.9.2.
Anderson, SC, Monnahan, CC, Johnson, KF, Ono, K, and Valero, JL (2014). ss3sim: An R package for fisheries stock assessment simulation with Stock Synthesis. PLOS ONE. 9(4): e92725. DOI: 10.1371/journal.pone.0092725.
@Manual{,
title = {ss3sim: Fisheries Stock Assessment Simulation Testing with Stock Synthesis},
author = {Sean C. Anderson and Cole C. Monnahan and Kelli F. Johnson and Kotaro Ono and Juan L. Valero and Curry J. Cunningham and Felipe Hurtado-Ferro and Peter Kuriyama and Roberto Licandeo and Carey R. McGilliard and Merrill Rudd and Cody S. Szuwalski and Ian G. Taylor and Katyana A. Vert-pre and Athol R. Whitten},
year = {2016},
note = {R package version 0.9.2},
}
@Article{,
title = {ss3sim: An {R} package for fisheries stock assessment simulation with {Stock Synthesis}},
author = {Sean C. Anderson and Cole C. Monnahan and Kelli F. Johnson and Kotaro Ono and Juan L. Valero},
year = {2014},
journal = {PLOS ONE},
volume = {9},
number = {4},
pages = {e92725},
doi = {10.1371/journal.pone.0092725},
}