Fisheries Stock Assessment Simulation Testing with Stock Synthesis

Develops a framework for fisheries stock assessment simulation testing with Stock Synthesis (SS) as described in Anderson et al. (2014) .

Build Status AppVeyor Build Status CRAN_Status_Badge

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.


Installing the ss3sim R package

Install the CRAN version of ss3sim with:


Or, install the development version from GitHub:

devtools::install_github("ss3sim/ss3sim") # without vignettes (faster)
devtools::install_github("ss3sim/ss3sim", build_vignettes = TRUE) # with vignettes

We'd suggest using the GitHub version since it comes with SS3 executables/binaries. 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") for more details.

If you would like to run simulations in parallel, then also run:

install.packages(c("doParallel", "foreach"))

You can then load ss3sim with:


You can read the help files with:


and access the vignettes for reproducible examples of ss3sim simulations with:


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:

  1. a base model of the underlying truth (an SS3 operating model)
  2. a base model of how you will assess that truth (an SS3 estimation model),
  3. 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.

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 SS 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

An example of ss3sim 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 (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

Stewart, I.J., C.C. Monnahan. 2016. Implications of process error in selectivity for approaches to weighting compositional data in fisheries stock assessments. Fisheries Research. In press. (code repository).

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. (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. (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 (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 (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

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. (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. (PDF).

Citing ss3sim

If you use ss3sim in a publication, please cite ss3sim as shown by citation("ss3sim"):

To cite ss3sim in publications use:
  Anderson, SC, Monnahan, CC, Johnson, KF, Ono, K, Valero, JL,
  Cunningham, CJ, Hurtado-Ferro, F, Kuriyama, P, Licandeo, R,
  McGilliard, CR, Rudd, M, Stawitz, CC, Szuwalski, CS, Taylor, IG,
  Vert-pre, KA, and Whitten, AR (2016). ss3sim: Fisheries Stock
  Assessment Simulation Testing with Stock Synthesis. R package
  version 0.9.3.
  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.
  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 Christine C. Stawitz 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.3},
  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},


ss3sim 0.9.5

  • Adds citation to Description field

ss3sim 0.9.4

  • Fix compatibility with dplyr 0.6.0
  • Fix issue with SS3 binary in development version #239

ss3sim 0.9.3

  • Fix LICENSE for CRAN
  • Update author list
  • Incorporate @cstawitz's additions to the making-models vignette
  • Fixes to executable locating for Windows

ss3sim 0.9.2

  • Revise package description

ss3sim 0.9.1

  • Fix compatibility with dplyr

ss3sim 0.9.0

  • Fix compatibility of vignette with ggplot2 2.0.0.

  • Add new data types: conditional age at length, mean length at age, and empirical weight at age.

  • sample_agecomp and sample_lcomp now take new effective sample size (ESS) argument as inputs, so the user can weight the composition data as desired.

  • Add functions to estimate von Bertalanffy growth. These are used internally by change_e().

  • Add change_maturity() to alter the SS3 maturity option

  • Check that fleet name in the data frame matches the newest SS3 version (see change_fltname())

  • Add change_data(), which prepares the OM .dat files to have the correct data used for sampling that scenario. It also can manipulate length bin widths, the SS3 robustification constant, and the SS3 tail compression value. It takes care of calling the new change_tail_compression() and change_lcomp_constant() functions.

  • Add calculate_re() to calculate relative errors on the result data frames.

  • Add internal checking of the validity of SS3 .dat files (#203)

  • The get_results function now returns run time, a list of parameters that were on bounds, and recruitment deviations.

  • Switch vignette to R Markdown and HTML ouput (#194)

  • Add re-binning within the estimation model of length and conditional age-at-length data (#201, #205)

  • Add Kelli's profile_fmsy() function (#173)

  • Merrill added parallel processing option to the get results functions (#171)

  • Added parallel iterations processing option (#168)

  • Function argument descriptions now indicate which ones need to be specified in case files with an asterisk (#161).

  • Merrill updated the get-results functions to work without bias runs, to check for folders that look like ss3sim runs, and to issue a warning if there are problems reading the files (#155).

  • Copy wtatage.ss_new from OM to EM (#163).

  • Add Travis CI testing of the package

  • Added much more extensive testing of the package in the root tests folder. This is for internal testing only and not bundled with the package (#156).

  • Allow for missing arguments in case files. This allows us to add new arguments to existing functions without breaking old code. A missing argument gets passed as NULL via the add_nulls() function (within #148).

  • Re-write case file parsing to be more robust and allow for scientific notations (#157).

  • Add the option to use the optimized SS executables (#138 and #147) and ability to have spaces in the path name to the executable.

  • Add Cole Monnahan's ss3sim plotting functions (#134).

  • change_lcomp, change_agecomp, and change_index are now sample_lcomp, sample_agecomp, and sample_index. The old functions point to the new functions with warnings that they are depreciated. Existing code should continue to work (#145).

  • ss3sim now requires the SS3 binary to be named according to the version (#138 and #147).

  • Bump required version of r4ss to 1.22.1 since 1.22.0 did not export functions that ss3sim needs.

  • ss3sim now requires R 3.1.0 since we cannot easily test on earlier versions.

ss3sim 0.8.2

New features

  • Added ability to pass seed value to get_recdevs() (#125).

  • Added dimension check of user_recdevs to ensure recruitment deviations are supplied for all iterations (#130).

  • Vignette now uses a custom Solarized colour theme.

Bug fixes

  • Moved vignette data files to the data folder so they are user-accessible after installing the package (#126).

  • Updated out-dated paper citations. All papers are now accepted.

  • Removed multi-core code in vignette for CRAN checks.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


1.0.3 by Kelli F. Johnson, 2 years ago

Report a bug at

Browse source code at

Authors: Kelli F. Johnson [aut, cre] , Sean C. Anderson [aut] , Kathryn Doering [aut] , Cole Monnahan [aut] , Christine Stawitz [aut] , Ian Taylor [aut] , Curry Cunningham [ctb] , Allan Hicks [ctb] , Felipe Hurtado-Ferro [ctb] , Peter Kuriyama [ctb] , Roberto Licandeo [ctb] , Carey McGilliard [ctb] , Melissa Murdian [ctb] , Kotaro Ono [ctb] , Merrill Rudd [ctb] , Cody Szuwalski [ctb] , Juan Valero [ctb] , Athol Whitten [ctb]

Documentation:   PDF Manual  

MIT + file LICENSE license

Imports foreach, r4ss, gtools, ggplot2, bbmle, grDevices, graphics, stats, utils

Suggests knitr, doParallel, rmarkdown

See at CRAN