change_tv takes Stock Synthesis .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.

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" for help on specifying this argument.

ctl_file_in

A string providing the path to the input Stock Synthesis .ctl file.

ctl_file_out

A string providing the path to the output Stock Synthesis 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 Stock Synthesis .dat file.

dat_file_out

A string providing the path to the output Stock Synthesis .dat file.

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.

Details

Although there are three ways to implement time-varying parameters within Stock Synthesis, ss3sim and change_tv only use the environmental variable option. Within Stock Synthesis, 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 Stock Synthesis version 3.24f manual for more information.

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

See also

Other change functions: change_data(), change_e(), change_em_binning(), change_f(), change_o(), change_retro()

Author

Kotaro Ono, Carey McGilliard, Kelli F. Johnson, and Kathryn L. Doering

Examples

if (FALSE) { # \dontrun{
# 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_uniform_Fem_GP_1" = c(rep(0, 20), rep(.1, 80)),
      "SR_BH_steep" = stats::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)
} # }