ss3sim_base {ss3sim}

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.

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.

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

• ...

Author(s)

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

See Also

run_ss3sim

Examples

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