R/change_tv.r
change_tv.Rdchange_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"
)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.
A string providing the path to the input Stock Synthesis .ctl file.
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.
A string providing the path to the input Stock Synthesis .dat file.
A string providing the path to the output Stock Synthesis .dat file.
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.
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.
change_tv_listParameters 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]\)
Other change functions:
change_data(),
change_e(),
change_em_binning(),
change_f(),
change_o(),
change_retro()
if (FALSE) {
# 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)
}