Unlimited learning, half price | 50% off
Get 50% off unlimited learning

⚠️There's a newer version (1.0.3) of this package.Take me there.

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

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

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:

library("ss3sim")

You can read the help files with:

?ss3sim

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

browseVignettes("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:

  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.

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

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. http://dx.doi.org/10.1016/j.fishres.2016.06.018. (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. 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"):

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.
  http://doi.org/10.1371/journal.pone.0092725.

toBibtex(citation("ss3sim"))
@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 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},
}

@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},
}

Copy Link

Version

Install

install.packages('ss3sim')

Monthly Downloads

520

Version

0.9.5

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Maintainer

Sean Anderson

Last Published

April 19th, 2017

Functions in ss3sim (0.9.5)

add_nulls

Add NULL values to non-existent list elements
bias_ss3

Perform a single bias adjustment run
change_index

(Depreciated) Sample the biomass with observation error
change_e

Methods to alter which parameters are estimated in a SS3 .ctl file.
change_em_binning

Change population and observed length composition bins in an SS estimation model
get_args

Take a csv file, read it, and turn the first column into the list names and the second column into the list values.
change_lcomp

(Depreciated) Sample length compositions from expected values
change_tail_compression

Replace tail compression value for length composition data.
change_tv

Methods to include time-varying parameters in an SS3 operating model
case_index

Write a case file for index data to the disk.
get_bin

Get SS3 binary/executable location in package
profile_fmsy

Determine Fmsy for a given operating model
rename_ss3_files

Rename SS3-version-specific files
sample_lcomp

Sample length compositions from expected values
sample_mlacomp

[BETA VERSION] Sample mean length (size-)-at-age data and write to file for use by the EM.
standardize_bounds

Standardize the bounds of the estimation model control file.
get_sigmar

Get recruitment deviation sigma
id_scenarios

Identify ss3sim scenarios within a directory
plot_scalar_points

Plot scalar values as points.
case_tv

Write time varying casefiles to the disk
change_lcomp_constant

Set the robustification constant for length composition data.
change_maturity

Alter a control file to specify the SS3 maturity option
calculate_runtime

Calculate run time
substr_r

Substring from right
plot_ts_boxplot

Plot timeseries values as boxplots.
sample_wtatage

Sample empirial weight-at-age data and write to file for use by the EM
sanitize_admb_options

Check admb options to make sure there aren't flags there shouldn't be
calculate_data_units

Given sampling arguments, calculate super set of fleets, years, and data types.
calculate_re

Calculate relative error
case_fishing

Write a case file for fishing data to the disk.
change_agecomp

(Depreciated) Sample age compositions from expected values
change_data

Change the data that is available as output from an SS operating model.
change_rec_devs

Replace recruitment deviations
case_deparse

Turn an argument describing an object into a character.
change_year

Methods to change the years in an ss3sim model
check_data

Check that the SS3 data file looks correct
get_bin_info

Get the parameter values for change_bin
change_retro

Alter a starter file for a retrospective analysis
get_caseval

Take a scenario ID and a case type and return the case number
get_fish600_casefolder

Get the folder location of the FISH600 case files
case_comp

Write a case file for length- or age-composition data
clean_data

Given sampling arguments remove ("clean") all data in a .dat file that is not specified
cleanup_ss3

Clean up after an SS3 run
expand_scenarios

Create vectors of scenario IDs
extract_expected_data

Extract the expected data values
get_model_folder

Get the folder location of an included SS3 model configuration
get_results_derived

Extract time series from a model run with the associated standard deviation.
get_results_scalar

Extract scalar quantities from a model run.
ss3sim

ss3sim: Fisheries stock assessment simulation testing with Stock Synthesis
ss3sim_base

Base wrapper function to run an ss3sim simulation
get_caseargs

Take a scenario ID and return argument lists
get_recdevs

Return a set of recruitment deviations
get_results_all

Extract SS3 simulation output
plot_ts_lines

Plot timeseries values as lines.
plot_ts_points

Plot timeseries values as points.
run_ss3sim

Master function to run SS3 simulations
sample_agecomp

Sample age compositions from expected values
verify_input

Verify and standardize SS3 input files
verify_plot_arguments

A helper function to check the correct input for the plotting functions.
get_nll_components

Get negative log likelihood (NLL) values from a report file list
pastef

Paste with "/" as the separator
plot_scalar_boxplot

Print scalar values as boxplots.
change_f

Alter the fishing mortality (F) values in an SS3 .par file.
change_fltname

Standardize column name for FltSvy in event r4ss is not the newest version.
copy_ss3models

Copy the operating and estimation models and create a folder structure
sample_calcomp

Sample conditional age-at-length (CAL) data and write to file for use by the EM.
sample_index

Sample the biomass with observation error
create_argfiles

Create template argument input files
facet_form

A helper function for building a ggplot facet. Used internally by the plotting functions.
fill_across

Fill in matrix across rows of weight-at-age data by interpolation
get_results_scenario

Extract SS3 simulation results for one scenario.
get_results_timeseries

Extract time series from a model run.
run_bias_ss3

Determine level of bias adjustment for SS3 runs
run_ss3model

Run an operating or estimation model for a specified set of scenario IDs
scalar_dat

Example scalar data from the ss3sim vignette
setup_parallel

Setup parallel processing
ts_dat

Example time series data from the ss3sim vignette
vbgf_func

Predict length given VBGF parameters