run_ss3sim: Master function to run SS3 simulations
In ss3sim: Fisheries Stock Assessment Simulation Testing with Stock Synthesis

Description Usage Arguments Details Value Author(s) See Also Examples

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.

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,
  ...)

`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 `get_caseargs` and the vignette for details on specifying the scenarios.
`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 `get_caseargs`. See that function for details and examples of how to specify this. The introduction vignette also explains how to specify the case files.
`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. For traditional stochastic simulations these would be independent and normally distributed deviations with a standard deviation equal to the desired sigma R. Note that these recruitment deviations will be used verbatim (after exponentiation). `user_recdevs` will not be multiplied by sigma R and they will not be log-normal bias corrected. If `user_recdevs` are specified as anything besides `NULL` the package will issue a warning about this. Biased recruitment deviations can lead to biased model results.
`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 one scenario but you wanted to run it faster.
`...`	Anything else to pass to `ss3sim_base`. This could include `bias_adjust`. Also, you can pass additional options to the `SS3` command through the argument `admb_options`.

The operating model folder should contain: forecast.ss, yourmodel.ctl, yourmodel.dat, ss.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 ss.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.

The output will appear in whatever your current R working directory is. There will be folders named after your scenarios. They will look like this:

D0-F0-cod/1/om
D0-F0-cod/1/em
D0-F0-cod/2/om
...

Sean C. Anderson

ss3sim_base, run_ss3model, get_caseargs, expand_scenarios

 ## Not run: 
# 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)
on.exit(setwd(wd), add = TRUE)

# Find the data in the ss3sim package:
d <- system.file("extdata", package = "ss3sim")
om <- file.path(d, "models", "cod-om")
em <- file.path(d, "models", "cod-em")
case_folder <- file.path(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-E0-cod", recursive = TRUE) # clean up

# If try to use bias adjustment, a warning will be triggered and the run will
# proceed WITHOUT using bias adjustment (and may result in error.)
# run_ss3sim(iterations = 1, scenarios = "D1-F0-cod",
#   case_folder = case_folder, om_dir = om, em_dir = em,
#   bias_adjust = TRUE)

# A run with deterministic process error for model checking:
recdevs_det <- matrix(0, nrow = 101, ncol = 2)
run_ss3sim(iterations = 1:2, scenarios = "D0-E100-F0-cod",
  case_folder = case_folder,
  case_files = list(F = "F", D = c("index", "lcomp", "agecomp"), E = "E"),
  om_dir = om, em_dir = em,
  bias_adjust = FALSE, 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 = "D0-F0-cod",
#   case_folder = case_folder, om_dir = om, em_dir = em,
#   parallel = TRUE, parallel_iterations = TRUE)
# unlink("D0-F0-cod", recursive = TRUE)

## End(Not run)