ss3sim (version 0.9.0)

run_ss3sim: Master function to run SS3 simulations

Description

This is the main high-level wrapper function for running ss3sim simulations. This function first deals with parsing a scenario ID into case arguments, reads the appropriate case files, and then passes these arguments on to ss3sim_base to run a simulation. Alternatively, you might choose to run ss3sim_base directly and skip the case-file setup.

Usage

run_ss3sim(iterations, scenarios, case_folder, om_dir, em_dir,
  case_files = list(F = "F", D = c("index", "lcomp", "agecomp")),
  user_recdevs = NULL, parallel = FALSE, parallel_iterations = FALSE, ...)

Arguments

iterations

Which iterations to run. A numeric vector. For example 1:100.

scenarios

Which scenarios to run. A vector of character objects. For example c("D0-F0-cod", "D1-F1-cod"). Also, see expand_scenarios for a shortcut to specifying the scenarios. See

case_folder

The folder containing the plain-text case files.

om_dir

The folder containing the SS3 operating model configuration files.

em_dir

The folder containing the SS3 estimation model configuration files.

case_files

A named list that relates the case IDs to the files to return. The default list specifies only the required fishing mortality and data scenarios. To specify other cases you will need to extend this named list. This argument is passed to

user_recdevs

An optional matrix of recruitment deviations to replace the recruitment deviations built into the package. The columns represent run iterations and the rows represent years. user_recdevs can be a matrix of 0s for deterministic model checking.

parallel

A logical argument that controls whether the scenarios are run in parallel. You will need to register multiple cores first with a package such as doParallel and have the foreach package installed. See the example below.

parallel_iterations

Logical. By default parallel = TRUE will run scenarios in parallel. If you set parallel = TRUE and parallel_iterations = TRUE then the iterations will be run in parallel. This would be useful if you were only running

...

Anything else to pass to ss3sim_base. This could include bias_adjust and bias_nsim. Also, you can pass additional options to the SS3 command through the argument <

Value

• The output will appear in whatever your current Rworking directory is. There will be folders named after your scenarios. They will look like this:
  • D0-F0-cod/bias/1/om
  • D0-F0-cod/bias/1/em
  • D0-F0-cod/bias/2/om
  • ...
  • D0-F0-cod/1/om
  • D0-F0-cod/1/em
  • D0-F0-cod/2/om
  • ...

Details

The operating model folder should contain: forecast.ss, yourmodel.ctl, yourmodel.dat, ss3.par, and starter.ss. The files should be the versions that are returned from an SS run as .ss_new files. This is important because it creates consistent formatting which many of the functions in this package depend on. Rename the .ss_new files as listed above (and in all lowercase). The estimation model folder should contain all the same files listed above except the ss3.par and yourmodel.dat files, which are unnecessary but can be included if desired. See the vignette for details on modifying an existing SS3 model to run with ss3sim. Alternatively, you might consider modifying one of the built-in model configurations.

See Also

ss3sim_base, run_ss3model, run_bias_ss3, get_caseargs, expand_scenarios

Examples

# Create a temporary folder for the output and set the working directory:
temp_path <- file.path(tempdir(), "ss3sim-example")
dir.create(temp_path, showWarnings = FALSE)
wd <- getwd()
setwd(temp_path)

# Find the data in the ss3sim package:
d <- system.file("extdata", package = "ss3sim")
om <- paste0(d, "/models/cod-om")
em <- paste0(d, "/models/cod-em")
case_folder <- paste0(d, "/eg-cases")

# Without bias adjustment:
run_ss3sim(iterations = 1, scenarios = "D0-F0-cod",
  case_folder = case_folder, om_dir = om, em_dir = em)
unlink("D0-F0-cod", recursive = TRUE) # clean up

# An example specifying the case files:
run_ss3sim(iterations = 1, scenarios = "D0-F0-E0-cod",
  case_folder = case_folder, om_dir = om, em_dir = em,
  case_files = list(F = "F", D = c("index", "lcomp",
      "agecomp"), E = "E"))
unlink("D0-F0-cod", recursive = TRUE) # clean up

# With bias adjustment:
# (Note that bias_nsim should be bigger, say 5 or 10, but it is set
# to 2 here so the example runs faster.)
run_ss3sim(iterations = 1, scenarios = "D1-F0-cod",
  case_folder = case_folder, om_dir = om, em_dir = em,
  bias_adjust = TRUE, bias_nsim = 2)

# Restarting the previous run using the existing bias-adjustment
# output
run_ss3sim(iterations = 2:3, scenarios = "D1-F0-cod",
  case_folder = case_folder, om_dir = om, em_dir = em,
  bias_adjust = FALSE, bias_already_run = TRUE)
unlink("D1-F0-cod", recursive = TRUE)

# A run with deterministic process error for model checking:
recdevs_det <- matrix(0, nrow = 100, ncol = 20)
run_ss3sim(iterations = 1:20, scenarios = "D0-E100-F0-cod",
  case_folder = case_folder, om_dir = om, em_dir = em,
  bias_adjust = TRUE, bias_nsim = 2, user_recdevs = recdevs_det)
unlink("D0-E100-F0-cod", recursive = TRUE)

# An example of a run using parallel processing across 2 cores:
require(doParallel)
registerDoParallel(cores = 2)
require(foreach)
getDoParWorkers() # check how many cores are registered

# parallel scenarios:
run_ss3sim(iterations = 1, scenarios = c("D0-F0-cod",
    "D1-F0-cod"), case_folder = case_folder,
  om_dir = om, em_dir = em, parallel = TRUE)
unlink("D0-F0-cod", recursive = TRUE)
unlink("D1-F0-cod", recursive = TRUE)

# parallel iterations:
run_ss3sim(iterations = 1:2, scenarios = c("D0-F0-cod"),
  case_folder = case_folder, om_dir = om, em_dir = em,
  parallel = TRUE, parallel_iterations = TRUE)
unlink("D0-F0-cod", recursive = TRUE)

# parallel iterations with bias adjustment:
run_ss3sim(iterations = 1:2, scenarios = c("D0-F0-cod"),
  case_folder = case_folder, om_dir = om, em_dir = em, parallel = TRUE,
  parallel_iterations = TRUE, bias_adjust = TRUE, bias_nsim = 2)
unlink("D0-F0-cod", recursive = TRUE)

# Return to original working directory:
setwd(wd)