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 = " "
)
Which iterations to run. A numeric vector.
A name to use as the folder name for the unique combination of parameters for the OM and EM.
A named list containing arguments for change_f()
.
A mandatory input.
A named list containing arguments for
sample_index()
. A mandatory input.
A named list containing arguments for
sample_discard()
.
A named list containing arguments for
sample_lcomp()
. A mandatory input.
A named list containing arguments for
sample_agecomp()
. A mandatory input.
A named list containing arguments for
sample_calcomp()
, for conditional age-at-length data.
A named list containing arguments for
sample_wtatage()
, for empirical weight-at-age data.
A named list containing arguments for
sample_mlacomp()
, for mean length-at-age data.
A named list containing arguments for
change_em_binning()
.
A named list containing arguments for
change_e()
.
A named list containing arguments for
change_tv()
(time-varying).
A named list containing arguments for change_o()
.
The directory with the operating model you want to copy and use for the specified simulations.
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.
A named list containing the arguments for
change_retro()
.
A named list containing arguments for changing data.
A named list containing arguments for
r4ss::tune_comps()
.
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.
A logical argument allowing users to turn the
warning regarding biased recruitment deviations off when user_recdevs
are specified.
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.
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.
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.
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.
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.
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()
.
if (FALSE) { # \dontrun{
# 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
)
} # }