diff --git a/6starter.tex b/6starter.tex index 811d885f..e5ad5c59 100644 --- a/6starter.tex +++ b/6starter.tex @@ -40,7 +40,7 @@ \subsection{Starter File Options (starter.ss)} control\_ file.ctl & & File name of the control file \Tstrut\\ \hline - 0 & Initial Parameter Values: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Do not set equal to 1 if there have been any changes to the control file that would alter the number or order of parameters stored in the ss.par file. Values in ss.par can be edited, carefully. Do not run ss\_trans.exe from a ss.par from SS3 v.3.24.}}\Tstrut\\ + 0 & Initial Parameter Values: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Do not set equal to 1 if there have been any changes to the control file that would alter the number or order of parameters stored in the ss.par file. Values in ss.par can be edited, carefully. Do not run ss\_trans.exe from a ss.par from SS3 v.3.24.}}\Tstrut\\ & 0 = use values in control file; and& \\ & 1 = use ss.par after reading setup in the control file. & \\ @@ -87,12 +87,12 @@ \subsection{Starter File Options (starter.ss)} & 2 = full. & \\ \hline - 1 & Full Priors: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Turning this option on (1) adds the log likelihood contribution from all prior values for fixed and estimated parameters to the total negative log likelihood. With this option off (0), the total negative log likelihood will include the log likelihood for priors for only estimated parameters.}} \Tstrut\\ + 1 & Full Priors: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Turning this option on (1) adds the log likelihood contribution from all prior values for fixed and estimated parameters to the total negative log likelihood. With this option off (0), the total negative log likelihood will include the log likelihood for priors for only estimated parameters.}} \Tstrut\\ & 0 = only calculate priors for active parameters; and & \\ & 1 = calculate priors for all parameters that have a defined prior. & \\ \hline - 1 & Soft Bounds: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{This option creates a weak symmetric beta penalty for the selectivity parameters. This becomes important when estimating selectivity functions in which the values of some parameters cause other parameters to have negligible gradients, or when bounds have been set too widely such that a parameter drifts into a region in which it has negligible gradient. The soft bound creates a weak penalty to move parameters away from the bounds.}} \Tstrut\Bstrut\\ + 1 & Soft Bounds: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{This option creates a weak symmetric beta penalty for the selectivity parameters. This becomes important when estimating selectivity functions in which the values of some parameters cause other parameters to have negligible gradients, or when bounds have been set too widely such that a parameter drifts into a region in which it has negligible gradient. The soft bound creates a weak penalty to move parameters away from the bounds.}} \Tstrut\Bstrut\\ & 0 = omit; and & \\ & 1 = use. & \\ & & \\ @@ -111,7 +111,7 @@ \subsection{Starter File Options (starter.ss)} \hline %\pagebreak - 8 & Turn off estimation: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{The 0 option is useful for (1) quickly reading in a messy set of input files and producing the annotated control.ss\_new and data\_echo.ss\_new files, or (2) examining model output based solely on input parameter values. Similarly, the value option allows examination of model output after completing a specified phase. Also see usage note for restarting from a specified phase.}}\Tstrut\\ + 8 & Turn off estimation: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{The 0 option is useful for (-1) quickly reading in a messy set of input files and producing the annotated control.ss\_new and data\_echo.ss\_new files, or (0) examining model output based solely on input parameter values. Similarly, the value option allows examination of model output after completing a specified phase. Also see usage note for restarting from a specified phase.}} \Tstrut\\ & -1 = exit after reading input files; & \\ & 0 = exit after one call to the calculation routines and production of sso and ss\_new files; and & \\ & = exit after completing this phase. & \Bstrut\\ @@ -124,7 +124,7 @@ \subsection{Starter File Options (starter.ss)} 200 & MCMC thin interval & Number of iterations to remove between the main period of the MCMC run. \Tstrut\\ \hline - 0.0 & \hyperlink{Jitter}{Jitter:} & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{The jitter function has been revised with SS3 v.3.30. Starting values are now jittered based on a normal distribution with the pr(P\textsubscript{MIN}) = 0.1\% and the pr(P\textsubscript{MAX}) = 99.9\%. A positive value here will add a small random jitter to the initial parameter values. When using the jitter option, care should be given when defining the low and high bounds for parameter values and particularly -999 or 999 should not be used to define bounds for estimated parameters.}}\Tstrut\\ + 0.0 & \hyperlink{Jitter}{Jitter:} & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{The jitter function has been revised with SS3 v.3.30. Starting values are now jittered based on a normal distribution with the pr(P\textsubscript{MIN}) = 0.1\% and the pr(P\textsubscript{MAX}) = 99.9\%. A positive value here will add a small random jitter to the initial parameter values. When using the jitter option, care should be given when defining the low and high bounds for parameter values and particularly -999 or 999 should not be used to define bounds for estimated parameters.}}\Tstrut\\ & 0 = no jitter done to starting values; and & \\ & >0 starting values will vary with larger jitter values resulting in larger changes from the parameter values in the control or par file. & \\ & & \\ @@ -142,7 +142,7 @@ \subsection{Starter File Options (starter.ss)} & = end SD report in this year. & \Bstrut\\ \hline - 2 & Extra SD Report Years: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{In a long time series application, the model variance calculations will be smaller and faster if not all years are included in the SD reporting. For example, the annual SD reporting could start in 1960 and the extra option could select reporting in each decade before then.}}\Tstrut\\ + 2 & Extra SD Report Years: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{In a long time series application, the model variance calculations will be smaller and faster if not all years are included in the SD reporting. For example, the annual SD reporting could start in 1960 and the extra option could select reporting in each decade before then.}} \Tstrut\\ & 0 = none; and & \\ & = number of years to read. & \\ & & \\ @@ -153,52 +153,52 @@ \subsection{Starter File Options (starter.ss)} %\pagebreak %\hline - \multicolumn{1}{r}{1940 1950} & \multirow{1}{1cm}[-0.25cm]{\parbox{19.5cm}{Vector of years for additional SD reporting. The number of years need to equal the value specified in the above line (Extra SD Reporting). }} \Tstrut\\ + \multicolumn{1}{r}{1940 1950} & \multirow{1}{1cm}[-0.25cm]{\parbox{19.5cm}{Vector of years for additional SD reporting. The number of years need to equal the value specified in the above line (Extra SD Reporting).}} \Tstrut\\ & & \\ \hline - 0.0001 & Final convergence & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{This is a reasonable default value for the change in log likelihood denoting convergence. For applications with much data and thus a large total log likelihood value, a larger convergence criterion may still provide acceptable convergence}}\Tstrut\Bstrut\\ + 0.0001 & Final convergence & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{This is a reasonable default value for the change in log likelihood denoting convergence. For applications with much data and thus a large total log likelihood value, a larger convergence criterion may still provide acceptable convergence}} \Tstrut\Bstrut\\ & & \Bstrut\\ & & \Bstrut\\ % & & \\ \hline - 0 & Retrospective year: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Adjusts the model end year and disregards data after this year. May not handle time varying parameters completely.}} \Tstrut\\ + 0 & Retrospective year: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Adjusts the model end year and disregards data after this year. May not handle time varying parameters completely.}} \Tstrut\\ & 0 = none; and & \\ & -x = retrospective year relative to end year. & \Bstrut\\ \hline - 0 & Summary biomass min age & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Minimum integer age for inclusion in the summary biomass used for reporting and for calculation of total exploitation rate.}}\Tstrut\\ + 0 & Summary biomass min age & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Minimum integer age for inclusion in the summary biomass used for reporting and for calculation of total exploitation rate.}} \Tstrut\\ & & \\ %\hline \pagebreak - 1 & Depletion basis: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Selects the basis for the denominator when calculating degree of depletion in SB. The calculated values are reported to the SD report.}}\Tstrut\\ + 1 & Depletion basis: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Selects the basis for the denominator when calculating degree of depletion in SB. The calculated values are reported to the SD report.}} \Tstrut\\ & 0 = skip; & \\ - & 1 = X*SB0; & Relative to virgin spawning biomass.\\ - & 2 = X*SB\textsubscript{MSY}; & Relative to spawning biomass that achieves MSY.\\ - & 3 = X*SB\textsubscript{styr}; and & Relative to model start year spawning biomass.\\ - & 4 = X*SB\textsubscript{endyr}. & Relative to spawning biomass in the model end year.\\ + & 1 = X*SB0; & Relative to virgin spawning biomass. \\ + & 2 = X*SB\textsubscript{MSY}; & Relative to spawning biomass that achieves MSY. \\ + & 3 = X*SB\textsubscript{styr}; and & Relative to model start year spawning biomass. \\ + & 4 = X*SB\textsubscript{endyr}. & Relative to spawning biomass in the model end year. \\ & 5 = X*Dynamic SB0 & Relative to the calculated dynamic SB0. \\ & use tens digit (1-9) to invoke multi-year (up to 9 yrs) & \\ & use 1 as hundreds digit to invoke log(ratio) & \Bstrut\\ \hline - 1 & Fraction (X) for depletion denominator & Value for use in the calculation of the ratio for SB\textsubscript{y}/(X*SB0).\Tstrut\Bstrut\\ + 1 & Fraction (X) for depletion denominator & Value for use in the calculation of the ratio for SB\textsubscript{y}/(X*SB0). \Tstrut\Bstrut\\ \hline %\pagebreak - 1 & SPR report basis: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{SPR is the equilibrium SB per recruit that would result from the current year's pattern and intensity of F's. The quantities identified by 1, 2, and 3 here are all calculated in the benchmarks section. Then the one specified here is used as the selected }}\Tstrut\\ + 1 & SPR report basis: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{SPR is the equilibrium SB per recruit that would result from the current year's pattern and intensity of F's. The quantities identified by 1, 2, and 3 here are all calculated in the benchmarks section. Then the one specified here is used as the selected }} \Tstrut\\ & 0 = skip; & \\ & 1 = use 1-SPR\textsubscript{target}; & \\ & 2 = use 1-SPR at MSY; & \Tstrut\\ - & 3 = use 1-SPR at B\textsubscript{target}; and & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Denominator in a ratio with the annual value of (1 - SPR). This ratio (and its variance) is reported to the SD report output for the years selected above in the SD report year selection.}}\Tstrut\\ + & 3 = use 1-SPR at B\textsubscript{target}; and & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Denominator in a ratio with the annual value of (1 - SPR). This ratio (and its variance) is reported to the SD report output for the years selected above in the SD report year selection.}} \Tstrut\\ & 4 = no denominator, so report actual 1-SPR values. & \\ \pagebreak % \hline - 4 & Annual F units: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{In addition to SPR, an additional proxy for annual F can be specified here. As with SPR, the selected quantity will be calculated annually and in the benchmarks section. The ratio of the annual value to the selected (see F report basis below) benchmark value is reported to the SD report vector. Options 1 and 2 use total catch for the year and summary abundance at the beginning of the year, so combines seasons and areas. But if most catch occurs in one area and there is little movement between areas, this ratio is not informative about the F in the area where the catch is occurring. Option 3 is a simple sum of the full F's by fleet, so may provide non-intuitive results when there are multi areas or seasons or when the selectivities by fleet do not have good overlap in age. Option 4 is a real annual F calculated as a numbers weighted F for a specified range of ages (read below). The F is calculated as Z-M where Z and M are each calculated an ln(N\textsubscript{t+1}/N\textsubscript{t}) with and without F active, respectively. The numbers are summed over all biology morphs and all areas for the beginning of the year, so subsumes any seasonal pattern.}}\Tstrut\Bstrut\\ + 4 & Annual F units: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{In addition to SPR, an additional proxy for annual F can be specified here. As with SPR, the selected quantity will be calculated annually and in the benchmarks section. The ratio of the annual value to the selected (see F report basis below) benchmark value is reported to the SD report vector. Options 1 and 2 use total catch for the year and summary abundance at the beginning of the year, so combines seasons and areas. But if most catch occurs in one area and there is little movement between areas, this ratio is not informative about the F in the area where the catch is occurring. Option 3 is a simple sum of the full F's by fleet, so may provide non-intuitive results when there are multi areas or seasons or when the selectivities by fleet do not have good overlap in age. Option 4 is a real annual F calculated as a numbers weighted F for a specified range of ages (read below). The F is calculated as Z-M where Z and M are each calculated an ln(N\textsubscript{t+1}/N\textsubscript{t}) with and without F active, respectively. The numbers are summed over all biology morphs and all areas for the beginning of the year, so subsumes any seasonal pattern.}} \Tstrut\Bstrut\\ & 0 = skip; & \\ & 1 = exploitation rate in biomass; & \\ & 2 = exploitation rate in numbers; & \\ @@ -219,7 +219,7 @@ \subsection{Starter File Options (starter.ss)} \hline %\pagebreak - 1 & F report basis: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Selects the denominator to use when reporting the F std report values. A new option to allow for the calculation of a multi-year trailing average in F was implemented in v. 3.30.16. This option is triggered by appending the number of years to calculate the average across where an input of 1 or 11 would result in the SPR\textsubscript{target} with no changes. Alternatively a value of 21 would calculate F as SPR\textsubscript{target} with a 2-year trailing average.}}\Tstrut\\ + 1 & F report basis: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Selects the denominator to use when reporting the F std report values. A new option to allow for the calculation of a multi-year trailing average in F was implemented in v. 3.30.16. This option is triggered by appending the number of years to calculate the average across where an input of 1 or 11 would result in the SPR\textsubscript{target} with no changes. Alternatively a value of 21 would calculate F as SPR\textsubscript{target} with a 2-year trailing average.}} \Tstrut\\ & 0 = not relative, report raw values; & \\ & 1 = use F std value relative to SPR\textsubscript{target}; & \\ & 2 = use F std value relative to F\textsubscript{MSY}; and & \\ @@ -229,31 +229,31 @@ \subsection{Starter File Options (starter.ss)} \hline %\pagebreak - 0.01 & MCMC output detail: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Specify format of MCMC output. This input requires the specification of two items; the output detail and a bump value to be added to the ln(R0) in the first call to MCMC. A bias adjustment of 1.0 is applied to recruitment deviations in the MCMC phase, which could result in reduced recruitment estimates relative to the MLE when a lower bias adjustment value is applied. A small value, called the ``bump'', is added to the ln(R0) for the first call to MCMC in order to prevent the stock from hitting the lower bounds when switching from MLE to MCMC. If you wanted to select the default output option and apply a bump value of 0.01 this is specified by 0.01 where the integer value represents the output detail and the decimal is the bump value.}} \Tstrut\\ + 0.01 & MCMC output detail: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Specify format of MCMC output. This input requires the specification of two items; the output detail and a bump value to be added to the ln(R0) in the first call to MCMC. A bias adjustment of 1.0 is applied to recruitment deviations in the MCMC phase, which could result in reduced recruitment estimates relative to the MLE when a lower bias adjustment value is applied. A small value, called the ``bump'', is added to the ln(R0) for the first call to MCMC in order to prevent the stock from hitting the lower bounds when switching from MLE to MCMC. If you wanted to select the default output option and apply a bump value of 0.01 this is specified by 0.01 where the integer value represents the output detail and the decimal is the bump value.}} \Tstrut\Bstrut\\ & 0 = default; & \\ - & 1 = output likelihood components and associated lambda values; & \\ - & 2 = write report for each mceval; and & \\ - & 3 = make output subdirectory for each MCMC vector. & \\ - & & \\ - & & \\ + & 1 = output likelihood components and associated lambda values; & \\ + & 2 = write report for each mceval; and & \\ + & 3 = make output subdirectory for each MCMC vector. & \Bstrut\\ + & & \Tstrut\Bstrut\\ + % & & \\ % & & \\ \hline - \hypertarget{ALK}{0} & Age-length-key (ALK) tolerance level, 0 >= values required & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Value of 0 will not apply any compression. Values > 0 (e.g., 0.0001) will apply compression to the ALK which will increase the speed of calculations. The size of this value will impact the run time of your model, but one should be careful to ensure that the value used does not appreciably impact the estimated quantities relative to no compression of the ALK. The suggested value if applied is 0.0001.}} \Tstrut\Bstrut\\ - & & \\ - & & \Tstrut\\ - & & \Tstrut\Bstrut\\ + \hypertarget{ALK}{0} & Age-length-key (ALK) tolerance level, enter 0; & effect is disabled in code. \Tstrut\Bstrut\\ + % \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Value of 0 will not apply any compression. Values > 0 (e.g., 0.0001) will apply compression to the ALK which will increase the speed of calculations. The size of this value will impact the run time of your model, but one should be careful to ensure that the value used does not appreciably impact the estimated quantities relative to no compression of the ALK. The suggested value if applied is 0.0001.}} \Tstrut\Bstrut\\ + % & & \\ + % & & \Tstrut\\ + % & & \Tstrut\Bstrut\\ \hline - \multicolumn{2}{l}{COND: Seed Value (i.e., 1234)}& \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Specify a seed for data generation. This feature is not available in versions prior to 3.30.15. This is an optional input value which allows for the specification of a random number seed value. If you do not want to specify a seed, skip this input line and end the reading of the starter file with the check value (3.30). }} \Tstrut\Bstrut\\ - & & \\ - & & \\ + \multicolumn{2}{l}{COND: Seed Value (i.e., 1234)}& \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{Specify a seed for data generation. This feature is not available in versions prior to 3.30.15 This is an optional input value allowing for the specification of a random number seed value. If you do not want to specify a seed, skip this input line and end the starter file with the check value (3.30).}} \Tstrut\Bstrut\\ + & & \Bstrut\\ & & \Bstrut\\ % & & \\ - \pagebreak +% \pagebreak \hline - \hypertarget{Convert}{3.30} & Model version check value. & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{A value of 3.30 indicates that the control and data files are currently in SS3 v3.30 format and a value of 999 indicates that the control and data file are in a previous SS3 v.3.24 version. The ss\_trans.exe executable should be used and will convert the 3.24 version files to the new format in the control.ss\_new and data\_echo.ss\_new files. All ss\_new files are in the SS3 v.3.30 format, so starter.ss\_new has SS3 v.3.30 on the last line. The mortality-growth parameter section has a new sequence, so SS3 v.3.30 cannot read a ss.par file produced by SS3 v.3.24 and earlier, so please ensure that read par file option at the top of the starter file is set to 0. The \hyperlink{ConvIssues}{Converting Files from SS3 v.3.24} section has additional information on model features that may impede file conversion.}}\Tstrut\Bstrut\\ + \hypertarget{Convert}{3.30} & Model version check value. & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{A value of 3.30 indicates that the control and data files are currently in SS3 v3.30 format and a value of 999 indicates that the control and data files are in a previous SS3 v.3.24 version. The ss\_trans.exe executable should be used and will convert the 3.24 version files to the new format for the control.ss\_new and data\_echo.ss\_new files. All ss\_new files are in the SS3 v.3.30 format, so starter.ss\_new has SS3 v.3.30 on the last line. The mortality-growth parameter section has a new sequence and SS3 v.3.30 cannot read a ss.par file produced by SS3 v.3.24 and earlier, so please ensure that read par file option at the top of the starter file is set to 0. The \hyperlink{ConvIssues}{Converting Files from SS3 v.3.24} section has additional information on model features that may impede file conversion.}} \Tstrut\Bstrut\\ & & \\ & & \\ & & \\