tv_parameter_description.tex

\hypertarget{SpecTVLong}{}
\subsubsection[Specification of Time-Varying Parameters: Long Parameter Lines]{\protect\hyperlink{SpecTVLong}{Specification of Time-Varying Parameters: Long Parameter Lines}}

Time-varying specifications for a parameter are invoked using elements 8 - 14 in the \hyperlink{paraOrder}{long parameter line setup}. Each element and the options for selection related to time-varying parameters are as described below.

\hypertarget{EnvVar}{}
\begin{itemize}

\item Environmental or Density Dependent Link and variable (env\_var\&link; element 8)

	\begin{itemize}
	   \item The environmental or density dependent link and variable input is two inputs specified using a single three-digit number. The hundreds place contains the option for the link function, while the tens and ones place is used to specify the environmental variable or derived quantity to which the parameter is linked. Note that environmental variables can only be included on an annual basis, so seasonal models would have the same effect applied to all seasons. If the environmental link and variable input is positive, then the parameter is linked to a variable specified in the data file environmental data; if it is negative, then the parameter is linked to a derived quantity. For example, env\_var\&link input 103 would use link type 1 and apply it to environmental data column 3, while the input -103  would use link type 1 and apply it to the ``-3'' column which is ln(relative summary biomass). The other options for both elements are enumerated below.
	   \item The link function options (hundreds place) for the env\_var\&link input are:
	   \begin{itemize}
	       \item 1 = exponential scalar: $P_{y} = P_{base}e^{P_{t}E_{y}}$
		   \item 2 = linear offset: $P_{y} = P_{base} + P_{t}E_{y}$
		   \item 3 = Bounded replacement: $P_{y} = min(P_{base})+\frac{max(P_{base})-min(P_{base})}{1+e^{P_tE_y+ln((P_{base}-min(P_{base})+0.0000001)/(max(P_{base})-P_{base}+0.0000001))}}$
		   \item 4 = Logistic: $P_{y} = P_{base}\frac{2}{1+e^{-P_{t2}(E_{y}-P_{t1})}}$
	   \end{itemize}
		where:
	   \begin{itemize}
	       \item $P_{y}$ = Parameter value in year $y$
           \item $P_{base}$ = Base parameter value
           \item $P_{t}$ = Link parameter value
           \item $P_{t1}$ = First of 2 link parameters (offset)
           \item $P_{t2}$ = Second of 2 link parameters (slope)
           \item $E_{y}$ = Environmental index value or derived quantity value in year $y$
           \item $min(P_{base})$ = the minimum parameter bound of base parameter
           \item $max(P_{base})$ = the maximum parameter bound of base parameter
        \end{itemize}
		\item The variable options (tens and ones place, or $E_{y}$) for the env\_var\&link input are either 1) a positive integer from 1 to 99 referencing a time series located in the \hyperlink{env-dat}{environmental data section} of the data file, or 2) a negative value of -1 to -4 where $E_y$ is one of the following model-derived quantities:
		\begin{itemize}
			\item -1;  for ln(relative spawning biomass)
			\item -2;  for recruitment deviation
			\item -3;  for ln(relative summary biomass) (e.g., current year summary biomass divided by the unfished summary biomass)
			\item -4;  for ln(relative summary numbers)
		\end{itemize}
		\item The four derived quantities are all calculated at the beginning of each year within the model, so they are available to use as the basis for time-varying parameter links without violating any order of operations rules.
	\end{itemize}
	
\item Deviation Link (element 9). A positive integer invokes parameter deviations, but otherwise should be left as 0. SS3 expects the estimated deviations to be normal in distribution and the deviation values are multiplied by the standard error parameter as they are used. This differs from recruitment deviations and from the approach in SS3 v.3.24. Link options for parameter deviations are:
	\begin{itemize}
		\item 1 = multiplicative: $P_y = P_{base,y}e^{\text{dev}_y*\text{dev}_{se}}$,
		\item 2 = additive: $P_y = P_{base,y} + \text{dev}_y*\text{dev}_{se}$,
		\item 3 = random walk. Random walk options are implemented by using $\rho$ in the objective function. $P_y = P_{base,y} + \sum_{n=1}^{y} \text{dev}_n*\text{dev}_{se}$
		\item 4 = mean reverting random walk with $\rho$.
		\begin{itemize}
		    \item $X_1 = \text{dev}_1*\text{dev}_{se}$
			\item $P_1 = P_{base,y} + X_1$
			\item $X_y = \rho*X_{y-1} + \text{dev}_y*\text{dev}_{se}$
			\item $P_y = P_{base,y} + X_y$
		\end{itemize}
		\item 5 = mean reverting random walk with $\rho$ and a logit transformation to stay within the minimum and maximum parameter bounds (approach added in v.3.30.16)
	    \begin{itemize}
		    \item $X_1 = \text{dev}_1*\text{dev}_{se}$
			\item $R = P_{max} - P_{min}$
			\item $Y_1 = ln(\frac{P_{base,y} - P_{min} + \text{nil}}{P_{max} - P_{base,y} + nil})$
			\item $P_1 = P_{min} + \frac{R}{1 + e^{-Y_1 - X_1 }}$. For the first year.
			\item $X_y = \rho*X_{y-1} + \text{dev}_y*\text{dev}_{se}$ 
			\item $Y_y = ln(\frac{P_{base,y} - P_{min} + nil}{P_{max} + P_{base,y} + nil})$
			\item $P_1 = P_{min} + \frac{R}{1 + e^{-Y_y - X_y }}$. For years after the first year.
		\end{itemize}
		\item 6 = mean reverting random walk with penalty to keep the \gls{rmse} near 1.0. Same as case 4, but with penalty applied.
		\item The option of extending the final model year deviation value subsequent years (i.e., into the forecast period) was added in v.3.30.13. This new option is specified by selecting the appropriate deviation link option and appending a 2 at the front (e.g., 25), which will use the final year deviation value for all forecast years.
	\end{itemize}
	where: 
	\begin{itemize}
	     \item $P_{y}$ = Parameter value in year $y$
         \item $P_{base,y}$ = Base parameter value for year $y$
		 \item $\text{dev}_y$ = deviation in year $y$
		 \item $\text{dev}_{se}$ = standard error of the deviation
		 \item nil is a small value (e.g., 0.0000001)
	\end{itemize}
\item Deviation Minimum Year (element 10). Year deviations start for the parameter. This must be specified if using parameter deviations, but otherwise should be left as 0.
	
\item Deviation  Maximum Year (element 11). Year deviations end for parameter. This must be specified if using parameter deviations, but otherwise should be left as 0.
	
\item Deviation Phase (element 12). The phase in which the deviations for the parameter should be estimated. This must be specified if using parameter deviations, but otherwise should be left as 0.
%is there a recommended phase to use if wanting to estimate devs?
	
\item Use Time Blocks or Trends (element 13). Time blocks and trends are both specified using this input. If neither are used, this should be left as 0. For trend options, the cumulative normal distribution function is used as the shape of the trend in all cases, but the parameterization differs. In general, the trend used is: 
    \begin{equation}
	    P_y = P_{base} + P_{\text{offset}}\phi(\frac{y - P_{\text{infl}}}{P_{width}})
	\end{equation}
	where
	\begin{itemize} 
	    \item $P_y$ is the final parameter value in year $y$
		\item $P_{base}$ is the base parameter value
		\item $P_{\text{offset}}$ is the parameter offset value
		\item $\phi$ is the standard cumulative normal distribution function
		\item $P_{\text{infl}}$ is the inflection year (i.e., the year in which half of the total change from the base parameter has occurred)
		\item $P_{width}$ is the standard deviation.
	\end{itemize}
In all cases, 3 parameters are estimated and hence 3 short parameter lines are required. These parameter lines differ amongst the trend options.

The input value options for element 13 are:
	\begin{itemize}
% TODO: add more information about how the above equation relates to theoptions -1 and -3.
		\item > 0: time block index for parameter. See the \hyperlink{timeblocks}{time blocks section} of the control file for more information on specifying time blocks.
		\item -1: Trend Offset option. Three parameters are estimated: end trend value as a logistic offset (input as $ln(P_{\text{offset}})$), inflection year logistic offset (input as $ln(P_{\text{infl}})$), and width ($P_{width}$). Offset trend value is in natural log space. Inflection year is also in natural log space and offset from ln(0.5). Width is directly specified.
		\item -2: Trend Direct input option. In this case, $P_{\text{offset}} = 1$. Three parameters are input via short parameter lines: end trend parameter value ($P_y$ where $y$ is the final year), inflection year ($P_{\text{infl}}$), and width ($P_{width}$). 
		\item -3: Trend Fractional option. In this case, $P_{\text{offset}} = 1$. Three parameters will be estimated: end trend parameter value as a fraction of base parameter maximum - minimum, inflection year as a fraction of end year - start year, and width ($P_{width}$). Width is directly input.
	\end{itemize}
	
\item Time Block Functional Form (element 14). Leave as 0, unless time blocks are used.
	\begin{itemize}
		\item 0: multiplicative parameter ($P_{block} = P_{base}*e^{P_t}$)
		\item 1: additive parameter ($P_{block} = P_{base} + P_t$)
		\item 2: replace parameter ($P_{block} = P_t$)
		\item 3: random walk across blocks ($P_{block} = P_{block,-1} + P_t$)
	\end{itemize}
	where:
	\begin{itemize}
        \item $P_{block}$ = Final parameter value in time block $block$
        \item $P_{base}$ = Base parameter value
		\item $P_{t}$ = Time-varying parameter value for a time block
		\item $P_{block,-1}$ = Final parameter value in the previous time block
     \end{itemize}
\end{itemize}


Code for the deviation link can be found in \href{https://github.com/nmfs-ost/ss3-source-code/blob/main/SS_timevaryparm.tpl}{\texttt{SS\_timevaryparm.tpl}}, search for ``SS\_Label\_Info\_14.3''.

\hypertarget{SpecTVShort}{}
\subsubsection[Specification of Time-Varying Parameters: Short Parameter Lines]{\protect\hyperlink{SpecTVShort}{Specification of Time-Varying Parameters: Short Parameter Lines}}

If a time-varying specification set up in the long parameter lines for a particular section requires additional parameters, short parameter lines need to be created following the long parameter lines for the section (unless \hyperlink{autogen}{autogeneration} is used, which creates short parameter lines in \verb|control.ss\_new| upon running the model). The number of parameter lines required depends on the time-varying parameter specification.

For example, if two parameters were specified to have environmental linkages in the\gls{mg} parameter section, below the \gls{mg} parameters would be two parameter lines (when not auto-generating these lines), which is an environmental linkage parameter for each time-varying base parameter:

\begin{longtable}{p{0.7cm} p{0.7cm} p{0.7cm} p{1cm} p{1.4cm} p{1cm} p{1cm} p{6.7cm}}
	\hline
	   &    &      & Prior & Prior    & Prior &  & \Tstrut\\
	LO & HI & INIT & Value & \gls{sd} & Type  & Phase & Parameter Label \Bstrut\\
	\hline
	\endfirsthead
	
	\hline
	   &    &      & Prior & Prior & Prior &  & \Tstrut\\
	LO & HI & INIT & Value & \gls{sd}    & Type  & Phase & Parameter Label \Bstrut\\
	\hline
	\endhead
	
	\endfoot
	
	\endlastfoot
	
	\multicolumn{7}{l}{COND: Only if \gls{mg} parameters are time-varying} \Tstrut\\
	-99 & 99 & 1 & 0 & 0.01 & 0 & -1 &\#Wtlen\_1\_Fem\_ENV\_add \Tstrut\\
	-99 & 99 & 1 & 0 & 0.01 & 0 & -1 &\#Wtlen\_2\_Fem\_ENV\_add \Bstrut\\
	\hline
\end{longtable}

In Stock Synthesis v.3.30, the time-varying input short parameter lines are organized such that all parameters that affect a base parameter are clustered together with time blocks (or trend) first, then environmental linkages, then parameter deviations. For example, if the \gls{mg} base parameters 3 and 7 had time varying changes, the order would look like:
 
 \begin{center}
 	\begin{longtable}{p{5cm} p{10cm}}
 		\hline
 		\gls{mg} base parameter 3 & Block parameter 3-1 \Tstrut\\
 		& Block parameter 3-2 \\
 		& Environmental link parameter 3-1 \\
 		& Deviation \gls{se} parameter 3 \\
 		& Deviation $\rho$ parameter 3 \Bstrut\\
 		\gls{mg} base parameter 7 & Block parameter 7-1 \\
 		& Deviation \gls{se} parameter 7 \\
 		& Deviation $\rho$ parameter 7 \Bstrut\\
 		\hline	 	                    		
 	\end{longtable}
 \end{center}
 
The number of short parameter lines for each time-varying setup selected depends on the selection options. The \hyperlink{autogen}{autogeneration} feature can be used to figure out which parameter lines are needed. The short parameter lines needed for different time-varying options are:
\begin{itemize}
	\item Environmental Linkages: Requires 1 short parameter line ($P_{t}$), except for link option 4, which requires 2 short parameter lines ($P_{t1}$ and $P_{t2}$).
	\item Parameter deviations: Requires 2 short parameter lines, one for the standard error ($\text{dev}_{se}$), followed by one for $\rho$. Note that an input for $\rho$ is required but only used with random walk options. For the random walk options, $\rho$ can be set at 1 for a random walk with no drift or > 1 for a random walk with drift.
	\item Time Blocks: One parameter for each time block ($P_{t}$) set up in the pattern.
	\item Trends: Requires 3 parameter lines. The interpretation of the parameters differs by the trend option selected, but in general they are a parameter for the final parameter value, a parameter for the inflection point year, and a parameter for the width (i.e., the standard deviation).
\end{itemize}

\hypertarget{ExTVParam}{}
\subsubsection[Example Time-varying Parameter Setups]{\protect\hyperlink{ExTVParam}{Example Time-varying Parameter Setups}}

The time-varying parameter options in Stock Synthesis are flexible. Below are some example setups that illustrate how the time-varying options could be used in a model, although there are many more possible setups.

\myparagraph{Environmental and density dependent linkages}

\begin{itemize}
	\item Suppose growth rate is found to be linked with an index of water temperature. The water temperature proxy could be input into the data file as environmental data. If it is input as index number 1, the growth parameter $K$ (if using a von Bertalanffy growth equation) could be linked to the water temperature proxy data by specifying the code ``201'' in the env\_var\&link function input. This would establish an offset link between the parameter and the temperature proxy. One additional parameter line is required after the ``\gls{mg} parameter'' long parameter lines section.
	\item Suppose for a fishery, selectivity is thought to shift depending on population size. Smaller fish are selected when there are lower population numbers, while larger fish are selected when there are higher population numbers. The selectivity parameter could be made time-varying using the code ``-104'' in the env\_var\&link option, which assumes an exponential scalar link between the base selectivity parameter and the time varying parameter value. One additional parameter line is required at the end of the selectivity long parameter lines section.
\end{itemize}

\myparagraph{Parameter Deviations}

\begin{itemize}
	\item Suppose a selectivity parameter is thought to drift every year during 2000-2010. This could be represented using a random walk link option available within the parameter deviations options. To implement this, the user could input 3 into the ``dev link'' input on the long parameter line for the selectivity parameter, and then input values 2000 and 2010 for ``dev min yr'' and ``dev max yr'', respectively. The dev phase could be set to 3. With this setup, 2 additional short parameter lines would be expected, one for the standard error and one for $\rho$. Both of these will be used since a random walk option is selected. To use a random walk without drift, $\rho$ is set at 1 with a negative phase.
\end{itemize}

\myparagraph{Time Blocks}

\begin{itemize}
	\item Offset approach: One or more time blocks are created and cover all or a subset of the years. Each block gets a parameter that is used as an offset from the base parameter (time block functional form 1). In this situation, typically the base parameter and each of the offset parameters are estimated. In years not covered by blocks, the base parameter alone is used. However, if blocks cover all the years, then the value of the block parameter is completely correlated with the mean of the block offsets, so model convergence and variance estimation could be affected. The recommended approach when using offsets is to not have all years covered by blocks or to fix the base parameter value at a reasonable level when doing offsets for all years.	
	
	\item Replacement approach, Option A: Time blocks are created which cover a subset of the years. The base parameter is used in the non-block years and the value of the base parameter is replaced by the block parameter in each respective block (time block functional form 2). In this situation, typically the base parameter and each of the block parameters are estimated.	
	
	\item Replacement approach, Option B: Replacement time blocks are created for all the years, so the base parameter is simply a placeholder that is always replaced by a block parameter (time block functional form 2). In this situation, do not allow the model to estimate the base parameter and only estimate the corresponding block replacement parameters, otherwise, the search algorithm will be attempting to estimate parameters that do not contribute to the log likelihood, so model convergence and variance estimation could be affected.
\end{itemize}

\myparagraph{Trends}

\begin{itemize}
	\item Suppose natural mortality was thought to increase from 0.1 to 0.2 during 2000 to 2010. This could be input as a trend. First, the natural mortality parameter would be fixed at an initial value of 0.1. Then, a value of -2 could be input into the ``use block'' column of the natural mortality long parameter line to indicate that the direct input option for trends should be used. The long parameter line for $M$ could look like:
	\begin{center}
		\begin{longtable}{p{1cm} p{1cm} p{1cm} p{1.5cm} p{1cm} p{1.5cm} p{1.5cm} p{1.5cm} p{3cm}}
			
			\hline
			LO \Tstrut & HI & INIT & <other entries> & PHASE & <other entries> & Use\_Block & Block Fxn & Parameter Label \Bstrut\\
			\hline
			0          & 4 & 0.1 & \multicolumn{1}{c}{...} & -1 & \multicolumn{1}{c}{...} & -2 & 0 & \#M \Bstrut\\
			\hline
		\end{longtable}
	\end{center}

	\item Three short parameter lines are then expected after the mortality-growth long parameter lines, one for the final value, one for the inflection year and one for the width. The final value could be fixed by using 0.2 as the final value on the short parameter line and a negative phase value. The inflection year could be fixed at 2005 by inputting 2005 for the inflection year in the short parameter line with a negative phase. Finally, the width value (i.e., standard deviation of the cumulative normal distribution) could be set at 3 years. The short parameter lines could look like:
	
	\begin{longtable}{p{0.7cm} p{0.7cm} p{0.7cm} p{1cm} p{1.4cm} p{1cm} p{1cm} p{6.7cm}}
	\hline
	   &    &      & Prior & Prior    & Prior &  & \Tstrut\\
	LO & HI & INIT & Value & \gls{sd} & Type  & Phase & Parameter Label \Bstrut\\
	\hline
	\endfirsthead
	
	\hline
	   &    &      & Prior & Prior    & Prior &  & \Tstrut\\
	LO & HI & INIT & Value & \gls{sd} & Type  & Phase & Parameter Label \Bstrut\\
	\hline
	\endhead
	
	\endfoot
	
	\endlastfoot
	
	0.001 & 4    & 0.2  & 0 & 0.01 & 0 & -1 & \#M\_TrendFinal \Tstrut\\
	1999  & 2011 & 2005 & 0 & 0.01 & 0 & -1 & \#M\_TrendInfl \Bstrut\\
	-99   & 99   & 3    & 0 & 0.01 & 0 & -1 & \#M\_TrendWidth\_yrs \Bstrut\\
	\hline
\end{longtable}
\end{itemize}