Package 'SSMSE'

A single change input

The scenario name

The iteration name

A parameter file as read in by r4ss::SS_readpar_3.30

A data file as read in by r4ss::SS_readdat.

The dataframe with future om values

The number of years to extend the model forward

A control file as read in by r4ss::SS_readctl.

An valid SS data file read in using r4ss. In particular, this should be sampled data.

Datafile name run in previous iterations with the EM. Assumed to exist in EM_dir.

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.

Absolute or relative path to the Estimation model directory.

The number of years between assessments. E.g., if an assessment is conducted every 3 years, put 3 here. A single integer value.

Should checks on the data be performed? Defaults to TRUE.

An optional name of a file to write the new datafile to. If NULL, a new datafile will not be written.

Want verbose output? Defaults to FALSE.

A control file as read in by r4ss::SS_readctl.

A data file as read in by r4ss::SS_readdat.

A parameter file as read in by r4ss::SS_readpar_3.30

The timeseries table from r4ss::SS_output().

A data frame with random sample data for future parameter

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.

A datafile as read in by r4ss::SS_readdat

A data frame of observed composition data extracted from SS .dat file

A data frame of the expected composition data as estimated by an SS assessment model

A vector object including the composition bins

A vector of the fleet numbers to analyze composition uncertainty for (Default is all fleets if NULL)

A vector of the years to include when calculating composition uncertainty (Default is all years if NULL)

A vector of the seasons to include when calculating composition uncertainty (Default is all years if NULL)

TRUE/FALSE should genders be merged to calculate variance and biases (Defaults to TRUE)

A vector of the genders to analyze composition uncertainty for (Default is all genders if NULL)

TRUE/FALSE should seasons be merged to calculate variance and biases (Defaults to TRUE)

TRUE/FALSE should fleets be merged to calculate variance and biases (Defaults to FALSE)

The line in the input df containing info about the parameter.

Which line in val info to use.

This is the historic parameter that the end trend value. Can be NA if the there is no line in val_info for the given parameter

The dataframe of the parameter values by year. Use to get start val and last year

Name of the parameter with devs from the SS model. will reference, if using a relative method.

A parameter file as read in by r4ss::SS_readpar_3.30

A control file as read in by r4ss::SS_readctl.

Which parameter section should this variabile be in?

A data file as read in by r4ss::SS_readdat.

Filename of the datfile produced by the OM within the EM_dir.

Filename of the datfile from the original EM within the EM_dir.

Absolute or relative path to the Estimation model directory.

Should checks on the data be performed? Defaults to TRUE.

Want verbose output? Defaults to FALSE.

A forecasting file read into R using r4ss::SS_readforecast()

Should the absolute years in the forecast file be changed to relative years? Defaults to TRUE.

The number of years to increment forecasting period years. If NULL (the default value), will not be incremented.

The number of years of forecasting to do. If NULL, do not change the number of forecasting years already specified in fore

The first year of the model

The last year of the model fore assumes when read in. Note that the assumed model year will be different for the output if nyrs_increment is not NULL.

An SS data file read in using r4ss for an EM

An SS data file read in using r4ss for an OM

A component in both EM_dat and OM_dat to check values for. This should be a single string value.

The column names of data to append together.

The catch dataframe to test

Summary returned from running SSMSE_summary_all()

The first year of SSB checked

The last year of SSB checked

Input to check. Should be a directory name that should contain an SS model that can be used as an OM. @author Kathryn Doering

A forecast list read in using r4ss::SS_readforecast

The number of fleets with catch. If NULL, this function will skip a check requiring this input.

A dataframe of catch values and its associated information to add to the OM. The column names are the same as in an SS data file (e.g., year, season, fleet, catch, catch_se). length of the number of years (only works when catch is for 1 fleet)

The full path to the OM directory.

What units is the catch in? "bio" for biomass or "num" for numbers? Defaults to "bio".

The optional name (as a character string) of the datafile, presumed to exist in OM_dir. Defaults to NULL, and if is NULL, the function will get the datfile name from the starter.ss file in OM_dir.

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.

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.

The list object of scenarios specifying inputs created by SSMSE::create_scen_list.

A data set read in using r4ss::SS_readdat from an operating model. Note that it should span the same years as EM_dat.

A data set read in using r4ss::SS_readdata from an estimation model. Note that it should span the same years as EM_dat

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.

The list to compare sample_struct to.

A list to check

Want verbose output? Defaults to FALSE.

The full path to the directory in which the OM is run.

Relative or absolute path to the estimation model, if using a model outside of the SSMSE package.

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.

Allow existing files to be overwritten?

An SS data file as a list read in using r4ss

List item in dat_list to extract and return a modified version of this value

Column names in list_item

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.

The scenario name

The iteration number

Path to the OM files. Used to reference parameter names.

The total number of years that the model will be extended forward.

A global seed to set, then pull new seeds from. Defaults to 123.

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.

Data frame defining how r4ss names relate to the sample_struct names. For now, a 1:1 relationship is assumed.

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

The full path to the directory in which the OM is run.

Relative or absolute path to the estimation model,

Relative or absolute path to the estimation model, if using a model outside of the SSMSE package.

Want verbose output? Defaults to FALSE.

Type of example future_om_list object to create. Options are "model_change" or "custom". Defaults to "model_change".

The length of the example list to create. Defaults to 1. For now, just replicates the same list.

The full path to the directory in which the OM is run.

Allow existing files to be overwritten?

Should a new datafile be written?

Want verbose output? Defaults to FALSE.

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

The number of years between assessments. This is used to structure the forecast file for use in the OM.

The scenario number

The scenario name

the iteration number

An optional data_frame including changes that should be made after the end year of the input model. Including parameter variations, recruitment deviations, and implementation errors.

Should the model be run without estimation and some basic checks done to verify that the OM can run? Defaults to TRUE.

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.

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.

A random seed so that reproducible results are possible.

The directory to which to write output. IF NULL, will default to the working directory.

The number iteration

Name of the operating model (OM).

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

Name of the EM model

Relative or absolute path to the estimation model,

An r4ss list object read in using r4ss::SS_readdat() or the path (relative or absolute) to an SS data file to read in.

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

Should all NAs be removed from dataframes? Defaults to FALSE.

A vector containing names of the scenarios. The each string will be a directory containing all the model runs for a scenario.s

The directory to which to write output. IF NULL, will default to the working directory.

The number of iterations per scenario. A vector of integers in the same order as scen_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.

Vector of relative or absolute paths to the operating model, if using a model outside of the SSMSE package.

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.

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".

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.

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

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

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

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.

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

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.

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

Name of the operating model (OM).

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

Path where the new models will be written. Defaults to the current working directory.

Name of the parameter to modify

Vector of parameter values to modify in the OM. Assume these will be fixed so phase will be set as negative.

Should the models be refit to data? Defaults to TRUE

Should the hessian be estimated if reffiting the OMs? defaults to FALSE

Relative or absolute path to the estimation model, if using a model outside of the SSMSE package.

Logical. If this is the first initialization loop of the MSE, init_loop should be TRUE. If it is in further loops, it should be FALSE.

An valid SS data file read in using r4ss. In particular, this should be sampled data.

Want verbose output? Defaults to FALSE.

The number of years between assessments. E.g., if an assessment is conducted every 3 years, put 3 here. A single integer value.

Which years should be added to the new model? Ignored if init_loop is TRUE.

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.

A random seed so that reproducible results are possible.

The full path to the directory in which the OM is run.

Any additional parameters

Path to the Stock Synthesis data file containing catch

A vector containing a range of years. Years are as defined in the Stock Synthesis data file.

Name of SS3 binary, defaults to "ss"

Path to the Stock Synthesis data file containing catch

A vector containing a range of years. Years are as defined in the Stock Synthesis data file.

Path to the Stock Synthesis data file containing catch

A vector containing a range of years. Years are as defined in the Stock Synthesis data file.

The timeseries table from r4ss::SS_output().

From datalist, the catch units. A named list where the names are the fleets (to provide an extra check)

Path to the EM files

A SS datfile read into R using r4ss::SS_readdat()

An SS data file read in by as a list read in using r4ss from the operating model

An SS data file read in by as a list read in using r4ss from the estimation model

Should checks on the data be performed? Defaults to TRUE.

The timeseries table from r4ss::SS_output().

A vector of fleet names, in the order they appear in the ss model.

A vector of ALL fleet names that are in the model in the order that they are specified in the model. This vector helps the function know which order the fleets appear in the model.

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.

The full path to the directory in which the OM is run.

a vector of years

An SS data file

Types of data to include

A dataframe which has a column that matches (at least partially) colname

How should the value to be returned be selected? Current options include "most_common_value", where the most common input uncertainty value will be returned and "only_value" where all input values must be the same in data; if they are, this value will be returned. Otherwise, an error will be generated.

Column name as a string in data. Note that partial matching and regular expressions can be used.

Column name as a string in data used to group the data before calculating the input value to use. Defaults to NULL.

The full path to the OM directory.

A vector of years

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.

Path to the directory containing the scenarios, either relative or absolute. Defaults to the working directory.

If it exists, should the summmary files generated by SSMSE_summary_all be used? Defaults to TRUE.

Quantites from the operating model to add

Summary returned from running SSMSE_summary_all()

The first year to include in the average

The last year to include in the average

The timeseries table from r4ss::SS_output().

From datalist, the catch units. A named list where the names are the fleets (to provide an extra check)

Summary returned from running SSMSE_summary_all()

The first year to include in the average

The last year to include in the average

Path to the Stock Synthesis data file containing catch

A vector containing a range of years. Years are as defined in the Stock Synthesis data file.

Relative or absolute path to the estimation model, if using a model outside of the SSMSE package.

Initialization director that retains the reference files for interim assessments

Logical. If this is the first initialization loop of the MSE, init_loop should be TRUE. If it is in further loops, it should be FALSE.

An valid SS data file read in using r4ss. In particular, this should be sampled data.

The full path to the directory in which the OM is run.

Want verbose output? Defaults to FALSE.

The number of years between assessments. E.g., if an assessment is conducted every 3 years, put 3 here. A single integer value.

Which years should be added to the new model? Ignored if init_loop is TRUE.

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.

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.

An optional including how many years to average over, fleet weights, the scaling rate (Beta) of catch relative to the index change for each fleet, and the reference year for each fleet (either a fixed year or <=0 relative to end_yr, fixed year will stay constant during simulation while relative year will progress with simulation).

A random seed so that reproducible results are possible.

Any additional parameters

The full path to the directory in which the OM is run.

An valid SS data file read in using r4ss. In particular, this should be sampled data.

Which years should be added to the new model? Ignored if init_loop is TRUE.

Any additional parameters

Name of the operating model (OM).

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

the parameter names to find

A parameter file as read in by r4ss::SS_readpar_3.30

The full path to the directory in which the OM is run.

An valid SS data file read in using r4ss. In particular, this should be sampled data.

Which years should be added to the new model? Ignored if init_loop is TRUE.

Any additional parameters

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.

Relative or absolute path to the estimation model, if using a model outside of the SSMSE package.

Initialization director that retains the reference files for interim assessments

Logical. If this is the first initialization loop of the MSE, init_loop should be TRUE. If it is in further loops, it should be FALSE.

An valid SS data file read in using r4ss. In particular, this should be sampled data.

The full path to the directory in which the OM is run.

Want verbose output? Defaults to FALSE.

The number of years between assessments. E.g., if an assessment is conducted every 3 years, put 3 here. A single integer value.

Which years should be added to the new model? Ignored if init_loop is TRUE.

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.

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.

An optional including how many years to average over, fleet weights, the scaling rate (Beta) of catch relative to the index change for each fleet, and the reference year for each fleet (either a fixed year or <=0 relative to end_yr, fixed year will stay constant during simulation while relative year will progress with simulation).

A random seed so that reproducible results are possible.

Path to the directory containing 1 scenario. Defaults to the current working directory.

Type of composition data, age or length. Defaults to age.

Path to the directory containing 1 scenario. Defaults to the current working directory.

Object name that is not an r4ss object to print in the error

Type that obj_name was expected to be, but is not,

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.

The data file, as read in using r4ss

the object (containing list component of name in obj) that will be modified. Only combinations of the columns found in compare object will be retained

the object (containing list component of name_in_obj) that return_obj will be compared to

the name of the list elements to use; the same name must be in return_obj and compare_obj. This list element must be a data frame with the same column names

The column names within the name_in_obj list components to compare.

Absolute or relative path to the estimation model directory

Get the hessian during model run? Defaults to FALSE. Not estimating the hessian will speed up the run, but no estimates of error will be generated.

Perform checks to see if the model converged? Defaults to TRUE.

Should input values be read from the .par file? If TRUE, will change setting in the starter file; otherwise, will use the setting already in the starter file, which may or may not read from the .par file.

Want verbose output? Defaults to FALSE.

The full path to the OM directory.

Return the bootstrap dataset? If TRUE, function returns the number bootstrapped dataset specified in nboot. If FALSE, it returns the expected values.

The number bootstrapped data set. This value is only used if boot = TRUE. Note that this numbering does NOT correspond with the numbering in section of r4ss::SS_readdat. E.g., specifying section = 3 in SS_readdat is equivalent to specifying nboot = 1.

Is this the initial iteration of the OM? Defaults to FALSE.

Want verbose output? Defaults to FALSE.

If set to TRUE, and the run fails, a new folder called error_check will be created, and the model will be run from control start values instead of ss.par. The 2 par files are then compared to help debug the issue with the model run. Defaults to TRUE.

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

A random seed so that reproducible results are possible.

The full or relative path to the model directory

Any options to pass to SS command. Should be of the form '-option'. Note that no checks are done to ensure this is a valid ADMB command

Name of the SS executable. Defaults to "ss"

Passed to system. If TRUE then ADMB output is not printed on screen. This will be slightly faster. Set to FALSE to help with debugging.

A length of time (in seconds) to pause after running the simulation model. This can be necessary on certain computers where file writing can be slightly delayed. For example, on computers where the files are written over a network connection. If the output files haven't finished writing before R starts looking for the output then the simulation will crash with an error about missing files. The default value is set to 0.01 seconds, just to be safe.

Logical: passed on to system.

Should it be checked that the model ran by deleting the data.ss_new file if one exists and then checking if one was created? Defaults to TRUE.

If set to TRUE, and the run fails, a new folder called error_check will be created, and the model will be run from control start values instead of ss.par. The 2 par files are then compared to help debug the issue with the model run. Defaults to FALSE.

Want verbose output? Defaults to FALSE.

Anything else to pass to system.

A vector containing names of the scenarios. The each string will be a directory containing all the model runs for a scenario.s

The directory to which to write output. IF NULL, will default to the working directory.

The number of iterations per scenario. A vector of integers in the same order as scen_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.

Vector of relative or absolute paths to the operating model, if using a model outside of the SSMSE package.

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.

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".

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.

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.

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.

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

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

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

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.

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.

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

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.

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

Want verbose output? Defaults to FALSE.

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]].

Number of times to try to find an F that achieves the catches input in the OM. Defaults to 20.

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.

Option to use parallel processing on iterations. Defaults to FALSE

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)

The directory to which to write output. IF NULL, will default to the working directory.

Name of the operating model (OM).

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

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.

Relative or absolute path to the estimation model,

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.

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.

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.

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

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

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

number of years of lag in obtaining data. i.e. the number of years post EM assessment end yr before advice can be implemented. defaults to 0.

Which scenario is this. Integer value >=1

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

The iteration number, which is also the name of the folder the results will be written to.

List containing fixed seeds for this iteration.

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.

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.

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.

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

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

Number of times to try to find an F that achieves the catches input in the OM. Defaults to 20.

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.

Want verbose output? Defaults to FALSE.

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

Which scenario is this. Integer value >=1

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

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

Name of the operating model (OM).

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

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.

Relative or absolute path to the estimation model,

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.

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.

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.

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

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

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

List containing fixed seeds for this scenario and its iterations.

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.

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.

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.

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

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

Want verbose output? Defaults to FALSE.

Option to use parallel processing on iterations. Defaults to FALSE

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)

Number of times to try to find an F that achieves the catches input in the OM. Defaults to 20.

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.

A single value or vector of mean parameters

A single value or vector of sd parameter

The phi (coefficient) value for an ar 1 process. Should be between -1 and 1. 0 means an AR 1 process will NOT be used. 1 indicates a random walk. A single value or vector.

The number of sampled values to expect

The distribution to sample from.

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]].

The number of iterations per scenario. A vector of integers in the same order as scen_name_vec.

A list object representing the output from the calc_comp_var function

A vector representing the expected composition values for which to draw a random observation dataset

A vector object including the composition bins

A vector of the years to simulate data for. default is all years in data_exp if NULL.

A vector of the seasons to simulate data for. default is all seasons in data_exp if NULL.

A vector of the fleets to simulate data for. default is all fleets in data_exp if NULL.

A vector of the genders to simulate data for. default is all genders in data_exp if NULL.

Path to the directory containing the scenarios, either relative or absolute. Defaults to the working directory.

A character vector of scenarios in dir from which to extract summaries. If left as NULL, the summaries will be extracted from all folders in dir.

Option to use parallel processing on iterations. Defaults to FALSE

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)

Allow existing files to be overwritten?

Path to the directory for 1 iteration of 1 scenario.

Path to the directory for 1 scenario, either relative or absolute. Defaults to the working directory.

The original model directory

The new model directory (folder need not exist)

A vector of base parameter values that will be updated to include the impact of a time varying block change

A vector of years for which the base values are needed

The timevarying parameter lines for the block effects on the base parameter

The index of the current parameter being updated

A control file as read in by r4ss::SS_readctl.

A data file as read in by r4ss::SS_readdat.

A subset of the control file representing the parameter section of interest (i.e. MG, SR, Q, or Selectivity)

the difference between the base parameters max and min bounds

The value of the base parameter

The min and max bounds of the base parameter

A vector of base parameter values that will be updated to include the impact of a time varying deviations

The time varying parameter lines for the deviations on the base parameter

A vector of the parameter deviations to be applied to the base values

The index of the current parameter being updated

A subset of the control file representing the parameter section of interest (i.e. MG, SR, Q, or Selectivity)

the difference between the base parameters max and min bounds

The min and max bounds of the base parameter

A vector of base parameter values that will be updated to include the impact of a time varying environmental effects

A vector of years for which the base values are needed

The time varying parameter lines for the environmental effects on the base parameter

The index of the current parameter being updated

The timeseries table from r4ss::SS_output().

A subset of the control file representing the parameter section of interest (i.e. MG, SR, Q, or Selectivity)

A datafile as read in by r4ss::SS_readdat

the difference between the base parameters max and min bounds

The min and max bounds of the base parameter

A parameter file as read in by r4ss::SS_readpar_3.30

The full path to the OM directory.

A dataframe of catch values and its associated information to add to the OM. The column names are the same as in an SS data file (e.g., year, season, fleet, catch, catch_se). Must input either a catch and/or a harvest rate data frame. If both are input the catch will override harvest rate as the management unit but harvest rate will be used as a starting guess for search.

A dataframe of harvest rate (F) values and associated information to add to the OM. The column names are as in an SS datafile. If harvest rate is input without a corresponding catch the OM will assume effort based management an use harvest rate directly with implementation error added.

data frame with columns year, seas, fleet, basis that specifies if catch should reference retained biomass (1) or dead biomass (2). Any year/season/fleet not listed will assume a value of 1 referencing retained biomass. Entering -99 for any of year, season, or fleet will apply the basis across all values of that variable (i.e. a single row with -99, -99, -99, 1 would implement retained biomass for all cases)

data frame with columns year, fleet, season, limit that specifies a maximum F allowed in the OM or a negative value to specify a multiple of the historic maximum F. Any year/season/fleet not listed will assume a value of 1.5. Entering -99 for any of year, season, or fleet will apply the limit across all values of that variable (i.e. a single row with -99, -99, -99, -2 would implement a cap of twice the historic maximum F for all cases)

a dataframe of parameter value updates to modify OM

Should the datafile be overwritten? Defaults to TRUE.

The implementation error

Want verbose output? Defaults to FALSE.

A random seed so that reproducible results are possible.

Number of times to try to find an F that achieves the catches input in the OM. Defaults to 20.

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.