R/change_tv.r
change_tv.Rd
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"
)
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_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]\)
Other change functions:
change_data()
,
change_e()
,
change_em_binning()
,
change_f()
,
change_o()
,
change_retro()
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)
} # }