Base wrapper function to run an ss3sim simulation
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.
The output will appear in whatever your current working directory is. There will be folders named after your scenarios. They will look like this:
D0-F0-cod/1/omD0-F0-cod/1/emD0-F0-cod/2/omThis 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.
## 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)
run_ss3sim
Sean Anderson with contributions from many others as listed in the DESCRIPTION file.