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, om_dir, em_dir, retro_params = NULL,
  data_params = NULL, call_change_data = TRUE, user_recdevs = NULL,
  user_recdevs_warn = TRUE, bias_adjust = FALSE, bias_nsim = 5,
  bias_already_run = FALSE, hess_always = FALSE, print_logfile = TRUE,
  sleep = 0, conv_crit = 0.2, seed = 21, keep_compreport = TRUE, ...)

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.

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

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.

call_change_data

A boolean of whether to call change_data and modify the OM at each iteration. Defaults to TRUE. See the vignette for further information on why you might choose to turn this off.

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.

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? See run_bias_ss3.

bias_nsim

If bias adjustment is run, how many simulations should the bias adjustment factor be estimated from? It will take the mean of the adjustment factors across these runs.

bias_already_run

If you've already run the bias runs for a scenario (the bias folders and .dat files already exist) then you can set this to TRUE to avoid re-running the bias adjustment routine.

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.

conv_crit

The maximum percentage of bias iterations that can produce a non-invertible Hessian before a warning will be produced. If this percentage is exceeded then a file WARNINGS.txt will be produced. Currently, the simulations will continue to run.

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 comb

keep_compreport

Logical: should the SS3 file CompReport.sso be kept or deleted? CompReport.sso is often rather large and so deleting it can save space but the file is needed for some of the r4ss plots among other purposes.

...

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 argu

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

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

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

# 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")

# Pull in file paths from the package example data:
d <- system.file("extdata", package = "ss3sim")
om_dir <- paste0(d, "/models/cod-om")
em_dir <- paste0(d, "/models/cod-em")
a <- get_caseargs(folder = paste0(d, "/eg-cases"), scenario =
"F0-D0-M0-E0-cod")

ss3sim_base(iterations = 1, scenarios = "M0-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("M0-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 = 1913:2012, years_alter = 1913:2012, fvals = c(rep(0,
  25), rep(0.114, 75)))

index1 <- list(fleets = 2, years = list(seq(1974, 2012, by = 2)), sds_obs =
  list(0.1))

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

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

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

M0 <- list(NatM_p_1_Fem_GP_1 = rep(0, 100))

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

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

setwd(wd)