From deabeac0652c0e71a7a8ce89defd18107a4c64da Mon Sep 17 00:00:00 2001 From: e-perl-NOAA Date: Fri, 17 Oct 2025 13:23:02 -0400 Subject: [PATCH 1/6] add text about deviation parameters --- 9control.tex | 25 +++++++++++++++++++++++++ tv_parameter_description.tex | 14 +++++++------- 2 files changed, 32 insertions(+), 7 deletions(-) diff --git a/9control.tex b/9control.tex index 7fddb04e..7c4bcd09 100644 --- a/9control.tex +++ b/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} +\end{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{Deviation Variance and 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 $\mathbf{d_y}$. If the data are highly informative and the correct value of $s$ is used, $\text{var}(\mathbf{d_y})$ will be 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$) 12, it is advisable to profile on fixed values for $s$ to find a range that yields good results. A good starting criteria for selection is a value for $s$ such that the sum of the variance among the deviations ($\text{var}(\mathbf{d_y})$) and the mean variance of each deviation ($\text{mean}(\text{var}(\mathbf{d_y}))$) is close to 1. + \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")15. 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 zero16. + \hypertarget{RecDevSetup}{} \subsubsection[Recruitment Deviation Setup]{\protect\hyperlink{RecDevSetup}{Recruitment Deviation Setup}} \begin{longtable}{p{1cm} p{3cm} p{12cm}} diff --git a/tv_parameter_description.tex b/tv_parameter_description.tex index 92611c95..3b83e58a 100644 --- a/tv_parameter_description.tex +++ b/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} From 655a1e058cc2847e79a3c54c0a65b948ac3b73d8 Mon Sep 17 00:00:00 2001 From: e-perl-NOAA Date: Fri, 17 Oct 2025 13:29:13 -0400 Subject: [PATCH 2/6] fix --- 9control.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/9control.tex b/9control.tex index 7c4bcd09..72f93066 100644 --- a/9control.tex +++ b/9control.tex @@ -1264,11 +1264,11 @@ \subsubsection{Predator Fleet Mortality} \myparagraph{Key Performance and Implementation Notes} \begin{itemize} -\end{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{Deviation Variance and 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 $\mathbf{d_y}$. If the data are highly informative and the correct value of $s$ is used, $\text{var}(\mathbf{d_y})$ will be 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$) 12, it is advisable to profile on fixed values for $s$ to find a range that yields good results. A good starting criteria for selection is a value for $s$ such that the sum of the variance among the deviations ($\text{var}(\mathbf{d_y})$) and the mean variance of each deviation ($\text{mean}(\text{var}(\mathbf{d_y}))$) is close to 1. \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")15. 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 zero16. +\end{itemize} \hypertarget{RecDevSetup}{} \subsubsection[Recruitment Deviation Setup]{\protect\hyperlink{RecDevSetup}{Recruitment Deviation Setup}} From 3733db3bed82fed6dc354ef1294c7fa00bc96945 Mon Sep 17 00:00:00 2001 From: e-perl-NOAA Date: Fri, 17 Oct 2025 13:30:10 -0400 Subject: [PATCH 3/6] remove unnecessary numbers --- 9control.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/9control.tex b/9control.tex index 72f93066..b6356480 100644 --- a/9control.tex +++ b/9control.tex @@ -1266,8 +1266,8 @@ \subsubsection{Predator Fleet Mortality} \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{Deviation Variance and 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 $\mathbf{d_y}$. If the data are highly informative and the correct value of $s$ is used, $\text{var}(\mathbf{d_y})$ will be 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$) 12, it is advisable to profile on fixed values for $s$ to find a range that yields good results. A good starting criteria for selection is a value for $s$ such that the sum of the variance among the deviations ($\text{var}(\mathbf{d_y})$) and the mean variance of each deviation ($\text{mean}(\text{var}(\mathbf{d_y}))$) is close to 1. - \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")15. 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 zero16. + \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. A good starting criteria for selection is a value for $s$ such that the sum of the variance among the deviations ($\text{var}(\mathbf{d_y})$) and the mean variance of each deviation ($\text{mean}(\text{var}(\mathbf{d_y}))$) is close to 1. + \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}{} From 2b59569e78d7e5783fffcd6aaa53b769ae9ac32f Mon Sep 17 00:00:00 2001 From: e-perl-NOAA Date: Fri, 17 Oct 2025 14:01:03 -0400 Subject: [PATCH 4/6] better wording --- 9control.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/9control.tex b/9control.tex index b6356480..8fea82f8 100644 --- a/9control.tex +++ b/9control.tex @@ -1265,8 +1265,8 @@ \subsubsection{Predator Fleet Mortality} \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{Deviation Variance and 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 $\mathbf{d_y}$. If the data are highly informative and the correct value of $s$ is used, $\text{var}(\mathbf{d_y})$ will be 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. A good starting criteria for selection is a value for $s$ such that the sum of the variance among the deviations ($\text{var}(\mathbf{d_y})$) and the mean variance of each deviation ($\text{mean}(\text{var}(\mathbf{d_y}))$) is close to 1. + \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} From 3a8c070bb2e8acdc58226ca0fbec9ba13dd4a843 Mon Sep 17 00:00:00 2001 From: Elizabeth Perl Date: Fri, 17 Oct 2025 14:45:56 -0400 Subject: [PATCH 5/6] Update 9control.tex Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- 9control.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/9control.tex b/9control.tex index 8fea82f8..4783d45d 100644 --- a/9control.tex +++ b/9control.tex @@ -1249,7 +1249,7 @@ \subsubsection{Predator Fleet Mortality} \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 +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. From 9b30e06a5200fbc5b531f0a8b2b1292423e3bfee Mon Sep 17 00:00:00 2001 From: Elizabeth Perl Date: Fri, 17 Oct 2025 14:46:10 -0400 Subject: [PATCH 6/6] Update 9control.tex Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- 9control.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/9control.tex b/9control.tex index 4783d45d..a0e5c649 100644 --- a/9control.tex +++ b/9control.tex @@ -1247,7 +1247,7 @@ \subsubsection{Predator Fleet Mortality} \hypertarget{ParmDevs}{} -\subsubsection[Parameter Deviations]{\protect\hyperlink{ParmDevs}{Parameter Deviations}}. +\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.