change_tv {ss3sim}

Methods to include time-varying parameters in an SS3 operating model

Description

change_tv takes SS3 .ctl, .par, and .dat files and implements time-varying parameters using environmental variables. change_tv is specifically set up to work with an operating model .ctl file.

Usage

change_tv(change_tv_list, ctl_file_in = "control.ss_new",
  ctl_file_out = "om.ctl", dat_file_in = "ss3.dat",
  dat_file_out = "ss3.dat")

Arguments

change_tv_list

*A list of named vectors. Names correspond to parameters in the operating model that currently do not use environmental deviations and the vectors correspond to deviations. See the section "Specifying the change_tv_list" below for help on specifying this argument.

ctl_file_in

A string providing the path to the input SS .ctl file.

ctl_file_out

A string providing the path to the output SS control file. If the value is NULL, the file will not be written to the disk.

dat_file_in

A string providing the path to the input SS .dat file.

dat_file_out

A string providing the path to the output SS .dat file.

Details

Although there are three ways to implement time-varying parameters within SS3, ss3sim and change_tv only use the environmental variable option. Within SS3, time-varying parameters work on an annual time-step. Thus, for models with multiple seasons, the time-varying parameters will remain constant for the entire year.

The ctl_file_in argument needs to be a .ss_new file because the documentation in .ss_new files are automated and standardized. This function takes advantage of the standard documentation the .ss_new files to determine which lines to manipulate and where to add code in the .ctl, .par, and .dat files, code that is necessary to implement time-varying parameters.

ss3sim uses annual recruitment deviations and may not work with a model that ties recruitment deviations to environmental covariates. If you need to compare the environment to annual recruitment deviations, the preferred option is to transform the environmental variable into an age 0 pre-recruit survey. See page 55 of the SS3 version 3.24f manual for more information.

Value

The function creates modified versions of the .ctl and .dat files if ctl_file_out and dat_file_out are not NULL. The function also returns a list of the modified .ctl and .dat R objects invisibly.

Which arguments to specifiy in case files

All function argument descriptions that start with an asterisk (*) will be passed through the case files to run_ss3sim. If one of these arguments is not specified in a case file, then a value of NULL will be passed, which may or may not be an appropriate value. Other arguments will be ignored if specified.

Specifying the change_tv_list

Parameters will change to vary with time according to the vectors of deviations passed to change_tv_list. Vectors of deviations, also referred to as environmental data, must have a length equal to endyr-startyr+1, where endyr and startyr are specified the .dat file. Specify years without deviations as zero.

Parameter names must be unique and match the full parameter name in the .ctl file. Names for stock recruit parameters must contain "devs", "R0", or "steep", and only one stock recruit parameter can be time-varying per model.

This feature will include an *additive* functional linkage between environmental data and the parameter where the link parameter is fixed at a value of one and the par value is specified in the .par file: par'[y] = par + link * env[y].

For catchability (q) the *additive* functional linkage is implemented on the log scale: ln(q'[y]) = ln(q) + link * env[y]

Passing arguments to change_tv through run_ss3sim

(1) create a case file with an arbitrary letter not used elsewhere (anything but D, E, F, or R) and (2) include the line function_type; change_tv in your case file. For example, you might want to use M for natural mortality, S for selectivity, or G for growth.

Author(s)

Kotaro Ono, Carey McGilliard, Kelli Johnson, and Kathryn Doering

See Also

Other change functions: change_data, change_em_binning, change_e, change_f_par, change_f, change_o, change_retro

Examples

## Not run: 
# Create a temporary folder for the output and set the working directory:
temp_path <- file.path(tempdir(), "ss3sim-tv-example")
dir.create(temp_path, showWarnings = FALSE)
wd <- getwd()
setwd(temp_path)
on.exit(setwd(wd), add = TRUE)

d <- system.file("extdata", package = "ss3sim")
om <- file.path(d, "models", "cod-om")
dir.create("cod-om")
file.copy(om, ".", recursive = TRUE)
setwd("cod-om")

change_tv(change_tv_list =
            list("NatM_p_1_Fem_GP_1" = c(rep(0, 20), rep(.1, 80)),
                 "SR_BH_steep"=rnorm(100, 0, 0.05)),
          ctl_file_in  = "codOM.ctl",
          ctl_file_out = "example.ctl",
          dat_file_in  = "codOM.dat",
          dat_file_out = "example.dat")

# Clean up:
unlink("cod-om", recursive = TRUE)

## End(Not run)