High-level wrapper to run a simulation

A wrapper function that

calls r4ss::run() to run the operating model,
samples the output to create fishery and survey data, and
calls r4ss::run() to run the estimation model. This function is the main workhorse of ss3sim and is typically not called by the user but called from run_ss3sim().

ss3sim_base(
  iterations,
  scenarios,
  f_params,
  index_params,
  discard_params = NULL,
  lcomp_params = NULL,
  agecomp_params = NULL,
  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,
  weight_comps_params = NULL,
  user_recdevs = NULL,
  user_recdevs_warn = TRUE,
  bias_adjust = FALSE,
  sleep = 0,
  seed = 21,
  extras = " "
)

Arguments

iterations: Which iterations to run. A numeric vector.
scenarios: A name to use as the folder name for the unique combination of parameters for the OM and EM.
f_params: A named list containing arguments for change_f(). A mandatory input.
index_params: A named list containing arguments for sample_index(). A mandatory input.
discard_params: A named list containing arguments for sample_discard().
lcomp_params: A named list containing arguments for sample_lcomp(). A mandatory input.
agecomp_params: A named list containing arguments for sample_agecomp(). A mandatory input.
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).
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. If NA, then no estimation method is included and ss3sim just generates data.
retro_params: A named list containing the arguments for change_retro().
data_params: A named list containing arguments for changing data.
weight_comps_params: A named list containing arguments for r4ss::tune_comps().
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: A logical argument specifying bias adjustment is conducted. Bias adjustment helps assure that the estimated recruitment deviations, which are assumed to be log-normally distributed, are mean unbiased leading to mean-unbiased estimates of biomass Methot and Taylor, 2011. Bias adjustment should always be performed when using maximum likelihood estimation when running simulations for publication or management. The argument allows users to turn bias adjustment off because it involves running the EM multiple times with the hessian and is not needed when initially exploring your simulation structure.
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.
extras: A character string that will be passed to the extras argument of r4ss::run(). The default is " " which results in the hessian being inverted if the model has positive phases, i.e., the EM. Pass "-nohess " if you do not want to estimate the hessian or "-stopph 3 -nohess" if you want to stop the model in phase 3 and you do not want to invert the hessian. The key is that the entry must be one string with spaces between the arguments that will be passed to ADMB.

Value

The output will appear in whatever your current R working directory is. There will be folders named after your scenarios with one folder per iteration. Each iteration folder with include an operating model and an estimation method. Your directory will look like the following:

scen-cod/1/om
scen-cod/1/em
scen-cod/2/om
...

If em_dir = NA, then the contents of the em directories will be minimal because they will only contain the simulated data and not any fits to those data.

Details

This function is written to be flexible. You can specify the fishing mortality, survey catch-per-unit-effort settings, length-composition data settings, etc. in the function call as list objects (see the example below). For a generic higher-level function, see run_ss3sim().

Author

Sean Anderson with contributions from many others as listed in the DESCRIPTION file.

Examples

if (FALSE) {
# 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_dir <- file.path(d, "models", "cod-om")
em_dir <- file.path(d, "models", "cod-em")

# Or, create the argument lists directly in R:

F0 <- list(
  years = 1:100,
  fleets = 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(50, 100),
  years = list(26:100, seq(62, 100, by = 2))
)

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

E0 <- list(
  par_name = c("LnQ_base_Fishery", "NatM_uniform_Fem_GP_1"),
  par_int = c(NA, NA), par_phase = c(-5, -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_dir,
  em_dir = em_dir
)
replist <- r4ss::SS_output(file.path("D1-E0-F0-cod", 1, "em"),
  verbose = FALSE, printstats = FALSE, covar = FALSE
)
testthat::expect_equivalent(replist[["cpue"]][, "Yr"], index1[["years"]][[1]])

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

# Run without an EM, where {ss3sim} is a data-generating tool
ss3sim_base(
  iterations = 1,
  scenarios = "noEM",
  f_params = F0,
  index_params = index1,
  lcomp_params = lcomp1,
  agecomp_params = agecomp1,
  estim_params = E0,
  om_dir = om_dir,
  em_dir = NA
)
}

Arguments

Value

Details

See also

Author

Examples