ss3sim_base: Base wrapper function to run an ss3sim simulation
In ss3sim: Fisheries Stock Assessment Simulation Testing with Stock Synthesis

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

This function is a wrapper function that can call run_ss3model for the operating model, sample the output (add recruitment deviations, survey the data, etc.), and run the estimation model. ss3sim_base is the main internal function for ss3sim. It is intended to be used through run_ss3sim, but can also be used directly.

ss3sim_base(iterations, scenarios, f_params, index_params, lcomp_params,
  agecomp_params, calcomp_params = NULL, wtatage_params = NULL,
  mlacomp_params = NULL, em_binning_params = NULL,
  estim_params = NULL, tv_params = NULL, operat_params = NULL,
  om_dir, em_dir, retro_params = NULL, data_params = NULL,
  user_recdevs = NULL, user_recdevs_warn = TRUE, bias_adjust = FALSE,
  hess_always = FALSE, print_logfile = TRUE, sleep = 0, seed = 21,
  ...)

`iterations`	Which iterations to run. A numeric vector.
`scenarios`	Which scenarios to run.
`f_params`	A named list containing arguments for `change_f`. A mandatory case.
`index_params`	A named list containing arguments for `sample_index`. A mandatory case.
`lcomp_params`	A named list containing arguments for `sample_lcomp`. A mandatory case.
`agecomp_params`	A named list containing arguments for `sample_agecomp`. A mandatory case.
`calcomp_params`	A named list containing arguments for `sample_calcomp`, for conditional age-at-length data. Currently CAL is not implemented in this version of ss3sim, so calcomp_params should be NULL.
`wtatage_params`	A named list containing arguments for `sample_wtatage`, for empirical weight-at-age data.
`mlacomp_params`	A named list containing arguments for `sample_mlacomp`, for mean length-at-age data.
`em_binning_params`	A named list containing arguments for `change_em_binning`.
`estim_params`	A named list containing arguments for `change_e`.
`tv_params`	A named list containing arguments for `change_tv` (time-varying).
`operat_params`	A named list containing arguments for `change_o`.
`om_dir`	The directory with the operating model you want to copy and use for the specified simulations.
`em_dir`	The directory with the estimation model you want to copy and use for the specified simulations.
`retro_params`	A named list containing arguments for `change_retro`.
`data_params`	A named list containing arguments for `change_data`.
`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.
`user_recdevs_warn`	A logical argument allowing users to turn the warning regarding biased recruitment deviations off when `user_recdevs` are specified.
`bias_adjust`	Run bias adjustment first?.
`hess_always`	If `TRUE` then the Hessian will always be calculated. If `FALSE` then the Hessian will only be calculated for bias-adjustment runs thereby saving time.
`print_logfile`	Logical. Print a log file?
`sleep`	A time interval (in seconds) to pause on each iteration. Useful if you want to reduce average CPU time – perhaps because you're working on a shared server.
`seed`	The seed value to pass to `get_recdevs` when generating recruitment deviations. The generated recruitment deviations depend on the iteration value, but also on the value of `seed`. A given combination of iteration, number of years, and `seed` value will result in the same recruitment deviations.
`...`	Anything extra to pass to `run_ss3model`. For example, you may want to pass additional options to `SS3` through the argument `admb_options`. Anything that doesn't match a named argument in `run_ss3model` will be passed to the `system` call that runs `SS3`.

This function is written to be flexible. You can specify the fishing mortality, survey index, length composition, age composition, and time-varying parameters in the function call as list objects (see the example below). For a generic higher-level function, see run_ss3sim.

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 Anderson with contributions from many others as listed in the DESCRIPTION file.

run_ss3sim

## Not run: 
# Create a temporary folder for the output and set the working directory:
  # Create a temporary folder for the output and set the working directory:
  temp_path <- file.path(tempdir(), "ss3sim-base-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")

  # Pull in file paths from the package example data:
  d <- system.file("extdata", package = "ss3sim")
  om_dir <- file.path(d, "models", "cod-om")
  em_dir <- file.path(d, "models", "cod-em")
  a <- get_caseargs(folder = file.path(d, "eg-cases"),
                    case_files = list(F = "F",
                                      D = c("index", "lcomp", "agecomp"),
                                      E = "E"),
                    scenario = "F0-D0-E0-cod")
  ss3sim_base(iterations = 1,
              scenarios = "F0-D0-E0-cod",
              f_params = a$F,
              index_params = a$index,
              lcomp_params = a$lcomp,
              agecomp_params = a$agecomp,
              tv_params = a$tv_params,
              estim_params = a$E,
              om_dir = om_dir,
              em_dir = em_dir)
  unlink("F0-D0-E0-cod", recursive = TRUE) # clean up

  # Or, create the argument lists directly in R and skip the case file setup:

  F0 <- list(years = 1:100,
             fisheries = 1,
             fvals = c(rep(0, 25), rep(0.114, 75)))

  index1 <- list(fleets = 2, years = list(seq(62, 100, by = 2)),
                 sds_obs = list(0.1))

  lcomp1 <- list(fleets = c(1, 2), Nsamp = list(100, 100),
                 years = list(26:100, seq(62, 100, by = 2)),
                 lengthbin_vector = NULL, cpar = c(1, 1))

  agecomp1 <- list(fleets = c(1, 2), Nsamp = list(100, 100),
                   years = list(26:100, seq(62, 100, by = 2)),
                   agebin_vector = NULL, cpar = c(1, 1))

  E0 <- list(natM_type = NULL, natM_n_breakpoints = NULL, natM_lorenzen = NULL,
             natM_val = NULL,
             par_name = c("LnQ_base_Fishery", "NatM_p_1_Fem_GP_1"),
             par_int = c(NA, NA), par_phase = c(-1, -1), forecast_num = 0)

  ss3sim_base(iterations = 1,
              scenarios = "D1-E0-F0-cod", #name as desired
              f_params = F0,
              index_params = index1,
              lcomp_params = lcomp1,
              agecomp_params = agecomp1,
              estim_params = E0,
              om_dir = om,
              em_dir = em)

  unlink("D1-E0-F0-cod", recursive = TRUE) # clean up

## End(Not run)