run an MSE using SS OMs — run

High level function to run a management strategy evaluation using Stock Synthesis as the Operating model(s). For more examples and information on how to use SSMSE, see the SSMSE user manual.

Usage

run_SSMSE(
  scen_name_vec,
  out_dir_scen_vec = NULL,
  iter_vec,
  OM_name_vec = NULL,
  OM_in_dir_vec = NULL,
  EM_name_vec = NULL,
  EM_in_dir_vec = NULL,
  run_EM_last_yr = FALSE,
  MS_vec = c("EM", "no_catch", "Interim"),
  custom_MS_source = NULL,
  use_SS_boot_vec = TRUE,
  nyrs_vec,
  nyrs_assess_vec,
  sample_struct_list = NULL,
  future_om_list = NULL,
  sample_struct_hist_list = NULL,
  sample_catch_vec = FALSE,
  interim_struct_list = NULL,
  verbose = FALSE,
  seed = NULL,
  n_F_search_loops = 20,
  tolerance_F_search = 0.001,
  run_parallel = FALSE,
  n_cores = NULL
)

Arguments

scen_name_vec: A vector containing names of the scenarios. The each string will be a directory containing all the model runs for a scenario.s
out_dir_scen_vec: The directory to which to write output. IF NULL, will default to the working directory.
iter_vec: The number of iterations per scenario. A vector of integers in the same order as scen_name_vec.
OM_name_vec: Names of a valid Stock Synthesis stock assessment model. To see the names of built-in models, type list.dirs(system.file("extdata", "models", package = "SSMSE"),full.names = FALSE, recursive = FALSE) into the R console.
OM_in_dir_vec: Vector of relative or absolute paths to the operating model, if using a model outside of the SSMSE package.
EM_name_vec: Should be NULL unless MS = "EM". Name of a valid Stock Synthesis stock assessment model to use as an EM. If the value of EM_name is NULL and MS = "EM", then SSMSE will look for the estimation model in the path specified in EM_in_dir. valid inputs for EM_name are: "cod" or NULL.
EM_in_dir_vec: Relative or absolute path to the estimation model, if using model outside of the SSMSE package. Note that this value should be NULL if MS has a value other than "EM".
run_EM_last_yr: Should the MS be implemented to get future catch if the last year is an assessment year? TRUE/FALSE option, so the same for all scenarios and iterations. Defaults to FALSE.
MS_vec: Vector of management strategies. Current options are: "last_yr_catch" which uses the previous year's catch; "no_catch" which uses 0 catch; "EM" which uses an stock synthesis model as the estimation method and the management strategy as defined in the forecast file of the stock synthesis estimation method; "Interim" to modify catch based on survey predictions between assessments. Users can also specify their own managment strategies as an function. To use the function, it must be available in the global enviroment and specified by name in MS. For example, if the function is called "my_ms" then the user should make it available in the global environment and specify "my_ms" as a component of MS_vec.
custom_MS_source: A file location with the source code for any custom MS models to be used in the simulation. SSMSE will source this file which should contain a function/s whose name/s match each custom MS models included in MS_vec. To learn more about using custom management strategies, see the using a Custom Management Stratey/Procedure section in the SSMSE User Manual.
use_SS_boot_vec: Should a bootstrapped data set generated by SS be used? Defaults to TRUE.
nyrs_vec: Number of years beyond the years included in the OM to run the MSE. A single integer value.
nyrs_assess_vec: The number of years between assessments. E.g., if an assessment is conducted every 3 years, put 3 here. A single integer value. (NOTE: This could be made more flexible by instead reading in a vector of assessment years, so users could specify irregular numbers of yrs between assessments.)
sample_struct_list: A optional list of lists including which years, seasons, and fleets should be added from the OM into the EM for different types of data. If NULL, the data structure will try to be infered from the pattern found for each of the datatypes within the EM datafiles. Include this strucutre for the number of years to extend the model out.
future_om_list: An optional list of lists including changes that should be made after the end year of the input model. Each first level list element outlines 1 change to be made to the operating model. To see an example, try running create_future_om_list. Defaults to NULL, which implies that the model will be extended forward in time assuming the original model structure.
sample_struct_hist_list: An optional list of lists including which years should be sampled for the historical period for the data generated from the OM. If this is left as NULL, then the same sampling scheme will be used as in the OM's data file. If it is not NULL, then each year
sample_catch_vec: Should catch be sampled or fixed at the OM values? This can be a single Boolean (TRUE or FALSE) to apply to all scenarios or a vector of the same length as the number of scenarios. Defaults to FALSE.
interim_struct_list: A optional list of parameters to control an interim assessment with an example structure below, where Beta=a positive value that is inversely proportional to risk, MA_years= the number of years to average index observations of when calculating deviations, assess_freq=the number of years between full assessments during with an interim assessment will happen every year, and Index_weights is a vector of length n indexes that weights all indexes for multi index inference. interim_struct_list<-list(Beta=1,MA_years=3,assess_freq=5,Index_weights=rep(1,max(ref_index[,3])))
verbose: Want verbose output? Defaults to FALSE.
seed: Input a fixed seed to replicate previous simulation runs. Seed can be a single value for a global seed, n_scenarios+1 length vector for scenario specific and a global seed, n_iterations+n_scenarios+1 length vector for iteration scenario and global seeds. Can also be a list object with a single value under seed[["global"]], a vector under seed[["scenario"]], and a multiple vectors for iteration specific seeds under seed[["iter"]][[1:n_scenarios]].
n_F_search_loops: Number of times to try to find an F that achieves the catches input in the OM. Defaults to 20.
tolerance_F_search: How far apart the input catch and achieved catch can be in tried to find an F that achieves the catch input in the OM. Defaults to 0.001.
run_parallel: Option to use parallel processing on iterations. Defaults to FALSE
n_cores: how many cores to use if running in parallel defaults to n_cores available - 1 (also capped at one less than the number of cores available)

Author

Kathryn Doering & Nathan Vaughan

Examples

if (FALSE) {
my_dir <- file.path(tempdir(), "ex-run_SSMSE")
dir.create(my_dir)
# For the EM, use the specified data structure
my_sample_struct_list <- list(
  NULL,
  list(
    catch = data.frame(
      Yr = 101:106,
      Seas = 1,
      FltSvy = 1,
      SE = 0.05
    ),
    CPUE = data.frame(
      Yr = c(102, 105),
      Seas = 7,
      FltSvy = 2,
      SE = 0.01
    ),
    lencomp = data.frame(
      Yr = c(102, 105), Seas = 1,
      FltSvy = 1, Sex = 0,
      Part = 0, Nsamp = 100
    ),
  )
)
# Use the default parameter values, except for the once specified.
# Note that the scen_list, either specified or internally created in the
# function is returned.
input_list <- run_SSMSE(
  scen_name_vec = c("scen_1", "scen_2"),
  out_dir_scen_vec = my_dir,
  iter_vec = c(2, 2),
  OM_name_vec = c("cod", "cod"),
  OM_in_dir_vec = NULL,
  EM_name_vec = c(NA, "cod"),
  EM_in_dir_vec = NULL,
  MS_vec = c("no_catch", "EM"),
  use_SS_boot_vec = TRUE,
  nyrs_vec = 6,
  nyrs_assess_vec = 3,
  scope = c("2", "1", "3"),
  rec_dev_pattern = c(
    "none", "rand", "AutoCorr_rand",
    "AutoCorr_Spec", "vector"
  ),
  rec_dev_pars = NULL,
  impl_error_pattern = c("none", "rand", "user"),
  impl_error_pars = NULL,
  verbose = FALSE,
  seed = NULL,
  sample_struct_list = my_sample_struct_list
)
unlink(my_dir, recursive = TRUE)
}