Deviation parameters

9control.tex

@@ -1245,6 +1245,31 @@ \subsubsection{Predator Fleet Mortality}
 
 Simulation studies conducted by \citet{methot-adjusting-2011} compared three methods of tuning $\sigma_R$ with the above approach generally performed best since it accounts for variability among recruitment deviations and the uncertainty in their estimates.
 
+
+\hypertarget{ParmDevs}{}
+\subsubsection[Parameter Deviations]{\protect\hyperlink{ParmDevs}{Parameter Deviations}}
+
+SS3 includes mechanisms for incorporating penalized parameter deviations to model annual variation in certain model parameters that cannot be fully explained by simple time blocks or external environmental drivers. This capability applies to various parameters within the mortality-growth, catchability, and selectivity sections, offering a unified approach across these types.
+
+The core concept is that a time-varying parameter value is realized as the product of its estimated deviations ($d_y$) and a standard deviation parameter ($s$), which is also estimated by the model in version 3.30 and later.
+
+\begin{equation}
+Realized dev_y = d_y \cdot s
+\end{equation}
+
+This formulation uses a non-centered parameterization for parameter deviations, meaning the estimated deviations ($d_y$) are expected to have a mean of 0 and a standard deviation of 1. The non-centered approach is considered more efficient and numerically stable for estimation routines like MCMC and maximum likelihood estimation (MLE).
+
+Parameter deviations are introduced via the parameters' long parameter lines in the control file, primarily using the \hyperlink{DevLink}{Deviation Link} (there are 4 types which are explained in this Deviation Link section), \hyperlink{DevMinYr}{Deviation minimum year}, \hyperlink{DevMaxYr}{Deviation maximum year}, and \hyperlink{DevPhase}{Deviation phase} columns.
+
+\myparagraph{Key Performance and Implementation Notes}
+
+\begin{itemize}
+	\item \textbf{Likelihood Calculation Error:} In SS3 versions v.3.30.00 through v.3.30.12, an error existed in the calculation of the negative log-likelihood for the parameter deviation vector, which incorrectly included a term based on $-log(s)$ ($PLIKE_2$). This often led to the estimate of the standard deviation parameter ($s$) being pulled towards a minimal value. Users of these older versions should re-run estimates of $s$ using version v.3.30.13 or later.
+	\item \textbf{Standard Deviation ($s$):} When the parameter deviations feature is active, the final variance of the realized deviations depends on the combined effect of $s^2$ and the variance of $d_y$. If the data are highly informative and the correct value of $s$ is used, the variance of $d_y$ will be close to 1. For less informative data, it is possible to find $s$ such that the sum of the variance among the deviations ($d_y$) and the mean variance of each deviation ($d_y$) is close to 1.
+	\item \textbf{Advisable Estimation Practice:} Because a penalized likelihood approach like that in SS3 may have a negative bias when directly estimating the standard deviation parameter ($s$), it is advisable to profile on fixed values for $s$ to find a range that yields good results.
+	\item \textbf{Addressing Non-Zero Mean in Deviations:} If the time span for the deviations does not cover all model years, the model might use a non-zero mean in the deviation vector to create a temporal offset to the base parameter (a "block offset"). To counteract this, it can be useful to include a separately estimated block parameter for the same range of years, allowing the deviations to center naturally on zero.
+\end{itemize}
+
 \hypertarget{RecDevSetup}{}
 \subsubsection[Recruitment Deviation Setup]{\protect\hyperlink{RecDevSetup}{Recruitment Deviation Setup}}
 \begin{longtable}{p{1cm} p{3cm} p{12cm}}

tv_parameter_description.tex

@@ -37,8 +37,8 @@
 		\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:
+
+\item \hypertarget{DevLink}{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 (where $dev_{se}$ is the standard deviation parameter $s$) are listed below. Note that options 1-4 give the revised and now correct non-centered approach (as of v.3.30.13). Options 11-14 utilize the incorrect approach from v.3.30.12 and earlier, which should be avoided.
 	\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}$,
@@ -71,11 +71,11 @@
 		 \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 \hypertarget{DevMinYr}{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.
+\item \hypertarget{DevMaxYr}{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 \hypertarget{DevPhase}{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: 
@@ -171,7 +171,7 @@
 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 Parameter deviations: Requires 2 short parameter lines, one for the standard deviation parameter ($s$ or $\text{dev}_{se}$) for the deviations, followed by one for the autocorrelation parameter $\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}