ss3sim_base: Base wrapper function to run an ss3sim simulation

Description

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.

Usage

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

Arguments

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.

Value

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

Details

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.

Examples

Run this code

# 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
# }