Skip to contents

Run an MSE scenario using SS OM

Source: R/runSSMSE.R
run_SSMSE_scen.Rd

High level function to run 1 scenario (but potentially many iterations) for a management strategy evaluation using Stock Synthesis as the Operating Model

Usage

run_SSMSE_scen(
  scen_name = "scen_1",
  nscen = 1,
  out_dir_scen = NULL,
  iter = 2,
  OM_name = "cod",
  OM_in_dir = NULL,
  EM_name = NULL,
  EM_in_dir = NULL,
  run_EM_last_yr = FALSE,
  MS = "no_catch",
  custom_MS_source = NULL,
  use_SS_boot = TRUE,
  nyrs = 100,
  nyrs_assess = 3,
  scen_seed = NULL,
  sample_struct = NULL,
  future_om_list = NULL,
  sample_struct_hist = NULL,
  sample_catch = FALSE,
  interim_struct = NULL,
  verbose = FALSE,
  run_parallel = FALSE,
  n_cores = NULL,
  n_F_search_loops = 20,
  tolerance_F_search = 0.001
)

Arguments

scen_name

Name of the scenario. The directory containing all the model runs the scenario will be stored within a folder of this name.

nscen

Which scenario is this. Integer value >=1

out_dir_scen

The directory to which to write output. IF NULL, will

iter

The number of iterations for the scenario. A single integer value.

OM_name

Name of the operating model (OM).

OM_in_dir

Relative or absolute path to the operating model, if using a model outside of the SSMSE package. Should be a string.

EM_name

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. or NULL.

EM_in_dir

Relative or absolute path to the estimation model,

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

The management strategy to use. 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 management strategies as a function. For example, if the function is called "my_ms" then the user should specify MS = "my_ms" and specify the path to the file containing the function in custom_MS_source.

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

Should a bootstrapped data set generated by SS be used? Defaults to TRUE.

nyrs

Number of years beyond the years included in the OM to run the MSE. A single integer value.

nyrs_assess

The number of years between assessments. E.g., if an assessment is conducted every 3 years, put 3 here. A single integer value. (NOTE: we could make this more flexible by instead reading in a vector of assessment years, so users could specify irregular numbers of yrs between assessments.)

scen_seed

List containing fixed seeds for this scenario and its iterations.

sample_struct

A optional list 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 inferred from the pattern found for each of the datatypes within the EM datafiles. Include this structure for the number of years to extend the model out. Note that the data should be specified using the list component names and column names as in would be used in r4ss::SS_readdat(). The run_SSMSE_iter function examples give an example of what this structure should be. Running the function create_sample_struct() will also produce a sample_struct object in the correct form. Can be NULL only when MS is not EM.

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

An optional list 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

Should catch be sampled or fixed at the OM values? Defaults to FALSE.

interim_struct

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(Beta = 1,
                     MA_years = 3,
                     assess_freq = 5,
                     Index_weights = rep(1, max(ref_index[, 3])))

verbose

Want verbose output? Defaults to FALSE.

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)

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.

Author

Kathryn Doering & Nathan Vaughan

Examples

if (FALSE) {
# Create a temporary folder for the output and set the working directory:
temp_path <- file.path(tempdir(), "run_SSMSE_scen-example")
dir.create(temp_path, showWarnings = FALSE)

# run 2 iteration and 1 scenario of SSMSE
run_SSMSE_scen(
  scen_name = "no_catch",
  iter = 1:2,
  OM_name = "cod",
  MS = "no_catch",
  out_dir_scen = temp_path,
  nyrs = 6,
  nyrs_assess = 3
)
unlink(temp_path, recursive = TRUE)
}