9control.tex

\hypertarget{ControlFile}{}
\section[Control File]{\protect\hyperlink{ControlFile}{Control File}}
\hypertarget{OverviewControl}{}
\subsection[Overview of Control File]{\protect\hyperlink{OverviewControl}{Overview of Control File}}
These listed model features are denoted in the control file in the following order:
	\begin{enumerate}
		\item Number of growth patterns and platoons
		\item Design matrix for assignment of recruitment to area/settlement event/growth pattern
		\item Design matrix for movement between areas
		\item Definition of time blocks that can be used for time-varying parameters
		\item Controls far all time-varying parameters
		\\
		\item Specification for growth and fecundity
		\item Natural mortality growth parameters, weight-at-length, maturity, and fecundity, for each sex 
		\item Hermaphroditism parameter line (if used)
		\item Recruitment distribution parameters for each area, settlement event, and growth pattern
		\item Cohort growth deviation
		\item Movement between areas (if used)
		\item Age error parameter line (if used)
		\item Catch multiplier (if used)
		\item Fraction female 
		\item Setup for any mortality-growth parameters are time-varying
		\item Seasonal effects on biology parameters
		\\
		\item Spawner-recruitment parameters
		\item Setup for any stock recruitment parameters are time-varying
		\item Recruitment deviations
		\\
		\item $F$ ballpark value in specified year
		\item Method for calculating fishing mortality ($F$)
		\item Initial equilibrium $F$ for each fleet
		\\
		\item Catchability (Q) setup for each fleet and survey
		\item Catchability parameters
		\item Setup for any catchability parameters are time-varying
		\\
		\item Length selectivity, retention, discard mortality setup for each fleet and survey
		\item Age selectivity setup for each fleet and survey
		\item Parameters for length selectivity, retention, discard mortality for each fleet and survey
		\item Parameters for age selectivity, retention, discard mortality for each fleet and survey
		\item Setup for any selectivity parameters that are time-varying
		\\
		\item Tag-recapture parameters
		\\
		\item Variance adjustments
		\item Lambdas for likelihood components
	\end{enumerate}
The order in which they appear in the control file has grown over time rather opportunistically, so it may not appear particularly logical at this time, especially various aspects of recruitment distribution and growth. 
% When the same information is entered via the SS3 GUI, it is organized more logically and then written in this form to the text control file.

\hypertarget{ParameterLine}{}
\subsection[Parameter Line Elements]{\protect\hyperlink{ParameterLine}{Parameter Line Elements}}
The primary role of the control file is to define the parameters to be used by the model. The general syntax of the 14 elements of a long parameter line is described here. If used, time-varying parameter lines use only the first seven elements of a parameter line and will be referred to as a short parameter line. Three types of time-varying properties can be applied to a base parameter: blocks or trend, environmental linkage, and random deviation. Each parameter line contains:

\hypertarget{Priors}{} \hypertarget{paraOrder}{}
\begin{center}
	\begin{tabular}{p{2cm} p{3cm} p{10cm}}
		\hline
		Column & Element & Description \Tstrut\Bstrut\\
		\hline
		1 & LO & Minimum value for the parameter \Tstrut\\
		2 & HI & Maximum value for the parameter \Tstrut\\
		3 \Tstrut & INIT & Initial value for the parameter. If the phase (described below) for the parameter is negative the parameter is fixed at this value. If the \texttt{ss3.par} file is read, it overwrites these INIT values.\\
		4 \Tstrut & PRIOR & Expected value for the parameter. This value is ignored if the prior type is 0 (no prior) or 1 (symmetric beta). If the selected prior type (described below) is log-normal, this value is entered in natural log space. \\
		5 \Tstrut & PRIOR \gls{sd} & \gls{sd} for the prior, used to calculate likelihood of the current parameter value. This value is ignored if prior type is 0. The \gls{sd} is in regular space regardless of the prior type. \\
		6 \Tstrut & \hyperlink{PriorDescrip}{PRIOR TYPE} & 0 = none; \\
		& & 1 = symmetric beta; \\
		& & 2 = full beta; \\
		& & 3 = log-normal without bias adjustment; \\
		& & 4 = log-normal with bias adjustment; \\
		& & 5 = gamma; and \\
		& & 6 = normal. \\
		7 \Tstrut & PHASE & Phase in which parameter begins to be estimated. A negative value causes the parameter to retain its INIT value (or value read from the \texttt{ss3.par} file). \Bstrut\\
		8 \Tstrut & Env var \& Link & Create a linkage to an input environmental time series \\
		9 \Tstrut & Dev link & Invokes use of the deviation vector in the linkage function \\
		10 \Tstrut & Dev min yr & Beginning year for the deviation vector \\
		11 \Tstrut & Dev max yr & Ending year for the deviation vector \\
		12 \Tstrut & Dev phase & Phase for estimation for elements in the deviation vector \\
		13 \Tstrut & Block & Time block or trend to be applied \\
		14 \Tstrut & Block function & Functional form for the block offset. \Bstrut\\
		\hline
	\end{tabular}
\end{center}

Note that relative to Stock Synthesis v.3.24, the order of PRIOR \gls{sd} and PRIOR TYPE have been switched and the PRIOR TYPE options have been renumbered.

The full parameter line (14 in length) syntax for the mortality-growth, spawn-recruitment, catchability, and selectivity sections provides additional controls to give the parameter time-varying properties. If a parameter (a full parameter line of length 14) is set up to be time-varying (i.e., parameter time blocks, annual deviations), short parameter lines, the first 7 elements, are required to be specified immediately after the main parameter block (i.e., mortality-growth parameter section). Additional information regard time-varying parameters and how to implement them is in the \hyperlink{TVpara}{Using Time-Varying Parameters} section.

\hypertarget{ControlTerminology}{}
\subsection[Terminology]{\protect\hyperlink{ControlTerminology}{Terminology}}
The term COND appears in the ``Typical Value'' column of this documentation (it does not actually appear in the model files), it indicates that the following section is omitted except under certain conditions, or that the factors included in the following section depend upon certain conditions. In most cases, the description in the definition column is the same as the label output to the ss\_new files.

\hypertarget{ControlInputs}{}
\subsection[Beginning of Control File Inputs]{\protect\hyperlink{ControlInputs}{Beginning of Control File Inputs}}
\begin{center}
	\begin{longtable}{p{0.5cm} p{2cm} p{12.5cm}}
		\hline
		\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
		\hline
		\endfirsthead

		\hline
		\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
		\hline
		\endhead

		\hline
		\endfoot

		\endlastfoot

		\#C \Tstrut & comment & Comments beginning with \#C at the top of the file will be retained and included in output. \Bstrut\\
		\hline

		0 & & 0 = Do not read the weight-at-age (\texttt{wtatage.ss}) file; \Tstrut\\
		  & & 1 = Read the weight-at-age (\texttt{wtatage.ss}) file, also read and use the growth parameters; and \\
		  & & 2 = Future option to read the weight-at-age (\texttt{wtatage.ss}) file, then omit reading and using growth parameters and all length-based data. \\
		  & & Additional information on the weight-at-age file and the expected formatting can be found in the \hyperlink{WAA}{Empirical Weight-at-Age} section. \Bstrut\\

		%\hline
		\pagebreak
		1 & & Number (N) of growth patterns (GP), also referred to as morphs: \Tstrut\\
		& & These are collections of fish with unique biological characteristics (growth, mortality, weight-length, reproduction). The GP $\times$ Sex $\times$ Settlement Events constitute unique growth patterns that are tracked in SS3. They are assigned these characteristics at birth and retain them throughout their lifetime. At recruitment, growth pattern members are distributed across areas (if any) and they retain their biological characteristics even if they move to another area in which a different cohort with different biological characteristics might predominate. For example, one could assign a fast-growing growth pattern to recruit predominately in a southern area and a slow-growing growth pattern to a northern area. The natural mortality and growth parameters are specified for each growth pattern in the mortality-growth parameter section in the order of female growth pattern 1 to growth pattern N followed by male growth pattern 1 to growth pattern N in a two sex model. \Bstrut\\

		\hline
		1 & & Number of platoons within a growth pattern/morph: \Tstrut\\
		& & This allows exploration of size-dependent survivorship. A value of 1 will not create additional platoons. Odd-numbered values (i.e., 3, 5) will break the overall morph into that number of platoons creating a smaller, larger, and mean growth platoon. The higher the number of platoons the slower the model will run, so values above 5 not advised. The fraction of each morph assigned to each platoon is custom-input or designated to be a normal approximation. When multiple platoons are designated, an additional input is the ratio of between platoon to within platoon variability in size-at-age. This is used to partition the total growth variability. For the platoons, their size-at-age is calculated as a factor (determined from the between-within variability calculation) times the size-at-age of the central morph which is determined from the growth parameters for that Growth Pattern $\times$ Sex. \Bstrut\\

		\multicolumn{2}{l}{COND > 1} & \multicolumn{1}{l}{\parbox{12cm}{Following 2 lines are conditional on N platoons > 1.}} \Tstrut\Bstrut\\

		& 0.7 & Platoon within/between standard deviation ratio. Ratio of the amount of variability in length-at-age within platoons to between platoons so that a small ratio means that the platoons are narrower and more widely spaced. A parameter (after movement parameters) is needed if the within/between standard deviation ratio is negative. \Bstrut\\

		& 0.2 0.6 0.2 & Distribution among platoons. Enter either a custom vector or enter a vector of length N with the first value of -1 to get a normal approximation: (0.15, 0.70, 0.15) for 3 platoons, or 5 platoons (0.031, 0.237, 0.464, 0.237, 0.031). \Bstrut\\
		\hline
	\end{longtable}
	\vspace*{-\baselineskip}
\end{center}

\hypertarget{WatA}{}
\subsubsection[Weight-at-Age]{\protect\hyperlink{WatA}{Weight-at-Age}}
The capability to read empirical body weight-at-age for the population and each fleet was added starting in v.3.04, in lieu of generating these weights internally from the growth parameters, weight-at-length, and size-selectivity. The values are read from a separate file named, \texttt{wtatage.ss}. This file is only required to exist if this option is selected. See the \hyperlink{WAA}{Empirical Weight-at-Age} section for additional information on file formatting for empirical weight-at-age.

\hypertarget{SettlementTiming}{}
\subsubsection[Settlement Timing for Recruits and Distribution]{\protect\hyperlink{SettlementTiming}{Settlement Timing for Recruits and Distribution}}
In older versions of SS3 one value of spawning biomass was calculated annually at the beginning of one specified spawning season and this spawning biomass produced one annual total recruitment value. The annual recruitment value was then distributed among seasons, areas, and growth types according to other model parameters.

Additional control of the seasonal timing was added in v.3.30 and now there is an explicit elapsed time between spawning and recruitment. Spawning still occurs, just once per year, which defines a single spawning biomass for the stock-recruitment curve, but its timing can be at any specified time, not just the beginning of a season. Recruitment of the progeny from an annual spawning can now enter the population in one or more settlement events, at some point after spawning as defined by the user.

\begin{center}
	\begin{longtable}{p{1.25cm} p{1.25cm} p{1cm} p{11.5cm}}
		\hline
		\multicolumn{2}{l}{Typical Value} & \multicolumn{2}{l}{Description and Options} \Tstrut\Bstrut\\
		\hline
		\endfirsthead
		
		\hline
		\multicolumn{2}{l}{Typical Value} & \multicolumn{2}{l}{Description and Options} \Tstrut\Bstrut\\
		\hline
		\endhead
		
		\hline
		\endfoot
		
		\endlastfoot
		
		1 & & \multicolumn{2}{l}{\parbox{12.5cm}{Recruitment distribution method. This section controls which combinations of growth pattern $\times$ area $\times$ settlement will get a portion of the total recruitment coming from each spawning. Options:}} \Tstrut\\
		& & \\
		% & & \\
		& & \multicolumn{2}{l}{\parbox{12.5cm}{1 = no longer available (used the Stock Synthesis v.3.24 or earlier setup);}} \\
		& & \multicolumn{2}{l}{\parbox{12.5cm}{2 = main effects for growth pattern, settle timing, and area;}} \\
		& & \multicolumn{2}{l}{\parbox{12.5cm}{3 = each settle entity; and}} \\
		& & \multicolumn{2}{l}{\parbox{12.5cm}{4 = none, no parameters (only if growth pattern $\times$ settlement $\times$ area = 1).}} \Tstrut\Bstrut\\
		
		\hline
		1 & & \multicolumn{2}{l}{Spawner-Recruitment (not implement yet, but required), options:} \Tstrut\\
		& & \multicolumn{2}{l}{1 = global; and} \\
		& & \multicolumn{2}{l}{\parbox{12.5cm}{2 = by area (by area is not yet implemented; there is a conceptual challenge to doing the equilibrium calculation when there is fishing).}} \\
		& & \\
		
		\hline
		1 & & \multicolumn{2}{l}{\parbox{12.5cm}{Number of recruitment settlement assignments. Must be at least 1 even if only 1 settlement and 1 area because the timing of that settlement must be specified.}} \Tstrut\Bstrut\\ 
		& & \\
		
		\hline
		0 \Tstrut & & \multicolumn{2}{l}{Future feature, not implement yet but required.} \Bstrut\\
		
		\hline
		Growth Pattern & Month & Area & Age at settlement \Tstrut\\
		\hline
		1 & 5.5 & 1 & 0 \Bstrut\\
		\hline
	\end{longtable}
	\vspace*{-\baselineskip}
\end{center}


The above example specifies settlement to mid-May (month 5.5). Note that normally the calendar age at settlement is 0 if settlement happens between the time of spawning and the end of that year, and at age 1 if settlement is in the year after spawning. 

Below is an example setup where there are multiple settlement events, with one occurring the following year after spawning: 
\begin{center}
	\vspace*{-\baselineskip}
	\begin{tabular}{p{3cm} p{3cm} p{2cm} p{7cm}}
		\hline
		3 & \multicolumn{3}{l}{Number of recruitment settlement events} \Tstrut\\
		0 & \multicolumn{3}{l}{Unused option} \Bstrut\\
		\hline
		Growth Pattern & Month & Area & Age (for each settlement assignment) \Tstrut\Bstrut\\
		\hline
		1 & 11.0 & 1 & 0 \Tstrut\\
		1 & 12.0 & 1 & 0 \\
		1 & 1.0 & 1 & 1 \Bstrut\\
		\hline
	\end{tabular}		
\end{center}

%\myparagraph{Recruitment Timing and Settlement}
Details regarding settlement of recruits and timing:
	\begin{itemize}
		\item Recruitment happens in specified settlement events (growth pattern, month, area).
		\item Number of unique settlement timings is calculated at runtime.
		\item Now there is explicit elapsed time between spawning and recruitment.
		\item Growth and natural mortality of the platoon begins at time of settlement, which is its real age 0.0 for growth; but pre-settlement fish exist from the beginning of the season of settlement, so can be caught if selected.
		\item Age at recruitment now user-controlled (should be 0 if in year of spawning).
		\item All fish become integer age 1 (for age determination) on their first January 1st.
		\item Recruitment can occur > 12 months after spawning which is achieved by setting the settlement age to a value greater than 1.0.		
	\end{itemize}

The distribution of recruitment among these settlement events is controlled by recruitment apportionment parameters. There must be a parameter line for each growth pattern, then for each area, then for each settlement. All of these are required, but only those growth pattern $\times$ area $\times$ settlements designated to receive recruits in the recruitment design matrix will have the parameter used in the recruitment distribution calculation. For the recruitment apportionment, the parameter values are the natural log of apportionment weight. The sum of all apportionment weights is calculated for each growth pattern $\times$ area $\times$ settlements that have been designated to receive recruits in the recruitment design matrix. Then the apportionment weights are scaled to sum to 1.0 so that the total recruitment from the spawning event is distributed among the cells designated to receive recruitment. Additionally, these distribution parameters can be time-varying, so the fraction of the recruits that occur in a particular growth pattern, area, or settlement can change from year to year. To specify annual variation in the distribution or recruits by area add a start and end year in the deviation min year and max year columns. Similar to the apportionment of recruits by area, one should be fixed while the other area(s) can deviate relative to the one area. If annual deviations are specified then two additional short parameter lines will be required to specify the standard error and the autocorrelation for each area with deviations.

\hypertarget{recdist}{}
\myparagraph{Recruitment Distribution and Parameters}
Recruits are apportioned according to:

\begin{equation}
	\text{apportionment}_i = \frac{e^{p_i}}{\sum_{i=1}^{N}e^{p_i}}
\end{equation}

where $p_i$ is the proportion of recruits to area $i$ and $N$ is the number of settlement events. These parameters are defined in the mortality-growth parameter section.

Tips for fixing or estimating the recruitment apportionment:
\begin{itemize}
	
	\item Set the value for one of these parameters, $p_i$, to 0.0 and not estimate it so that other parameters will be estimated (if not fixed) relative to its fixed value.
	
	\item Give the estimated parameters a min-max so they have a good range relative to the base parameter (i.e., of min = -5 and max = 5).
	
	\item In order to get a different distribution of recruitments in different years, you will need to make at least one of the recruitment distribution parameters time-varying.

\end{itemize}	

In a seasonal model, all cohorts graduate to the age of 1 when they first reach January 1, even if the seasonal structure of the model has them being spawned in the late fall. In general, this means that the model operates under the assumption that all age data have been adjusted so that fish are age 0 at the time of spawning and all fish graduate to the next age on January 1. This can be problematic if the ageing structures deposit a ring at another time of year. Consequently, you may need to add or subtract a year to some of your age data to make it conform to the model expected data structure, or more ideally you may need to define the calendar year within the model to start at the beginning of the season at which ring deposition occurs. Talk with your ageing lab about their criteria for seasonal ring deposition.
		
Seasonal recruitment is coded to work smoothly with growth. If the recruitment occurring in each season is assigned the same growth pattern, then each seasonal cohort's growth trajectory is simply shifted along the age/time axis. At the end of the year, the early born cohorts will be larger, but all are growing with the same growth parameters, so all will converge in size as they approach their common maximum length (e.g., no seasonal effects on growth).
	
At the time of settlement, fish are assigned a size equal to the lower edge of the first population size bin, and they grow linearly until they reach the age A1. A warning is generated if the first population length bin is greater than 10 cm as this seems an unreasonably large value for a larval fish. A1 is in terms of real age elapsed since birth. All fish advance to the next integer age on January 1, regardless of birth season. For example, consider a 2 season model with some recruitment in each season and with each season's recruits coming from the same GP. At the end of the first year, the early born fish will be larger but both of the seasonal cohorts will advance to an integer age of 1 on Jan 1 of the next year. The full growth curve is still calculated below A1, but the size-at-age used is the linear replacement. Because the linear growth trajectory can never go negative, there is no need for the additive constant to the standard deviation (necessary for the growth model used in SS2 V1.x), but the option to add a constant has been retained in the model.

\hypertarget{Movement}{}
\subsubsection[Movement]{\protect\hyperlink{Movement}{Movement}}
Here the movement of fish between areas are defined. This is a box transfer with no explicit adjacency of areas, so fish can move from any area to any other area in each time step. While not incorporated yet, there is a desire for future versions of SS3 to have the capability to allow sex-specific movement, and also to allow some sort of mirroring so that sexes and growth patterns can share the same movement parameters if desired.

\begin{longtable}{p{0.5cm} p{2cm} p{12.5cm}}
	\hline
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endfirsthead

	\hline
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endhead

	\hline
	\endfoot

	\endlastfoot
	
	\multicolumn{3}{l}{COND: only if areas > 1} \Tstrut\\ 
	& 2 & Enter Number of movement definitions. \Tstrut\\		
	\Tstrut & 1.0 & First age that moves. This value is a real number, not an integer, to allow for an in-year start to movement in a multi-season model. It is the real age at the beginning of a season, even though movement does not occur until the end of the season. For example, in a setup with two 6-month seasons a value of 0.5 will cause the age 0 fish to not move when they complete their first 6-month season of life, and then to move at the end of their second season because they start movement capability when they reach the age of 0.5 years (6 months). \\

	\Tstrut & 1 1 1 2 4 10 & \multicolumn{1}{l}{\multirow{5}{6cm}{\parbox{12cm}{Movement definitions: season, growth pattern, source area, destination, age1, and age2. The example shown here has 1 growth patterns and 2 areas with fish moving between the two areas. The rate of movement will be controlled by the movement parameters later defined in the mortality-growth parameter section. Here the age1 and age2 specify the range over which the movement parameters are interpolated with movement constant below age1 and above age2.}}} \\
	& 1 2 2 1 4 10 & \Bstrut\\
	\\
	\\
	\\
	\\ 
	\\
	\hline
	\end{longtable}
	\vspace*{-\baselineskip}
	

Two parameters will be entered later for each growth pattern, area pair, and season.
\begin{itemize}
	\item Movement is constant at the first parameter (P1) below the specified minimum age for movement change, constant at the second parameter (P2) above maximum age for movement change, and linearly interpolated for intermediate ages.
	\item A movement rate parameter can be set to use the same value as the corresponding parameter for the first defined movement pattern by entering a parameter value of -9999 and a negative phase value.
	\item For each source area, the implicit movement parameter value is 0.0 (movement within a single area). However, this default value can be replaced if the stay movement is selected to have an explicit pair of parameters (e.g., specify movement rate for area 1 to area 1) and will require additional parameter lines.
	\item A constant movement rate across all ages can be accomplished by either:
	\begin{itemize}
		\item Setting both movement ages to 0, not estimating the first movement parameter, and using a second movement parameter to cover all ages from 0 to the maximum number of ages.
		\item Setting movement ages to any value, estimating the first movement parameter, and setting the second movement parameter to have a value of -9998 with a negative phase.
	\end{itemize} 
	\item The parameter is exponentiated so that a movement parameter value of 0 becomes 1.0.
	\item For each source area, all movement rates are then summed and divided by this sum so that 100\% of the fish are accounted for in the movement calculations.
	\begin{equation}
	\text{rate}_i = \frac{e^{p_i}}{\sum_{j=1}^{N}e^{p_i}}
	\end{equation}
	\item At least one movement parameter must be fixed so that all other movement parameters are estimated relative to it. This is achieved naturally by not specifying the stay rate parameter, so it has a fixed value of 0.0.
	\item The resultant movement rates are multiplied by season duration in a seasonal model.	
\end{itemize}

\hypertarget{timeblocks}{}
\subsubsection[Time Blocks]{\protect\hyperlink{timeblocks}{Time Blocks}}
	
\begin{longtable}{p{0.5cm} p{2cm} p{12.5cm}}
		\hline
		\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
		\hline
		\endfirsthead
		
		3 \Tstrut & & \multirow{1}{4cm}[-0.1cm]{\parbox{12.5cm}{Number of block patterns. These patterns can be referred to in the parameter sections to create a separate parameter value for each block.}} \Bstrut\\
		\\

		\hline
		\multicolumn{2}{l}{COND > 0:} \Tstrut & \multicolumn{1}{l}{Following inputs are omitted if the number of block patterns equals 0.} \\
		& \multirow{1}{2cm}[-0.1cm]{3 2 1} & Blocks per pattern: \Bstrut\\

		& \multirow{1}{2cm}[-0.1cm]{1975 1985 1986 1990 1995 2001} & \multirow{3}{12.5cm}[-0.1cm]{Beginning and ending years for blocks in design 1; years not assigned to a block period retain the baseline value for a parameter that uses this pattern.} \Bstrut\\
		\\
		\Bstrut\\
		% \\
		& \multirow{1}{2cm}[-0.1cm]{1987 1990 1995 2001} & \multirow{1}{12.5cm}[-0.1cm]{Beginning and ending years for blocks in design 2.} \Bstrut\\
		\\
		% \\
		& \multirow{1}{2cm}[-0.1cm]{1999 2002} & \multirow{1}{12.5cm}[-0.10cm]{Beginning and ending years for blocks in design 3.} \Bstrut\\
		\hline
\end{longtable}
\vspace*{-\baselineskip}

Blocks and other time-vary parameter controls are operative during forecast years, so care should be taken when setting the end year of the last block in a pattern. If that end year is set to the last year in the time series, then the parameter will revert to the base value for the forecast. If the user wants to continue the last block through the forecast, it is advisable to set the last block's end year value to -2 to cause SS3 to reset it to the last year of the forecast. Using the value -1 will set the block's end year to the last year of the time series and leave the forecast at the base parameter value. Note that additional controls on time-varying parameters in forecast years are in the forecast section.

\hypertarget{autogen}{}
\subsubsection[Auto-generation]{\protect\hyperlink{autogen}{Auto-generation}}
Auto-generation is a useful way to automatically create the required short time-varying parameter lines which will be written in the \texttt{control.ss\_new} file. These parameter lines can then be copied into the control file and modified as needed. As example, if you want to add a block to natural mortality, modify the block and block function entry of the mortality parameter line, ensure that auto-generation is set to 0 (for the biology section at least) and run the model without estimation. The \texttt{control.ss\_new} file will now show the required block parameter line specification for natural mortality and this line can be copied into the main control file. Note, that if auto-generation is on (set to 0), the model will not expect to read the time-varying parameters in that section of the control file and will error out if they are present

	
\begin{longtable}{p{0.5cm} p{2cm} p{12.5cm}}
	\hline
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endfirsthead

	\hline
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endhead

	\hline
	\endfoot

	\endlastfoot

	1 & & Environmental/Block/Deviation adjust method for all time-varying parameters. \Tstrut\\
	  & & 1 = warning relative to base parameter bounds; and \\
	  & & 3 = no bound check. Logistic bound check form from previous SS3 versions (e.g., v.3.24) is no longer an option. \Bstrut\\

	\multicolumn{2}{l}{1 1 1 1 1} & Auto-generation of time-varying parameter lines. Five values control auto-generation for parameter block sections: 1-biology, 2-spawn-recruitment, 3-catchability, 4-tag (future), and 5-selectivity. \\
	& 			& The accepted values are: \\
	& 			& 0 = auto-generate all time-varying parameters (no time-varying parameters are expected); \\
	& 			& 1 = read each time-varying parameter line as exists in the control file; and \\
	&			& 2 = read each line and auto-generate if read the time-varying parameter value for LO = -12345. Useful to generate reasonable starting values. \Bstrut\\
	\hline
\end{longtable}

\hypertarget{Biology}{}
\subsection[Biology]{\protect\hyperlink{Biology}{Biology}}
\hypertarget{NatM}{}
\subsubsection[Natural Mortality]{\protect\hyperlink{NatM}{Natural Mortality}}
Natural mortality ($M$) options include some options that are referenced to integer age and other options to real age since settlement. If using an option that references $M$ to real age since settlement, $M$ varies by age and will change by season (e.g., cohorts born early in the year will have different $M$ than cohorts born later in the year).

\myparagraph{Lorenzen Natural Mortality}
Lorenzen natural mortality is based on the concept that natural mortality is driven by physiological and ecological processes and varies over the life cycle of a fish. So, natural mortality is scaled by the length of the fish. In this implementation, a reference age and $M$ value are read in, and other ages will have an $M$ scaled to its body size-at-age. However, if platoons are used, all will have the same $M$ as their growth pattern. Lorenzen $M$ calculation will be updated if the starting year growth parameters are active, but if growth parameters vary during the time series, the $M$ is not further updated. Additionally, the $M$ is linked to the length-at-age from the growth parameters and can't be used for an empirical weight-at-age model. Be careful in using Lorenzen when there is time-varying growth.

\myparagraph{Age-specific $M$ Linked to Age-Specific Length and Maturity}

This is an experimental option available as of v.3.30.17. 

A general model for age- and sex-specific natural mortality expands a model developed by \citet{maunder2010bigeye} and \citet{maunder2011M} and is based on the following some assumptions:

\begin{enumerate}
  \item $M$ for younger fish is due mainly to processes that are functions of the size of the individuals (e.g., predation);
  \item $M$ increases after individuals become reproductively mature;
  \item Maturity follows a logistic curve; and
 % \item $M$ caused by reproduction may differ by sex, but juvenile $M$ is independent of sex; and 
  \item $M$ caused by senescence is either small or occurs at an age for which there are few fish alive, so it is not influential. 
\end{enumerate}
The model is based on combining the observation that $M$ is inversely proportional to length for young fish \citep{lorenzen2000allometry} and the logistic model from \citet{lehodey2008spatial} for older fish. Natural mortality for a given sex and age is:
\begin{equation}
M_{a,s} = M_{juv,s}\frac{L_{a,s}}{L_{mat*,s}}^{\lambda} + 
\frac{M_{mat,s}-M_{juv,s}\frac{L_{a,s}}{L_{mat*,s}}^{\lambda}}{1+e^{\beta_s(L_{a,s}- L_{50,s})}},
\end{equation}

where $M_{juv,s}$ (juvenile natural mortality), $\lambda$ (power), $L_{mat*,s}$ (first mature length of fish), and $M_{mat,s}$ (the mature instantaneous natural mortality rate by sex, are user inputs in long parameter lines. For sub-option 1, $L_{50}$ and $\beta$ (slope) parameters taken from the maturity relationship within the model, which must use maturity-fecundity option 1. For sub-option 3, the $L_{50,s}$ (the length at which 50\% of fish are mature) and $\beta$ (slope) parameters are specified in long parameter lines by the user.

Note that juvenile natural mortality, $M_{juv,s}$, and first mature length of fish, $L_{mat*,s}$, inputs are by sex (and growth pattern), but it is recommended to share them across sex by using the \hyperlink{offset}{offset option}. Using offset option 2 (males offset from females) causes male parameters to be an offset to the female parameters, so a parameter value of 0.0 for a male parameter will fix the parameter as same as the female parameter. Alternatively, using offset option 1 and setting males to 0.0 and not estimating the parameter fixes the parameter at the value of the female parameter (the \hyperlink{male-shortcut}{section on fixing male parameters the same as female parameters} has more details). This fulfills an additional assumption: $M$ caused by reproduction may differ by sex, but juvenile $M$ is independent of sex.

The length for a given age and sex, $L_{a,s}$ is calculated within the model.

Some suggested defaults for user-provided parameter inputs are:
\begin{itemize}
 \item $\lambda = -1.5$ from \citet{gulland1987natural}
 \item $M_{mat,s}=\frac{5.4}{t_{max,s}}$ from Hamel (submitted) if $t_{max}$ is available, otherwise $M_{mat,s} = 4.118K_{s}^{0.73}L_{inf,s}^{-0.33}$ as in \citet{then2015evaluating} 
 \item $M_{juv,s} = 3W_{mat}^{-0.288}$ from \citet{lorenzen1996relationship}
\end{itemize}

\myparagraph{Age-range Lorenzen}
The original implementation of Lorenzen natural mortality in Stock Synthesis uses a reference age and its associated natural mortality as inputs to determine the Lorenzen curve. However, sometimes this information is not known. The age-range Lorenzen instead uses a range of ages and the average natural mortality over them to calculate a Lorenzen natural mortality curve.

Like the original Lorenzen options, ages will have an $M$ scaled to its body size-at-age and care should be taken when there are multiple growth patterns or time-varying growth.

\myparagraph{Natural Mortality Options}
\begin{longtable}{p{0.5cm} p{2cm} p{12.75cm}}
	\hline	
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endfirsthead

	\hline
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endhead
	\hline

	\endfoot
	
	\endlastfoot

	1 & & Natural Mortality Options: \Tstrut\\
	  & & 0 = A single parameter; \\
	  & & 1 = N breakpoints; \\
	  & & 2 = Lorenzen; \\
	  & & 3 = Read age specific $M$ and do not do seasonal interpolation; \\
	  & & 4 = Read age specific and do seasonal interpolation, if appropriate; \\
	  & & 5 = Age-specific $M$ linked to age-specific length and maturity (experimental); \\
	  & & 6 = Age-range Lorenzen. \Bstrut\\
	\hline

	\multicolumn{2}{l}{COND = 0} & No additional natural mortality controls. \Tstrut\Bstrut\\
	\hline

	\multicolumn{2}{l}{COND = 1} & \Tstrut\Bstrut\\
	& 4 & Number of breakpoints. Then read a vector of ages for these breakpoints. Later, per sex $\times$ GP, read N parameters for the natural mortality at each breakpoint. \\

	\multicolumn{2}{r}{2.5 4.5 9.0 15.0} & Vector of age breakpoints. \Bstrut\\
	\hline
	
	\multicolumn{2}{l}{COND = 2} & \Tstrut\\
	& 4 \Tstrut & Reference age for Lorenzen natural mortality: read one additional integer value that is the reference age. Later read one long parameter line for each sex $\times$ growth pattern that will be the $M$ at the reference age. \\
	\hline
	
	\multicolumn{2}{l}{COND = 3 or 4} \Tstrut & Do not read any natural mortality parameters in the mortality growth parameter section. With option 3, these $M$ values are held fixed for the integer age (no seasonality or birth season considerations). With option 4, there is seasonal interpolation based on real age, just as in options 1 and 2.\\

	& 0.20 0.25...0.20 0.23... & Age-specific $M$ values where in a 2 sex model the first row is female and the second row is male. If there are multiple growth patterns female growth pattern 1-N is read first followed by males 1-N growth pattern. \Bstrut\\
	\hline
	
	\multicolumn{2}{l}{COND = 5} \Tstrut & Age-specific $M$ linked to age-specific length and maturity sub-options. \\

	&  & 1 = Requires 4 long parameter lines per sex $\times$ growth pattern using maturity. Must be used with maturity option 1; \\
	&  & 2 = Reserved for future option; \\
	&  & 3 = Requires 6 long parameter lines per sex $\times$ growth pattern \Bstrut\\
	\hline

	\multicolumn{2}{l}{COND = 6} \Tstrut & Read two additional integer values that are the age range for average $M$. Later, read one long parameter line for each sex $\times$ growth pattern that will be the average $M$ over the reference age range. \\
	& 0 \Tstrut & Minimum age of average $M$ range for calculating Lorenzen natural mortality. \\
	& 10 \Tstrut & Maximum age of average $M$ range for calculating Lorenzen natural mortality. \\ 
	\hline
\end{longtable}

\hypertarget{Growth}{}
\subsubsection[Growth]{\protect\hyperlink{Growth}{Growth}}

\myparagraph{Timing} 
When fish recruit at the real age of 0.0 at settlement, they have body size equal to the lower edge of the first population size bin. The fish then grow linearly until they reach a real age equal to the input value ``growth-at-age for L1'' and have a size equal to the parameter value for L1 (the minimum length parameter). As they age further, they grow according the selected growth equation. The growth curve is calibrated to go through the size L2 parameter when they reach the age of maximum length.
	
\myparagraph{Maximum Length (Linf)}
If ``Growth at age for L2'' is set equal to 999, then the size at the L2 parameter is used as Linf. 
	
\myparagraph{von Bertalanffy growth function}

The von Bertalanffy growth curve is parameterized as:

\begin{equation}
	L_t = L_\infty + (L_{1}-L_\infty)e^{-k(a-A_{1})}
\end{equation}

with parameters $L_{1}$, $L_\infty$, and $k$. The $L_\infty$ is calculated as:

\begin{equation}
	L_\infty = L_{1} + \frac{(L_2 - L_1)}{1-e^{-k(A2-A1)}}
\end{equation}

based on the input values of fixed age for first size-at-age ($A_1$) and fixed age for second size-at-age ($A_2$). 

\myparagraph{Richards growth function}
The \citet{richards1959growth} growth model as parameterized by \citet{schnute1981growth} provides a flexible growth parameterization that allows for a variety of growth curve shapes. The Richards growth is invoked by entering option 2 in the growth type field. The Richards growth function uses the standard growth parameters ($L_1$, $L_2$, $k$) and a fourth shape parameter $b$ that is specified after the growth coefficient $k$.

The Richards growth model is parameterized as:

\begin{equation}
	L_t = \left[L_1^b + (L_2^b-L_1^b)\frac{1-e^{-k(t-A_{1})}}{1-e^{-k(A_2-A_1)}}\right]^{1/b}
\end{equation}

with parameters $L_1$, $L_2$, $k$, and $b$.

The $b$ shape parameter can be positive or negative but not precisely 0. When estimating $b$ as a floating-point number, there is effectively no risk of the parameter becoming precisely zero during estimation, as long as the initial value is non-zero.

As special cases of the Richards growth model, $b\!=\!1$ is von Bertalanffy growth and $b$ near 0 is Gompertz growth. To use a Gompertz growth curve, the $b$ parameter can be fixed at a small value such as 0.0001.

When $A_1$ is greater than the youngest age in the model, some combinations of Richards growth parameters can lead to undefined (NaN) predicted length for the younger ages. The choice of $A_1$ and $A_2$ will affect the possible growth curve shapes.

The SS3 website includes \href{https://nmfs-ost.github.io/ss3-website/qmds/richards_growth_curve.html}{a vignette} providing further technical insights for using the Richards growth model in Stock Synthesis.

	
\myparagraph{Mean size-at-maximum age}
The mean size of fish in the max age bin depends upon how close the growth curve is to Linf by the time it reaches max age and the mortality rate of fish after they reach max age. Users specify the mortality rate to use in this calculation during the initial equilibrium year. This must be specified by the user and should be reasonably close to $M$ plus initial $F$. In v.3.30, this uses the von Bertalanffy growth out to 3 times the maximum population age and decays the numbers at age by exp(-value set here). For subsequent years of the time series, the model should update the size-at-maximum age according to the weighted average mean size of fish already at maximum age and the size of fish just graduating into maximum age. Unfortunately, this updating is only happening in years with time-varying growth. This will hopefully be fixed in the future version.
	
\myparagraph{Age-specific K}
This option creates age-specific K multipliers for each age of a user-specified age range, with independent multiplicative factors for each age in the range and for each growth pattern/sex. The null value is 1.0 and each age's K is set to the next earlier age's K times the value of the current age's multiplier. Each of these multipliers is entered as a full parameter line, so inherits all time-varying capabilities of full parameters. The lower end of this age range cannot extend younger than the specified age for which the first growth parameter applies. This is a beta model feature, so examine output closely to assure you are getting the size-at-age pattern you expect. Beware of using this option in a model with seasons within year because the K deviations are indexed solely by integer age according to birth year. There is no offset for birth season timing effects, nor is there any seasonal interpolation of the age-varying K.

\hypertarget{GrowthCessation}{}
\myparagraph{Growth cessation}
A growth cessation model was developed for the application to tropical tuna species \citep{maunder-growth-2018}. Growth cessation allows for a linear relationship between length and age, followed by a marked reduction of growth after the onset of sexual maturity by assuming linear growth for the youngest individuals and then a logistic function to model the decreasing growth rate at older ages.

\vspace*{-\baselineskip}	
\begin{longtable}{p{0.5cm} p{2cm} p{12.5cm}}
	\multicolumn{3}{l}{Example growth specifications:} \Tstrut\Bstrut\\
	\hline	
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endfirsthead

	\hline
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endhead
	\hline

	\endfoot
	
	\endlastfoot

	1 & & Growth Model: \Tstrut\\
	  & & 1 = von Bertalanffy (3 parameters); \\
	  & & 2 = Schnute's generalized growth curve (aka Richards curve) with 3 parameters. Third parameter has null value of 1.0; \\
	  & & 3 = von Bertalanffy with age-specific K multipliers for specified range of ages, requires additional inputs below following the placeholder for future growth feature; \\
	  & & 4 = age-specific K. Set base K as K for age = N ages and working backwards and the age-specific K = K for the next older age * multiplier, requires additional inputs below following the placeholder for future growth feature; \\
	  & & 5 = age specific K. Set base K as K for N ages and work backwards and the age-specific K = base K * multiplier, requires additional inputs below following the placeholder for future growth feature; \\
	  & & 6 = not implemented; \\
	  & & 7 = not implemented; and \\
	  & & 8 = growth cessation. Decreases the K for older fish. If implemented, the Amin and Amax parameters, the next two lines, need to be set at 0 and 999 respectively. The mortality-growth parameter section requires the base K parameter line which is interpreted as the steepness of the logistic function that models the reduction in the growth increment by age followed by a second parameter line which is the parameter related to the maximum growth rate. \Bstrut\\
	\hline

	\Tstrut 1 & & Growth Amin (A1): Reference age for first size-at-age L1 (post-settlement) parameter. First growth parameter is size at this age; linear growth below this. \Bstrut\\
	%\hline

	\Tstrut 25 & & Growth Amax (A2): Reference age for second size-at-age L2 (post-settlement) parameter. Use 999 to treat as L infinity. \Bstrut\\
	\hline
	
	\Tstrut 0.20 & & Exponential decay for growth above maximum age (plus group: fixed at 0.20 in v.3.24; should approximate initial Z). Alternative Options: \\
				 & & -998 = Disable growth above maximum age (plus group) similar to earlier versions of SS3 (prior to v.3.24); and \\
				 & & -999 = Replicate the simpler calculation done in v.3.24. \Bstrut\\
	\hline
	
	0 & & Placeholder for a future growth feature. \Tstrut\Bstrut\\
	\hline

	\multicolumn{2}{l}{COND = 3} & Growth model: age-specific K age-specific K where the age-specific K parameter values are multipliers of the age - 1 K parameter value. For example, if the base parameter is 0.20 based on the example setup the K parameter for age 5 is equal to 0.20 * age-5 multiplier. Subsequently, age 6 K value is equal to age 5 K (0.20 * age-5 multiplier) multiplied by the age-6 multiplier. All ages above the maximum age with age-specific K are equal to the maximum age-specific K. The age specific K values are available in the Report file in the AGE\_SPECIFIC\_K section. \\
	3 & & Number of K multipliers to read; \\
	& 5 & Minimum age for age-specific K; and \\
	& 6 & Second age for age-specific K; and \\
	& 7 & Maximum age for age-specific K. \Bstrut\\
	
	\multicolumn{2}{l}{COND = 4} & Growth model: age-specific K where the age-specific K parameter values are multipliers of the age + 1 K parameter value. For example, if the base parameter is 0.20 based on the example setup the K parameter for age 7 is equal to 0.20 * age-7 multiplier. Subsequently, age 6 K value is equal to age 7 K (0.20 * age-7 multiplier) multiplied by the age-6 multiplier. All ages below the minimum age with age-specific K are equal to the minimum age-specific K. The age specific K values are available in the Report file in the AGE\_SPECIFIC\_K section. \\
	3 & & Number of K multipliers to read; \\
	  & 7 & Maximum age for age-specific K; \\
	  & 6 & Second age for age-specific K; and \\
	  & 5 & Minimum age for age-specific K. \Bstrut\\
	\hline
	
	\multicolumn{2}{l}{COND = 5} & Growth model: age-specific K where the age-specific K parameter values are multipliers of the base K parameter value. For example, if the base parameter is 0.20 based on the example setup the K parameter for age 7 is equal to 0.20 * age-7 multiplier. Subsequently, age 6 K value is equal 0.20 * age-6 multiplier. The age specific K values are available in the Report file in the AGE\_SPECIFIC\_K section. \\
	3 & & Number of K multipliers to read; \\
	& 7 & Maximum age for age-specific K; \\
	& 6 & Second age for age-specific K; and \\
	& 5 & Minimum age for age-specific K. \Bstrut\\
	\hline

	\Tstrut 0 & & Standard deviation added to length-at-age: Enter 0.10 to mimic SS2 V1.xx. Recommend using a value of 0.0. \Bstrut\\
	\hline

	1 & & \gls{cv} Pattern (cannot be time-varying) \Tstrut\\
	  & & 0: CV=f(LAA), so the 2 parameters are in terms of \gls{cv} of the distribution of length-at-age (LAA) and the interpolation between these 2 parameters is a function of mean length-at-age; \\
	  & & 1: CV=f(A), so interpolation is a function of age (A); \\
	  & & 2: SD=f(LAA), so parameters define the \gls{sd} of length-at-age and interpolation is a function of mean length-at-age; \\
	  & & 3: SD=f(A); and \\
	  & & 4: Log-normal distribution of size-at-age. Input parameters will specify the \gls{sd} of natural log size-at-age (e.g., entered values will typically be between 0.05 and 0.15). A bias adjustment is applied so the log-normal distribution of size-at-age will have the same mean size as when a normal distribution is used. \Bstrut\\
	\hline
\end{longtable}

\hypertarget{Mat-Fec}{}
\subsubsection[Maturity-Fecundity]{\protect\hyperlink{Mat-Fec}{Maturity-Fecundity}}

\begin{longtable}{p{0.5cm} p{2cm} p{13cm}}
	\hline	
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endfirsthead

	\hline
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endhead
	\hline

	\endfoot
	
	\endlastfoot

	2 & & Maturity Option: \Tstrut\\
	  & & 1 = length logistic; \\
	  & & 2 = age logistic; \\
	  & & 3 = read maturity-at-age for each female growth pattern; \\
	  & & 4 = read a fecundity ``x'' maturity-at-age vector for all ages; \\
	  & & 5 = disabled; and \\
	  & & 6 = read vector of length-based maturity values. \\
	  & & Note: need to read 2 parameter lines (maturity at 50\% and maturity slope) even if option 3 or 4 is selected. \Bstrut\\
	\hline

	\multicolumn{2}{l}{COND = 3 or 4} & Maturity Option \Tstrut\\
	\multicolumn{2}{r}{0 0.05 0.10...} & Vector of age-specific maturity or fecundity. One row of length N ages + 1 based on the maximum population age for each female growth pattern. \Bstrut\\
	\multicolumn{2}{l}{COND = 6} & Maturity Option \Tstrut\\
	\multicolumn{2}{r}{0 0.05 0.10...} & Vector of length-specific maturity or fecundity, based on the population length bins. One row of length equal to the number of population length bins (defined in the data file) for each female growth pattern. \Bstrut\\
	\hline
	
	\Tstrut 1 & & First Mature Age: all ages below the first mature age will have maturity set to zero. This value is overridden if maturity option is 3 or 4 or if empirical weight-at-age (\texttt{wtatage.ss}) is used, but still must exist here. \Bstrut\\
	\hline

	\Tstrut 1 & & Fecundity Option (irrelevant if maturity option is 4 or \texttt{wtatage.ss} is used): \\
	  & & 1 = to interpret the 2 egg parameters as linear eggs/kg on body weight (current default), so fecundity = $wt*(a+b*wt)$, so value of a=1, b=0 causes eggs to be equivalent to spawning biomass; \\
	  & & 2 = to set fecundity= $a*L^b$; \\
	  & & 3 = to set fecundity= $a*W^b$, so values of a=1, b=1 causes fecundity to be equivalent to spawning biomass; \\
	  & & 4 = fecundity = $a+b*L$; and \\
	  & & 5 = eggs = $a+b*wt$. \Bstrut\\
	\hline
\end{longtable}

% \pagebreak
\hypertarget{Hermaphroditism}{}
\subsubsection[Hermaphroditism]{\protect\hyperlink{Hermaphroditism}{Hermaphroditism}}

Sequential hermaphroditism can be modeled in Stock Synthesis by having recruits be all female or all male and then defining a 3-parameter function which represents the annual age-specific probability of transition to the other sex. In a seasonal model, the transition can occur after each season or just once per year. There are also settings to control the first age which transitions and the contribution of males to the spawning biomass calculations.

The \hyperlink{SexRatio}{fraction female} parameter should be configured to reflect the fraction of age 0 fish of each sex. Values of 0 or 1 may lead to NaN likelihoods, so we recommend changing values that would be fixed at 0 or 1 to 0.000001 or 0.999999.

\begin{longtable}{p{0.5cm} p{2cm} p{13cm}}
	\hline	
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endfirsthead

	\hline
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endhead
	\hline

	\endfoot
	
	\endlastfoot

	0 & & Hermaphroditism Option: \Tstrut\\
	 &  & 0 = not used; \\
	 &  & 1 = invoke female-to-male age-specific function; and \\
	 &  & -1 = invoke male-to-female age-specific function.\Bstrut\\
	\hline

	\multicolumn{2}{l}{COND = 1 or} \Tstrut & \\
	\multicolumn{2}{l}{COND = -1} & Read 2 lines below if hermaphroditism is selected. Also read 3 parameters after reading the male weight-length parameters. \Bstrut\\
	& -1.2 & Hermaphroditism Season / First Age: \\
	&     & -1 to do transition at the end of each season (after mortality and before movement); or \\
	&     & <positive integer> to select just one season. \\
    &	  & If fractional part included (optional), indicates first age that transitions (otherwise, age 1 assumed). \\
	& 0.5 & Fraction of males to include in spawning biomass; \\
	&     & 0 = no males in spawning biomass; \\
	&     & fraction of male biomass to include in spawning biomass; and \\
	&     & 1 = simple addition of males to females. \Bstrut\\
	\hline
\end{longtable}
\vspace*{-\baselineskip}

The hermaphroditism option requires three full parameter lines in the \hyperlink{HermaphroditeBiology}{mortality and growth section}. These parameters control a cumulative normal distribution function as follows:
\begin{enumerate}
	\item The inflection age where the transition rate is halfway from 0 to its asymptote.
	\item The standard deviation of the cumulative normal (such that about 95\% of the increase in transition rate occurs within 2 standard deviations of the inflection point).
	\item The asymptotic transition rate (the highest proportion that will transition to the other sex in a time step).
\end{enumerate}
These parameter lines are entered directly after the weight-at-length parameters for males.

% \pagebreak
\hypertarget{offset}{}
\subsubsection[Natural Mortality and Growth Parameter Offset Method]{\protect\hyperlink{offset}{Natural Mortality and Growth Parameter Offset Method}}

The most common setup for natural mortality and growth parameters for two-sex models is direct assignment (option 1) which allows for independent estimation (or fixing) of natural mortality and growth parameters by sex. Within the direct assignment option there is functionality to set male parameters equal to the corresponding female parameter if the male INIT value is set to 0 and the phase is negative. 

Alternatively, there may be situations where a user wants to create direct linkages between natural mortality and growth parameters between sexes (options 2 or 3). If the parameter offset option 2 is selected, the control file still requires that all male natural mortality and growth parameters lines to be included. The natural mortality and growth parameters (e.g., k, Lmin, Lmax, CV1, CV2) for sex > 1 (typically male fish) have a value that is an exponential offset to the female natural mortality and growth parameters, e.g., $M_{\text{male}} = M_{\text{female}}*exp(M_{\text{male offset}})$. An offset parameter can be fixed at 0.0, at a non-zero value, or estimated.

Parameter offset option 3 has an offset feature for the growth \gls{cv} and for natural mortality. For the growth \gls{cv}, the parameter for \gls{cv} at old age is an exponential offset from the parameter for \gls{cv} at young age, e.g., $CV_{\text{old}} = CV_{\text{young}}*exp(CV_{\text{offset}})$. This allows for \gls{cv} old to track an estimated \gls{cv} young parameter. For natural mortality, if there is more than 1 natural mortality parameter, then parameters 2 and higher for the same sex and growth pattern are exponential offsets from the first natural mortality parameter. Note that it is an old feature designed to work with natural mortality option 1 (breakpoints). It may work with natural mortality options 3 and 4, but this has not been tested.


\begin{longtable}{p{0.5cm} p{2cm} p{13cm}}
	\hline	
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endfirsthead

	\hline
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endhead
	\hline

	\endfoot
	
	\endlastfoot

	 1 & & Parameter Offset Method: \Tstrut\Bstrut\\
	   & & 1 = direct assignment; \\
	   & & 2 = for each growth pattern by sex, parameter defines offset from sex 1, offsets are in exponential terms, so for example: $M_{\text{old male}} = M_{\text{old female}}*exp(M_{\text{old male}})$; and \\
	   & & 3 = for each growth pattern by sex, parameter defines offset from growth pattern 1 sex 1. For females, given that ``natM option'' is breakpoint and there are two breakpoints, parameter defines offset from early age (e.g., $M_{\text{old female}} = M_{\text{young female}}*exp(M_{\text{old female}}$). For males, given that ``natM option'' is breakpoint and there are two breakpoints, parameter is defined as offset from females AND from early age (e.g., $M_{\text{old male}} = M_{\text{young female}}*exp(M_{\text{young male}})*exp(M_{\text{old male}})$). \Bstrut\\
	\hline
\end{longtable}

\hypertarget{CatchMult}{}
\subsubsection[Catch Multiplier]{\protect\hyperlink{CatchMult}{Catch Multiplier}}
These parameter lines are only included in the control file if the catch multiplier field in the data file is set to 1 for a fleet. The model expected catch $C_{exp}$ by fleet is estimated by:

\begin{equation}
C_{exp} = \frac{C_{obs}}{c_{mult}}
\end{equation}

where $C_{obs}$ is the input catch by fleet (observed catch) within the data file and $c_{mult}$ is the estimated (or fixed) catch multiplier. It has year-specific, not season-specific, time-varying capabilities. In the catch likelihood calculation, expected catch is multiplied by the catch multiplier by year and fishery to get $C_{obs}$ before being compared to the observed retained catch as modified by the $c_{mult}$.

\hypertarget{AgeErrorParam}{}
\subsubsection[Ageing Error Parameters]{\protect\hyperlink{AgeErrorParam}{Ageing Error Parameters}}
These parameters are only included in the control file if one of the ageing error definitions in the data file has requested this feature (by putting a negative value for the ageing error of the age zero fish of one ageing error definition). As of v.3.30.12, these parameters now have time-varying capability. Seven additional full parameter lines are required. The parameter lines specify:
\begin{enumerate}
	\item Age at which the estimated pattern begins (just linear below this age), this is the start age.
	\item Bias at start age (as additive offset from unbiased age).
	\item Bias at maximum (as additive offset from unbiased age).
	\item Power function coefficient for interpolating between those 2 values (value of 0.0 produces linear interpolation in the bias).
	\item Standard deviation at start age.
	\item Standard deviation at max age.
	\item Power function coefficient for interpolating between those 2 values.
\end{enumerate}

\noindent Code for implementing vectors of mean age and standard deviation of age can be located online within the \href{https://github.com/nmfs-ost/ss3-source-code/blob/main/SS_miscfxn.tpl}{SS\_miscfxn.tpl} file, search for function ``get\_age\_age'' or ``SS\_Label\_Function 45''.

\hypertarget{SexRatio}{}
\subsubsection[Sex Ratio]{\protect\hyperlink{SexRatio}{Sex Ratio}}
The last line in the mortality-growth parameter section allows the user to fix or estimate the sex ratio between female and male fish at recruitment. The parameter is specified in the fraction of female fish and is applied at settlement. The default option is a sex ratio of 0.50 with this parameter not being estimated. Any composition data input as type = 3, both sexes, will be informative to the sex ratio because it scales females and males together, not separately, for this data type input. Estimation of the sex ratio is a new feature and should be done with care with the user checking that the answer is reflective of the data.

As of v.3.30.12, this parameter now has time-varying capability similar to other parameters in the mortality-growth section.

\subsubsection{Predator Fleet Mortality}
The ability to define a predator fleet was first implemented in v.3.30.18. A parameter line for predator mortality is only required if a predator fleet has been defined in the data file. For each fleet that is designated as a predator, a new parameter line is created in the \gls{mg} section in the control file. This parameter will have the label $M2\text{\_pred1}$, where the ``1'' is the index for the predator (not the index of the fleet being used as a predator). More than one predator can be included. If the model has > 1 season, it is normal to expect $M2$ to vary seasonally. Therefore, only if the number of seasons is greater than 1, follow each $M2$ parameter with number of season parameters to provide the seasonal multipliers. These are simple multipliers times $M2$, so at least one of these needs to have a non-estimated value. The set of multipliers can be used to set $M2$ to only operate in one season if desired. If there is more than one predator fleet, each will have its own seasonal multipliers. If there is only 1 season in the model, then no multiplier lines are included. 

$M2$ is age-specific, but not sex or morph specific. The value of the $M2$ parameter will be distributed across ages according to the selectivity for this fleet. In this example note that ``pred1'' refers to the first predator in the model, note the fleet number in which that predator has been 3 configured. The resultant age-specific $M2$ is added to the base $M$ to create a total age-specific $M$ that operates in the model exactly as $M$ has always operated. 

Because $M2$ is a \gls{mg}, it can be time-varying like any other \gls{mg}. This is important because $M2$, as a component added to base $M$, will probably always need to be time-varying by blocks, random walk or linkage to external driver. A time series of $M2$ from an external source could be input by setting the $M2$ parameter to have a base value of 0.0 and linking to the time series in the environmental data section of the data file using an additive link. In addition, the relationship should have a fixed slope of 1.0 such that $M2(y) = 0.0 + 1.0 * M2\text{\_env\_input}(y)$. 

Note that all existing reports of natural mortality are the total (base $M$ + $M2$) natural mortality. The $M2$ parameter is active in the virgin year and initial equilibrium year, where the value of $M2$ in the start year is used. In the future, separate control of $M2$ for the initial equilibrium will be provided. $M2$ is part of the total $M$ used in the \gls{spr} and \gls{msy} benchmark calculations. $M2$ is active in the forecast era, so be attentive to its configuration if it is time-varying. Testing to date shows that this $M2$ feature can replicate previous results using bycatch fleets.

Note that predator calculations probably will fail if tried with $F$ Method = 1 (Pope's), even though the Pope calculation is built into the hybrid $F$ approach.

\hypertarget{ReadBioParams}{}
\subsubsection[Read Biology Parameters]{\protect\hyperlink{ReadBioParams}{Read Biology Parameters}}
\hypertarget{MGorder}{}
Next, the model reads the \gls{mg} parameters in generally the following order (may vary based on selected options):

\begin{longtable}{p{1cm} p{2.25cm} p{10cm}}
	\hline
	Parameter & & Description \Tstrut\Bstrut\\
	\hline
	\endfirsthead

	\hline
	Parameter & & Description \Tstrut\Bstrut\\
	\hline
	\endhead

	\hline
	\endfoot

	\endlastfoot

	\multicolumn{2}{l}{Females}\Tstrut & Female natural mortality and growth parameters in the following order by growth pattern. \\
	& $M$ & Natural mortality for female growth pattern 1, where the number of natural mortality parameters depends on the option selected. \Bstrut\\
	\hline
	\multicolumn{2}{l}{COND if $M$ option = 1} & \Tstrut\\
	& N breakpoints & N-1 parameter lines as an exponential offsets from the previous reference age. \Bstrut\\
	\hline

	& Lmin & Length at Amin (units in cm) for female, growth pattern 1. \\
	& Lmax & Length at Amax (units in cm) for female, growth pattern 1. \\
	& VBK & von Bertalanffy growth coefficient (units are per year) for females, growth pattern 1. \Bstrut\\
	\hline

	\multicolumn{2}{l}{COND if growth type = 2} & \Tstrut\\
	& Richards Coefficient & Only include this parameter if Richards growth function is used. If included, a parameter value of 1.0 will have a null effect and produce a growth curve identical to von Bertalanffy. \\

	\multicolumn{2}{l}{COND if growth type >= 3} & Age-Specific K \\
	& \multicolumn{2}{l}{N parameter lines equal to the number K deviations for the ages specified above.} \Bstrut\\
	\hline

	\Tstrut & \gls{cv} young & Variability for size at age $<=$ Amin for females, growth pattern 1. Note that \gls{cv} cannot vary over time, so do not set up env-link or a deviation vector. Also, units are either as \gls{cv} or as standard deviation, depending on assigned value of \gls{cv} pattern. \\
	& \gls{cv} old & Variability for size at age $>=$ Amax for females, growth pattern 1. For intermediate ages, do a linear interpolation of \gls{cv} on means size-at-age. Note that the units for \gls{cv} will depend on the \gls{cv} pattern and the value of mortality-growth parameter as offset. The \gls{cv} value cannot vary over time. \Bstrut\\
	\hline

	\Tstrut & WtLen scale & Coefficient to convert length in cm to weight in kg for females. \\
	& WtLen exp & Exponent in to convert length to weight for females. \\
	& Mat-50\% & Maturity logistic inflection (in cm or years) where female maturity-at-length (or age) is a logistic function: $M_{l} = 1/(1+exp(\alpha*(l_{a} - \beta)))$. The $\alpha$ is the slope, $l_{a}$ is the size-at-age, and $\beta$ is the inflection of the maturity curve. Value ignored for maturity option 3, 4, and 6. \\ 
	& Mat-slope & Logistic slope (must have negative value). Value ignored for maturity option 3, 4, and 6. \\
	& Eggs-alpha & Two fecundity parameters; usage depends on the selected fecundity option. Must be included here even if vector is read in the control section above. \\
	& Eggs-beta & \Bstrut\\
	\hline

	\multicolumn{2}{l}{COND: growth pattern > 1} \Tstrut & Repeat female parameters in the above order for growth pattern 2. \Bstrut\\
	\hline

	\multicolumn{2}{l}{Males} \Tstrut & Male natural mortality and growth parameters in the following order by growth pattern. \Bstrut\\
	& $M$ & Natural mortality for male GP1, where the number of natural mortality parameters depends on the option selected. \Bstrut\\
	\hline
	\multicolumn{2}{l}{COND if $M$ option = 1} & \Tstrut\\
	& N breakpoints & N-1 parameter lines as an exponential offsets from the previous reference age. \Bstrut\\
	\hline
		
	& Lmin & Length at Amin (units in cm) for male, growth pattern 1. In a two sex model, fixing the INIT value a 0 will assume the same Lmin as the female parameter value. \\
	& Lmax & Length at Amax (units in cm) for male, growth pattern 1. In a two sex model, fixing the INIT value a 0 will assume the same Lmax as the female parameter value. \\
	& VBK & von Bertalanffy growth coefficient (units are per year) for males, growth pattern 1. In a two sex model, fixing the INIT value a 0 will assume the same k as the female parameter value. \Bstrut\\
	\hline

	\multicolumn{2}{l}{COND if growth type = 2} & \Tstrut\\
	& Richards Coefficient & Only include this parameter if Richards growth function is used. If included, a parameter value of 1.0 will have a null effect and produce a growth curve identical to Bertalanffy. \\
	\multicolumn{2}{l}{COND if growth type = 3} & Age-Specific K \\
	& \multicolumn{2}{l}{N parameter lines equal to the number K deviations for the ages specified above.} \Bstrut\\
	\hline

	\Tstrut & \gls{cv} young & Variability for size at age $<=$ Amin for males, GP1. Note that \gls{cv} cannot vary over time, so do not set up env-link or a deviation vector. Also, units are either as \gls{cv} or as standard deviation, depending on assigned value of \gls{cv} pattern. \\
	& \gls{cv} old & Variability for size at age $>=$ Amax for males, growth pattern 1. For intermediate ages, do a linear interpolation of \gls{cv} on means size-at-age. Note that the units for \gls{cv} will depend on the \gls{cv} pattern and the value of mortality-growth parameters as offset. \\
	\hline

	\Tstrut & WtLen scale & Coefficient to convert length in cm to weight in kg for males. \\
	& WtLen exp & Exponent to convert length to weight for males. \Bstrut\\
	%\hline

	\multicolumn{2}{l}{COND: growth pattern > 1} \Tstrut & Repeat male parameters in the above order for growth pattern 2. \\
	\hline

	\multicolumn{2}{l}{\hypertarget{HermaphroditeBiology}{COND: Hermaphroditism}} \Tstrut & 3 parameters lines define a cumulative normal distribution for the transition rate of females to males (or vice versa). For more detail on these parameters, see the description \hyperlink{Hermaphroditism}{Hermaphroditism controls} above.\\
	& Inflect Age & Hermaphrodite inflection age where the transition rate is halfway from 0 to its asymptote. \\
	& \gls{sd} & Hermaphrodite standard deviation of the cumulative normal. \\
	& Asmp Rate & Hermaphrodite asymptotic transition rate. \Bstrut\\
	\hline

	\multicolumn{2}{l}{COND: Recruitment Distribution} \Tstrut & 3 parameters lines defining recruitment distribution. See \hyperlink{recdist}{Recruitment Distribution and Parameters} for more details about recruitment apportionment parameterization. \\
	\multicolumn{2}{l}{Method = 2} \Tstrut & \\
	& & \\
	\multicolumn{2}{l}{Recruitment Dist. GP} \Tstrut & Recruitment apportionment by growth pattern, if multiple growth patterns, multiple entries required. \\
	\multicolumn{2}{l}{Recruitment Dist. Area} & Recruitment apportionment by area, if multiple areas, multiple entries required. \\
	\multicolumn{2}{l}{Recruitment Dist. Month} & Recruitment apportionment by month, if multiple months, multiple entries required. \Bstrut\\
	\hline

	\multicolumn{2}{l}{COND: Recruitment Distribution} \Tstrut & 1 parameter line for each settlement event defining the distribution of recruitment among them. See \hyperlink{recdist}{Recruitment Distribution and Parameters} for more details about recruitment apportionment parameterization. \\
	\multicolumn{2}{l}{Method = 3} \Tstrut & \\
	& & \\
	\multicolumn{2}{l}{Recruitment Dist. 1} \Tstrut & Recruitment apportionment parameter for the 1st settlement event. \\
	\multicolumn{2}{l}{Recruitment Dist. 2} & Recruitment apportionment parameter for the 2nd settlement event. \Bstrut\\
	\hline

	\multicolumn{2}{l}{Cohort growth deviation} \Tstrut & Set equal to 1.0 and do not estimate; it is deviations from this base that matter. \Bstrut\\
	\hline

	\multicolumn{2}{l}{2 $\times$ N selected movement pairs} & Movement parameters \Tstrut\Bstrut\\
	\hline

	\multicolumn{3}{l}{COND: The following lines are only required when the associated features are turned on.} \Tstrut\\
	& Platoon StDev Ratio & \\
	& Ageing Error & Turned on in the data file. \\
	& Catch Multiplier & For each fleet selected for this option in the data file. \\
	\hline

	\multicolumn{2}{l}{Fraction female}\Tstrut & \raisebox{0.1\ht\strutbox}{\hypertarget{SexRatio}{Fraction}} female at the time of recruitment by growth pattern, if multiple growth patterns, multiple entries required. \Bstrut\\
	\hline
	
	\multicolumn{3}{l}{COND: The following lines are only required when predator fleets are invoked.} \Tstrut\\
	& $M2$ Predator & Turned on in the data file. \\
	\hline
\end{longtable}


Example format for mortality-growth parameter section with 2 sexes, 2 areas.
Parameters marked with COND are conditional on selecting that feature:
\begin{longtable}{p{1.1cm} p{1.1cm} p{1.1cm} p{1.1cm} p{1.5cm} p{1.1cm} p{6.75cm}}
	\hline
	   &	&	   & Prior & <other & Block & \Tstrut\\
	LO & HI & INIT & Value & entries> & Fxn & Parameter Label \Bstrut\\
	\hline
	\endfirsthead

	\hline
	   &	&	   & Prior & <other & Block & \Tstrut\\
	LO & HI & INIT & Value & entries> & Type & Parameter Label \Bstrut\\
	\hline
	\endhead

	\hline
	\endfoot

	\endlastfoot

	0    & 0.50 & 0.15 & 0.1  & \multicolumn{1}{c}{...} & 0 & \#NatM\_p\_1\_Fem\_GP\_1 \Tstrut\\
	0    & 45   & 21   & 36   & \multicolumn{1}{c}{...} & 0 & \#L\_at\_Amin\_Fem\_GP\_1 \\
	40   & 90   & 70   & 70   & \multicolumn{1}{c}{...} & 0 & \#L\_at\_Amax\_Fem\_GP\_1 \\
	0    & 0.25 & 0.15 & 0.10 & \multicolumn{1}{c}{...} & 0 & \#VonBert\_K\_Fem\_GP\_1 \\
	0.10 & 0.25 & 0.15 & 0.20 & \multicolumn{1}{c}{...} & 0 & \#CV\_young\_Fem\_GP\_1 \\
	0.10 & 0.25 & 0.15 & 0.20 & \multicolumn{1}{c}{...} & 0 & \#CV\_old\_Fem\_GP\_1 \\
	-3   & 3    & 2e-6 & 0    & \multicolumn{1}{c}{...} & 0 & \#Wtlen\_1\_Fem \\
	-3   & 4    & 3    & 3    & \multicolumn{1}{c}{...} & 0 & \#Wtlen\_2\_Fem \\
	50   & 60   & 55   & 55   & \multicolumn{1}{c}{...} & 0 & \#Mat50\%\_Fem \\
	-3   & 3    & -0.2 & -0.2 & \multicolumn{1}{c}{...} & 0 & \#Mat\_slope\_Fem \\
	-5   & 5    & 0    & 0    & \multicolumn{1}{c}{...} & 0 & \#Eggs/kg\_inter\_Fem \\
	-50  & 5    & 0    & 0    & \multicolumn{1}{c}{...} & 0 & \#Eggs/kg\_slope\_wt\_Fem \\
	0    & 0.50 & 0.15 & 0.1  & \multicolumn{1}{c}{...} & 0 & \#NatM\_p\_1\_Mal\_GP\_1 \\
	0    & 45   & 21   & 36   & \multicolumn{1}{c}{...} & 0 & \#L\_at\_Amin\_Mal\_GP\_1 \\
	40   & 90   & 70   & 70   & \multicolumn{1}{c}{...} & 0 & \#L\_at\_Amax\_Mal\_GP\_1 \\
	0    & 0.25 & 0.15 & 0.10 & \multicolumn{1}{c}{...} & 0 & \#VonBert\_K\_Mal\_GP\_1 \\
	0.10 & 0.25 & 0.15 & 0.20 & \multicolumn{1}{c}{...} & 0 & \#CV\_young\_Mal\_GP\_1 \\
	0.10 & 0.25 & 0.15 & 0.20 & \multicolumn{1}{c}{...} & 0 & \#CV\_old\_Mal\_GP\_1 \\
	-3   & 3    & 2e-6 & 0    & \multicolumn{1}{c}{...} & 0 & \#Wtlen\_1\_Mal \\
	-3   & 4    & 3    & 3    & \multicolumn{1}{c}{...} & 0 & \#Wtlen\_2\_Mal \\
	 0   & 0    & 0    & 0    & \multicolumn{1}{c}{...} & 0 & \#RecrDist\_GP\_1 \\
	 0   & 0    & 0    & 0    & \multicolumn{1}{c}{...} & 0 & \#RecrDist\_Area\_1 \\
	 0   & 0    & 0    & 0    & \multicolumn{1}{c}{...} & 0 & \#RecrDist\_Area\_2 \\
	 0   & 0    & 0    & 0    & \multicolumn{1}{c}{...} & 0 & \#RecrDist\_Settlement\_1 \\
	 0.2 & 5    & 1    & 1    & \multicolumn{1}{c}{...} & 0 & \#Cohort\_Grow\_Dev \\
	-5   & 5    & -4   & 1    & \multicolumn{1}{c}{...} & 0 & \#Move\_A\_seas1\_GP1\_from\_1to2 (COND) \\
    -5   & 5    & -4   & 1    & \multicolumn{1}{c}{...} & 0 & \#Move\_B\_seas1\_GP1\_from\_1to2 (COND) \\
	-99  & 99   &  1   & 0    & \multicolumn{1}{c}{...} & 0 & \#AgeKeyParm1 (COND) \\
	-99  & 99   & 0.288 &  0  &...& 0 & \#Age\_Key\_Parms 2 to 5 (COND) \\
	-99  & 99   & 0.715 &  0  &...& 0 & \#Age\_Key\_Parm6 (COND) \\	
	0.2  & 3.0  & 1.0   &  0  &...& 0 & \#Catch\_mult\_fleet1 (COND) \\
	0.001 & 0.999 & 0.5 & 0.5 &...& 0 & \#Frac\_Female\_GP\_1 \\
	-1.0 & 2 & 0 & 0    &...& 0 & \#PredM2\_4 \Bstrut\\		
	\hline
\end{longtable}

\hypertarget{male-shortcut}{}
\myparagraph{Setting Male Parameters Equal to Females}
The model allows a short-cut for males to use the same parameter values as female fish for natural mortality, length minimum (Length at Amin), maximum length (Length at Amax), coefficient at younger ages (CV1), coefficient at older ages (CV2), and the growth coefficient (K) when using offset option = 1 (the \hyperlink{offset}{offset section} has information on the options available). If the INIT parameter value for males is set equal to 0.0 and the phase set to negative, not estimated, each of these male parameters will use the corresponding female parameter value for the males.

\hypertarget{TVParams}{}
\subsubsection[Time-varying Parameters]{\protect\hyperlink{TVParams}{Time-varying Parameters}}
Please see \hyperlink{tvOrder}{the Time-Varying Parameter Specification and Setup section} for details on how to set up time varying parameters. In short, additional short parameter lines will be needed after the long parameter lines. There are some \hyperlink{tvgrowth}{additional considerations} for time-varying growth.

\hypertarget{SeasBio}{}
\subsubsection[Seasonal Biology Parameters]{\protect\hyperlink{SeasBio}{Seasonal Biology Parameters}}
Seasonal effects are available for weight-length parameters, maturity, fecundity, and for the growth parameter K. The seasonal parameter values adjust the base parameter value for that season.
\begin{equation}
P'=P*exp(\text{seas\_value})
\end{equation}

\begin{longtable}{p{1cm} p{4cm} p{10cm}}
	\multicolumn{3}{l}{Control file continued:} \\
	\hline
	Value & & Description \Tstrut\Bstrut\\
	\hline
	\endfirsthead
	
	\hline
	Value & & Description \Tstrut\Bstrut\\
	\hline
	\endhead
	
	\endfoot
	\endlastfoot

	\multicolumn{2}{l}{0 0 0 0 0 0 0 0 0 0}\Tstrut & Seasonality for selected biology parameters (not a conditional input). Read 10 integers to specify which biology parameters have seasonality: female-wtlen1, female-wtlen2, maturity1, maturity2, fecundity1, fecundity2, male-wtlen1, male-wtlen2, L1, K. Reading a positive value selects that factor for seasonality. \Bstrut\\
	\hline
	
	\multicolumn{3}{l}{COND: If any factors have seasonality, then read N seasons parameters that define the} \Tstrut\\
	\multicolumn{3}{l}{seasonal offsets from the base parameter value.} \\
	\multicolumn{2}{r}{<short parameter line (s)>} & Read N seasons short parameter lines for each factor selected for seasonality.
	The parameter values define an exponential offset from the base parameter value. \Bstrut\\
	\hline

\end{longtable}

\hypertarget{SRR}{} 
\subsection[Spawner-Recruitment]{\protect\hyperlink{SRR}{Spawner-Recruitment}}
The spawner-recruitment section starts by specification of the functional relationship that will be used. 

\begin{longtable}{p{1cm} p{3cm} p{11cm}}
	\multicolumn{3}{l}{Control file continued:} \\
	\hline
	Value & Label & Description \Tstrut\Bstrut\\
	\hline
	\endfirsthead

	\hline
	Value & Label & Description \Tstrut\Bstrut\\
	\hline
	\endhead
	\hline
	\endfoot
	\endlastfoot

	3 & Spawner-            & The options are: \Tstrut\\
	  & Recruitment         & 2: \hyperlink{Ricker}{Ricker}: 2 parameters: $ln(R_{0})$ and steepness (h); \\
	  & Relationship        & 3: \hyperlink{BH}{Standard Beverton-Holt}, 2 parameters: $ln(R_{0})$ and steepness; \\
	  &                     & 4: Ignore steepness and no bias adjustment. Use this in conjunction with very low emphasis on recruitment deviations to get CAGEAN-like unconstrained recruitment estimates, 2 parameters, but only uses the first one; \\
	  &                     & 5: \hyperlink{Hockey}{Hockey stick}:3 parameters: $ln(R_{0})$, steepness, and $R_{\text{min}}$) for $ln(R_{0})$, fraction of virgin \gls{ssb} at which inflection occurs, and the R level at \gls{ssb} = 0.0; \\
	  &                     & 6: Beverton-Holt with flat-top beyond $B_{0}$, 2 parameters: $ln(R_{0})$ and steepness; \\
	  &                     & 7: \hyperlink{Survivorship}{Survivorship function}: 3 parameters: $ln(R_{0})$, $z_{frac}$, and $\beta$, suitable for sharks and low fecundity stocks to assure recruits are $<=$ population production; \\
	 %&                     & 8: \hyperlink{Shepherd}{Shepherd}: 3 parameters: $ln(R_{0})$, steepness, and shape parameter, $c$;\\
	  & 					& 8: \hyperlink{Shepherd}{Shepherd re-parameterization}: 3 parameters: $ln(R_{0})$, steepness, and shape parameter, $c$ (added to v.3.30.11 and is in beta mode); and \\
	  & 					& 9: \hyperlink{Ricker2}{Ricker re-parameterization}: 3 parameters: $ln(R_{0})$, steepness, and Ricker power, $\gamma$ (added to v.3.30.11 and is in beta mode). \Bstrut\\
	\hline

	1 \Tstrut & Equilibrium recruitment & Use steepness in initial equilibrium recruitment calculation \\
	  & 						& 0 = none; and \\
	  &							& 1 = use steepness (h). \\
	0 & Future Feature			& Reserved for the future option to make realized $\sigma_R$ a function of the stock-recruitment curve. \Bstrut\\ 
	\hline
\end{longtable}

\hypertarget{EquilRecr}{}
\myparagraph{Equilibrium Recruitment}
In principle, steepness should always be used when calculating equilibrium recruitment. This was not the default in early versions of Stock Synthesis, so has not come into common practice. The original logic, from early 1990s version of Stock Synthesis for long-lived U.S. west coast groundfish, was that fishing had not yet gone on long enough to have reduced spawning biomass enough to reduce expected recruitment noticeably for the chosen initial equilibrium year.

Steepness should be used in the equilibrium calculation whenever you believe that the initial equilibrium catch was large enough to have reduced expected recruitment below $R_{0}$. Note that when using this option, the initial equilibrium catch cannot be greater than \gls{msy}. SS3 uses the identical code for initial equilibrium catch and for \gls{msy} calculation, so it is axiomatic that \gls{msy} will be $<=$ initial equilibrium catch. So, SS3 will estimate a $R_{0}$ large enough to make \gls{msy} < initial equilibrium catch. Alternatively, you can elect to not use this option and instead add many years to the beginning of the time series with that same level of initial catch. In this case, it is not equilibrium, so the catch can reduce the population below $B_{MSY}$.

\hypertarget{SRRFunc}{}
\subsubsection[Spawner-Recruitment Functions]{\protect\hyperlink{SRRFunc}{Spawner-Recruitment Functions}}
The number of age-0 fish is related to spawning biomass according to a stock-recruitment relationship. There are a number of options for the shape of the spawner-recruitment relationship: Beverton-Holt, Ricker, Hockey-Stick, and a survival-based stock recruitment relationship.

\hypertarget{BH}{}
\myparagraph{Beverton-Holt}
The Beverton-Holt Stock Recruitment curve is calculated as:
\begin{equation}{R_y = \frac{4hR_0SB_y}{SB_0(1-h)+SB_y(5h-1)}e^{-0.5b_y\sigma^2_R+\tilde{R}_y}\qquad  \tilde{R}_y\sim N(0;\sigma^2_R)}
\end{equation}

where $R_0$ is the unfished equilibrium recruitment, $SB_0$ is the unfished equilibrium spawning biomass (corresponding to $R_0$), $SB_y$ is the spawning biomass at the start of the spawning season during year $y$, $h$ is the steepness parameter, $b_y$ is the bias adjustment fraction applied during year $y$, is the standard deviation among recruitment deviations in natural log space, and is the log-normal recruitment deviation for year $y$. The bias-adjustment factor \citep{methot-adjusting-2011} ensures unbiased estimation of mean recruitment even during data-poor eras in which the maximum likelihood estimate of the recruitment deviation is near 0.0.

\hypertarget{Ricker}{}
\myparagraph{Ricker}
The Ricker Stock Recruitment curve is calculated as:
\begin{equation}{R_y = \frac{R_0SB_y}{SB_0}e^{h(1-SB_y/SB_0)}e^{-0.5b_y\sigma^2_R+\tilde{R}_y}\qquad  \tilde{R}_y\sim N(0;\sigma^2_R)}
\end{equation}

where the stock recruitment parameters have the same meaning as described above for the Beverton-Holt.

\hypertarget{Hockey}{}
\myparagraph{Hockey-Stick}
The hockey-stick recruitment curve is calculated as:
\begin{equation}{R_y = join(R_{\text{min}}R_0+R_0\frac{SB_y}{hSB_0}(1-R_{\text{min}}))+R_0(1-join)e^{-0.5b_y\sigma^2_R+\tilde{R}_y}\qquad  \tilde{R}_y\sim N(0;\sigma^2_R)}\end{equation}
where $R_{\text{min}}$ is the minimum recruitment level predicted at a spawning size of zero and is set by the user in the control file, $h$ is defined as the fraction of $SB_0$ below which recruitment declines linearly, and $join$ is defined as:
\begin{equation}{ join = \bigg[1+e^{1000*\frac{(SB_0-hSB_0)}{SB_0}}\bigg]^{-1} } \end{equation}

\hypertarget{Survivorship}{}
\myparagraph{Survivorship}	
The survivorship stock recruitment relationship based on \citet{taylor-stockrecruitment-2013} is a stock-recruitment model that enables explicit modeling of survival between embryos and age 0 recruits, and allows the description of a wide range of pre-recruit survival curves. The model is especially useful for low fecundity species that produce relatively few offspring per litter and exhibit a more direct connection between spawning output and recruitment than species generating millions of eggs.

Survival-based recruitment is constrained so that the recruitment rate cannot exceed fecundity. The relationship between survival and spawning output is based on parameters which are on a natural log scale. These are:
\begin{equation}
z_0=-ln(S_0)
\end{equation} 
which is the negative of the natural log of the equilibrium survival $S_0$, and can be thought of as a pre-recruit instantaneous mortality rate at equilibrium, and
\begin{equation}
z_{\text{min}}=-ln(S_{\text{max}})=z_0(1-z_{\text{frac}})
\end{equation}
which is the negative of the natural log of the maximum pre-recruit survival rate ($S_{\text{max}}$, the limit as spawning output approaches 0), and is parameterized as a function of $z_{\text{frac}}$ (which represents the reduction in mortality as a fraction of $z_0$) so the expression is well-defined over the parameter range 0 < $z_{\text{frac}}$ < 1.

Recruitment at age 0 for each year in the time series is calculated as:
\begin{equation}{ R_y = SB_ye^{\Big(-z_0 + (z_0-z_{min})\big(1-(SB_y/SB_0)^\beta \big)\Big)}e^{\tilde{R}_y}\qquad  \tilde{R}_y\sim N(0;\sigma^2_R)}
\end{equation}
where $SB_y$ is the spawning output in year y, $\beta$ is a parameter controlling the shape of density-dependent relationship between relative spawning depletion $SB_y/SB_0$ and pre-recruit survival (with limit $\beta$ < 1), $\tilde{R}_y$ is the recruitment in year $y$, and $\sigma_R$ is the standard deviation of recruitment in natural log space. 

As implemented in Stock Synthesis, the parameters needed to apply the stock-recruitment relationship based on the pre-recruit survival are ln($R_0$), $z_{\text{frac}}$, and $\beta$. The value of ln($R_0$) defines the equilibrium quantities of $SB_0$, $S_0$, and $z_0$ for a given set of biological inputs (either estimated of fixed), regardless of the values of $z_{\text{frac}}$ and $\beta$.

The interpretation of the quantity $z_0=-ln(S_0)$ as pre-recruit instantaneous mortality rate at unfished equilibrium is imperfect because the recruitment in a given year is calculated as a product of the survival fraction $S_y$ and the spawning output $SB_y$ for that same time period so that there is not a 1-year lag between quantification of eggs or pups and recruitment at age 0, which is when recruits are calculated within Stock Synthesis. However, if age 0 or some set of the youngest ages is not selected by any fishery of survey, then density dependent survival may be assumed to occur anywhere before the first appearance of any cohort in the data or model expectations. In such cases, the upper limit on survival up to age $a$ is given by $S_{\text{max}}e^{-aM}$. 

Nevertheless, interpreting $z_0$ as an instantaneous mortality helps with the understanding of $z_{\text{frac}}$. This parameter controls the magnitude of the density-dependent increase in survival associated with a reduction in spawning output. It represents the fraction by which this mortality-like rate is reduced as spawning output is reduced from $SB_0$ to 0. This is approximately equal to the increase in survival as a fraction of the maximum possible increase in survival. That is: 
\begin{equation}
z_{\text{frac}}=\frac{ln(S_{\text{max}})-ln(S_0)}{-ln(S_0)} \approx \frac{S_{\text{max}}-S_0}{1-S_0}
\end{equation}
For example, if $S_0 = 0.4$, $z_{\text{frac}}=0.8$, then the resulting fraction increase in survival is $(S_{\text{max}}-S_0)/(1-S_0)=0.72$.

The parameter $\beta$ controls the point where survival changes fastest as a function of spawning depletion. A value of $\beta$ = 1 corresponds to a linear change in natural log survival and an approximately linear relationship between survival and spawning depletion. Values of $\beta$<1 have survival increasing fastest at low spawning output (concave decreasing survival) whereas $\beta$>1 has the increase in survival occurring the fastest closer to the unfished equilibrium (convex decreasing survival).

The steepness ($h$) of the spawner-recruit curve (defined as recruitment relative to $R_{0}$ at a spawning depletion level of 0.2) based on pre-recruit survival can be derived from the parameters discussed above according to the relationship and associated inequality:
\begin{equation}
h = 0.2e^{z_0z_{\text{frac}}(1-0.2^\beta)}<0.2e^{z_0}=\frac{1}{5S_0}=\frac{SB_0}{5R_0}
\end{equation}

Unlike the Beverton-Holt stock-recruitment relationship, recruitment can increase above $R_0$ for stocks that are below $SB_0$ and thus the steepness is not fundamentally constrained below 1. However, in many cases, steepness will be limited well below 1 by the inequality above, which implies an inverse relationship between the maximum steepness and equilibrium survival. Specifically, the inequality above bounds steepness below 1 for all cases where $S_0$ > 0.2, which are those with the lowest fecundity, an intuitively reasonable result. For example, with $S_0$ = 0.4, the steepness is limited below 0.5, regardless of the choice of $z_{\text{frac}}$ or $\beta$. This natural limit on steepness may be one of the most valuable aspects of this stock-recruitment relationship.

Code for the survival based recruitment can be found in \href{https://github.com/nmfs-ost/ss3-source-code/blob/main/SS_recruit.tpl}{\texttt{SS\_recruit.tpl}}, search for ``SS\_Label\_43.3.7 survival based''.

\myparagraph{Shepherd}
\hypertarget{Shepherd}{} 
The Shepherd stock recruit curve is calculated as:
\begin{equation}
R_y = \bigg(\frac{SB_y}{SB_0}\bigg)\frac{5h_{adj}R_0(1-0.2^c)}{(1-5h_{adj}0.2^c)+(5h_{adj}-1)(\frac{SB_y}{SB_0})^c}e^{-0.5b_y\sigma^2_R+\tilde{R}_y}\qquad \tilde{R}_y\sim N(0;\sigma^2_R)
\end{equation}
where $c$ is the shape parameter for the stock recruitment curve, and $h_{adj}$ is the transformed steepness parameter defined as:
\begin{equation}
h_{adj}=0.2+\bigg(\frac{h-0.2}{0.8}\bigg)\bigg(\frac{1}{5*0.2^c}-0.2\bigg)
\end{equation}

More details can be found in \citet{punt-extending-2019}.

\myparagraph{Ricker Re-parameterization}
\hypertarget{Ricker2}{}
The Ricker stock recruit curve re-parameterized version. More details can be found in \citet{punt-extending-2019}.
\begin{equation}
R_y = R_0*(1-temp)*e^{ln(5h)(1-SB_y/SB_0)^{\gamma}/0.8^{\gamma}}
\end{equation}
where $\gamma$ is the Ricker shape parameter and $temp$ is defined as:
\begin{equation}
temp = 
\begin{cases}
1-SB_y/SB_0 & \text{if $1-SB_y/SB_0 >$ 0 }\\
0.001 & \text{if $1-SB_y/SB_0 \leq$ 0}
\end{cases}		
\end{equation}
where $temp$ stabilizes recruitment at $R_0$ if $SB_y > SB_0$. 

\hypertarget{SRRParam}{}
\subsubsection[Spawner-Recruitment Parameter Setup]{\protect\hyperlink{SRRParam}{Spawner-Recruitment Parameter Setup}}
Read the required number of long parameter setup lines (e.g., LO, HI, INIT, PRIOR, PRIOR TYPE, SD, PHASE, ..., and BLOCK TYPE). These parameters are:
\begin{longtable}{p{1cm} p{3cm} p{11cm}}
	\hline
	Value & Label & Description \Tstrut\Bstrut\\
	\hline
	\endfirsthead

	\hline
	Value & Label & Description \Tstrut\Bstrut\\
	\hline
	\endhead
	\hline
	\endfoot
	\endlastfoot

	8.5 & $ln(R_{0})$ & Natural log of virgin recruitment level. \Tstrut\Bstrut\\
	\hline

	0.60 \Tstrut & Steepness & Steepness of spawner recruitment relationship, bound by 0.2 and 1.0 for the Beverton-Holt. \Bstrut\\
	%\hline

	\multicolumn{2}{l}{COND:} \Tstrut & \gls{srr} = 5, 7, or 8 \\
	& 3rd Parameter & Optional depending on which spawner-recruitment relationship function is used. \Bstrut\\
	\hline

	0.60 \Tstrut & $\sigma_R$ & Standard deviation of natural log recruitment. This parameter has two related roles. It penalizes deviations from the spawner-recruitment curve, and it defines the offset between the arithmetic mean spawner-recruitment curve (as calculated from $ln(R_{0})$ and steepness) and the expected geometric mean (which is the basis from which the deviations are calculated). Thus, the value of $\sigma_R$ must be selected to approximate the true average recruitment deviation. See \hyperlink{TuneSigmaR}{Tuning $\sigma_R$} section below for additional guidance on how to tune $\sigma_R$. \Bstrut\\
	\hline

	0 \Tstrut & Regime Parameter & This replaces the R1 offset parameter. It can have a block for the initial equilibrium year, so can fully replicate the functionality of the previous R1 offset approach. The SR regime parameter is intended to have a base value of 0.0 and not be estimated. Similar to cohort-growth deviation, it serves simply as a base for adding time-varying adjustments. This concept is similar to the old environment effect on deviates feature in v.3.24 and earlier. \Bstrut\\
	\hline

	0 & Autocorrelation & Autocorrelation in recruitment. \Tstrut\Bstrut\\
	\hline
\end{longtable}


Example setup of the spawner-recruitment section:
\begin{center}
	\begin{longtable}{p{1cm} p{1cm} p{1cm} p{1.5cm} p{3cm} p{2cm} p{3.5cm}}
		
		\hline
		LO \Tstrut & HI & INIT & PRIOR & <other entries> & Block Fxn & Parameter Label \Bstrut\\
		\hline
		3   & 31 & 8.81 & 10.3 & \multicolumn{1}{c}{...} & 0 & \#SR\_LN(R\textsubscript{0}) \Tstrut\\
		0.2 & 1  & 0.61 & 0.70 & \multicolumn{1}{c}{...} & 0 & \#SR\_BH\_steep \\
		0   & 2  & 0.60 & 0.80 & \multicolumn{1}{c}{...} & 0 & \#SR\_sigmaR \\
		-5  & 5  & 0    & 0    & \multicolumn{1}{c}{...} & 0 & \#SR\_regime \\
		-99 & 99 & 0    & 0    & \multicolumn{1}{c}{...} & 0 & \#SR\_autocorr \Bstrut\\
		\hline
	\end{longtable}
\end{center}
\vspace*{-1.7\baselineskip}

\hypertarget{SRR-TV}{}
\subsubsection[Spawner-Recruitment Time-Varying Parameters]{\protect\hyperlink{SRR-TV}{Spawner-Recruitment Time-Varying Parameters}}

The $R_{0}$, steepness, and regime shift parameters can be time-varying by blocks, trends, environmental linkages, or random deviations. Details on how to specify time-varying parameters can be found in the \hyperlink{tvOrder}{Time-Varying Parameter Specification and Setup} section. However, not all of these options make sense for all parameters; please see additional details in the section on \hyperlink{tv-sr}{Time-Varying Stock-Recruitment Considerations}.

\hypertarget{TuneSigmaR}{}
\subsubsection[Tuning $\sigma_R$]{\protect\hyperlink{TuneSigmaR}{Tuning $\sigma_R$}}
The $\sigma_R$ value is typically not estimable and it is recommended practice to tune input $\sigma_R$ values based on the variance in estimated recruitments post running SS3. The R package \href{https://github.com/r4ss/r4ss}{R code for Stock Synthesis (\texttt{r4ss})} designed to read and visualize SS3 model results provides recommendations on adjusting $\sigma_R$ values in the \texttt{sigma\_R\_info} object in the list created by the \texttt{r4ss::SS\_output()} function. An alternative $\sigma_R$ value is provided based on equation:

\begin{equation}
	\sigma_R^2 = Var(\hat{r}) + \overline{SE(\hat{r}_y)}^2
\end{equation}

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{RecDevSetup}{}
\subsubsection[Recruitment Deviation Setup]{\protect\hyperlink{RecDevSetup}{Recruitment Deviation Setup}}
\begin{longtable}{p{1cm} p{3cm} p{12cm}}
	\multicolumn{3}{l}{Control file continued:} \\

	\hline
	Value & Label & Description \Tstrut\Bstrut\\
	\hline
	\endfirsthead

	\hline
	Value & Label & Description \Tstrut\Bstrut\\
	\hline
	\endhead
	\hline
	\endfoot
	\endlastfoot


	1 \Tstrut & Do Recruitment Deviations & This selects the way in which recruitment deviations are coded: \\
	  & & 0: None (so all recruitments come from spawner recruitment curve). \\
	  & & 1: Deviation vector (previously the only option): the deviations during the main period are encoded as a deviation vector that enforces them to sum to zero for this period. \\
	  & & 2: Simple deviations: the deviations do not have an explicit constraint to sum to zero, although they still should end up having close to a zero-sum. The difference in model performance between options (1) and (2) has not been fully explored to date. This is the recommended option if doing \gls{mcmc} (see the \href{https://github.com/admb-project/admb/issues/107}{issue 107} in the \gls{admb} GitHub Repository for more information on this). \\
	  & & 3: Deviation vector (added in v.3.30.13) where the estimated recruitment is equal to the $R_{0}$ adjusted for blocks multiplied by a simple deviation vector of unconstrained deviations. The negative log likelihood from the deviation vector is equal to the natural log of the estimated recruitment divided by the expected recruitment by year adjusted for the spawner-recruit curve, regimes, environmental parameters, and bias-adjustment. The negative log likelihood between option 2 and 3 is approximately equal. \\
	  & & 4: Similar to option 3 but includes a penalty based on the sum of the deviations (added in v.3.30.13). \\
	  %& & Note: As of version 3.30.13 there is now an option to retain the last deviation estimated and apply that value into the forecast period. To specify this option add the value 2 before the deviation vector option (i.e., 21, 22, 23, or 24).\Bstrut\\
	\hline

	1971 \Tstrut & Main recruitment deviations begin year & If begin year is less than the model start year, then the early deviations are used to modify the initial age composition. However, if set to be more than the population maximum age before start year, it is changed to equal to the maximum age before start year. \Bstrut\\
	\hline

	2017 \Tstrut & \hypertarget{RecDevEndYear}{Main recruitment deviations end year} & The final year to estimate main recruitment deviations should be set to a year when information about young fish in the data becomes limited. For example, if the model end year is 2020 and the fleet/survey only starts observing fish of age 2+, the last year to estimate main recruitment deviations could be set to 2018. Years after the main period but before the end model year will be estimated as late deviations. If recruitment deviations end year is later than retro year, it is reset to equal retro year. \Bstrut\\
	\hline

	3 \Tstrut & Main recruitment deviations phase. & \Bstrut\\
	\hline

	1 \Tstrut & Advanced & 0: Use default values for advanced options \\ 
	& Options & 1: Read values for the 11 advanced options. \Bstrut\\
	\hline

	\multicolumn{3}{l}{COND = 1 Beginning of advanced options} \Tstrut\Bstrut\\
	& 1950 & Early Recruitment Deviations Start Year: \\
	& & 0: skip (default); \\
	& & + year: absolute year (must be less than begin year of main recruitment deviations); and \\
	& & -integer: set relative to main recruitment deviations start year. \\
	& & Note: because this is a deviation vector, it should be long enough so that recruitment deviations for individual years are not unduly constrained. \\

	\Tstrut & 6 & Early Recruitment Deviations Phase: \\
	& & Negative value: default value to not estimate early deviations. \\
	& & Users may want to set to a late phase if there is not much early data. \\
	
	\Tstrut & 0 & \raisebox{0.1\ht\strutbox}{\hypertarget{FcastRecDevPhase}{Forecast Recruitment Deviations Phase}}: \\
			&   & 0 = Default value. \\
			&   & Forecast recruitment deviations always begin in the first year after the end of the main recruitment deviations. Recruitment in the forecast period is deterministic derived from the specified stock-recruitment relationship. Setting their phase to 0 causes their phase to be set to max lambda phase +1 (so that they become active after rest of parameters have converged.). However, it is possible here to set an earlier phase for their estimation, or to set a negative phase to keep the forecast recruitment deviations at a constant level. \Bstrut\\

	\Tstrut & 1 & Forecast Recruitment Deviations Lambda: \\
			&   & 1 = Default value. \\
			&   & This lambda is for the log likelihood of the forecast recruitment deviations that occur before endyr + 1. Use a larger value here if solitary, noisy data at end of time series cause unruly recruitment deviation estimation. \\
	
	\Tstrut & 1956 & Last year with no bias adjustment. \\
			& 1970 & First year with full bias adjustment. \\
			& 2001 & Last year with full bias adjustment. \\
			& 2002 & First recent year with no bias adjustment. \\
			& 	   & These four entries control how the bias adjustment is phased in and then phased back out when the model is searching for the maximum log likelihood. Bias adjustment is automatically turned off when in \gls{mcmc} mode. For intervening years between the first and second years in this list, the amount of bias adjustment that will be applied is linearly phased in. The first year with full bias adjustment should be a few years into the data-rich period so that the model will apply the full bias-correction only to those recruitment deviations that have enough data to inform the model about the full range of recruitment variability. Defaults for the four-year values: start year - 1000, start year - Nages, main recruitment deviation final year, end year + 1. See \hyperlink{RecBias}{Recruitment Likelihood with Bias Adjustment} for more information. \\
	
	\Tstrut & 0.85 & Max Bias Adjustment: \\
			&	   & > 0: value for the maximum bias adjustment during the \gls{mle} mode. \\
			& 	   & -1: bias adjustment set to 1.0 for all years, including forecast, with estimated recruitment deviations (similar to \gls{mcmc}). \\
			& 	   & -2: bias adjustment set to 1.0 for all years from start to end model year, bias adjustment set to 0 for the forecast period \\
			& 	   & -3: bias adjustment set to 0 for all model and forecast years. \\

	\Tstrut & 0    & Period For Recruitment Cycles: \\
			&      & Use this when the model is configured to model seasons as years and there is a need to impose a periodicity to the expected recruitment level. If value is > 0, then read that number of full parameter lines below define the recruitment cycle. See more information on setting up seasons as years model in the \hyperlink{continuous-seasonal-recruitment-sec}{continuous seasonal recruitment section}. \\
	
	\Tstrut & -5   & Minimum Recruitment Deviation: Min value for recruitment deviation. \\
			&	   & Negative phase = Default value. \\

	\Tstrut & 5	   & Maximum Recruitment Deviation: Max value for recruitment deviation. \\
			&	   & Late Phase = Default value (e.g., 5) \\
	
	\Tstrut & 5   & Number of Explicit Recruitment Deviations to Read: \\
			&      & 0: Default, do not read any recruitment deviations; Integer: read this number of recruitment deviations. \\

	\multicolumn{3}{l}{COND = If N recruitment cycle is > 0, enter N full parameter lines below.} \Tstrut\\
	\Tstrut & <parameter line> & Full parameter line for each of the N periods of recruitment cycle. \Bstrut\\
	\hline

	\multicolumn{3}{l}{COND = If the number of recruitment deviations to read is > 0, then enter a total} \Tstrut\\
	\multicolumn{3}{l}{number of lines equal to that specified above. A year and a deviation value is expected as:} \Bstrut\\
	& 2010 1.27 & Enter year and deviation. \\
	& 2011 -0.45 & \multirow{1}{1cm}[-0.25cm]{\parbox{10cm}{Two example recruitment deviations being read. Note: the model will rescale the entire vector of recruitment deviation after reading these deviations, so by reading two positive values, all other recruitment deviations will be scaled to a small negative value to achieve a sum to zero condition before starting model estimation.}} \\
	& 2012 -0.25 & \\
	& 2013 0.67 & \\
	& 2014 0.20 & \\
	& 2015 -0.11 & \\
	& & \\
	\hline
	
		
	\multicolumn{3}{l}{End of advanced options} \Tstrut\Bstrut\\
	\hline
	
\end{longtable}

\myparagraph{Recruitment Eras}
Conceptually, the model treats the early, data-poor period, the main data-rich period, and the recent/forecast time period as three eras along a continuum. The user has control of the break year between eras. Each era has its own vector. The early era is defined as a vector (prior to V3.10 this was a deviation vector) so it can have zeros during the earliest years not informed by data and then a few years with non-zero values without imposing a zero-centering on this collection of deviations. The main era can be a vector of simple deviations, or a deviation vector, but it is normally implemented as a deviation vector so that the spawner-recruitment function is its central tendency. The last era does not force a zero-centered deviation vector so that it can have zeros during the actual forecast and non-zero values in last few years of the time series. The early and last eras are optional, but their use can help prevent balancing a preponderance of negative deviations in early years against a preponderance of positive deviations in later years. When the 3 eras are used, it would be typical to turn on the main era during an early model phase, turn on the early era during a later phase, then have the last era turn on in the final phase.

\hypertarget{RecBias}{}
\myparagraph{Recruitment Likelihood with Bias Adjustment}
For each year in the total recruitment deviation time series (early, mid, late/forecast) the contribution of that year to the log likelihood is equal to: $dev^2/(2.0*\sigma^2_R)+offset*ln(\sigma_R)$ where offset is the recruitment bias adjustment between the arithmetic and geometric mean of expected recruitment for that year. With this approach, years with a zero or small offset value do not contribute to the second component. $\sigma_R$ may be estimable when there is good data to establish the time series of recruitment deviations.

The implemented recruitment bias adjustment is based upon the work documented in \citet{methot-adjusting-2011} and following the work of \citet{maunder-estimation-2003}. The concept is based upon the following logic. The $\sigma_R$ represents the true variability of recruitment in the population. It provides the constraining penalty for the estimates of recruitment deviations, and it is not affected by data. Where data that are informative about recruitment deviations are available, the total variability in recruitment, $\sigma_R$, is partitioned into a signal (the variability among the recruitment estimates) and the residual, the variance of each recruitment estimate calculated as:

\begin{equation}
SE(\hat{r}_y)^2 + SD(\hat{r})^2=\Bigg( \bigg( \frac{1}{\sigma^2_d}+\frac{1}{\sigma^2_R}\bigg)^{-1/2}\Bigg)^2+\Bigg( \frac{\sigma^2_R}{(\sigma^2_R+\sigma^2_d)^{1/2}}\Bigg)^2=\sigma^2_R
\end{equation}

Where there are no data, no signal can be estimated and the individual recruitment deviations collapse towards 0.0 and the variance of each recruitment deviation approaches $\sigma_R$. Conversely, where there highly informative data about the recruitment deviations, then the variability among the estimated recruitment deviations will approach $\sigma_R$ and the variance of each recruitment deviation will approach zero. Perfect data will estimate the recruitment time series signal perfectly. Of course, we never have perfect data, so we should always expect the estimated signal (variability among the recruitment deviations) to be less than the true population recruitment variability.

The correct offset (bias adjustment) to apply to the expected value for recruitment is based on the concept that a time series of estimated recruitments should be mean unbiased, not median unbiased, because the biomass of a stock depends upon the cumulative number of recruits, which is dominated by the large recruitments. The degree of offset depends upon the degree of recruitment signal that can be estimated. Where no recruitment signal can be estimated, the median recruitment is the same as the mean recruitment, so no offset is applied. Where log-normal recruitment signal can be estimated, the mean recruitment will be greater than the median recruitment. The value:

\begin{equation}
	b_y=\frac{E\Big( SD(\hat{r}_y)\Big)^2}{\sigma^2_R}=1-\frac{SE(\hat{r}_y)^2}{\sigma^2_R}
\end{equation}

\noindent of the offset then depends upon the partitioning of $\sigma_R$ into between and within recruitment variability. The most appropriate degree of bias adjustment can be approximated from the relationship among $\sigma_R$, recruitment variability (the signal), and recruitment residual error. Because the quantity and quality of data varies during a time series, the user can control the rate at which the offset is ramped in during the early, data-poor years, and then ramped back to zero for the forecast years. On output, the mean bias adjustment during the early and main eras is calculated, comparing this value to the \gls{rmse} of estimated recruitment deviations in the \texttt{Report.sso} file. A warning is generated if the \gls{rmse} is small and the bias adjustment is larger than 2.0 times the ratio of $RMSE^2$ to $\sigma^2_R$. Additional information on recruitment bias adjustment can be found in the \hyperlink{BiasCorrect}{Recruitment Variability and Bias Correction section}.

In \gls{mcmc} mode, the model still draws recruitment deviations from the log-normal distribution, so the full offset is used such that the expected mean recruitment from this log-normal distribution will stay equal to the mean from the spawner-recruitment curve. When the model reaches the \gls{mcmc} and MCEVAL phases, all bias adjustment values are set to 1.0 for all active recruitment deviations because the model is now re-sampling from the full log-normal distribution of each recruitment.

\myparagraph{Recruitment Cycle}
When the model is configured such that seasons are modeled as years, the concept of season within year disappears. However, there may be reason to still want to model a repeating pattern in expected recruitment to track an actual seasonal cycle in recruitment. If the recruitment cycle factor is set to a positive integer, this value is interpreted as the number of time units in the cycle and this number of full parameter lines will be read. The cyclic effect is modeled as an exp(p) factor times $R_{0}, s$o a parameter value of 0.0 has nil effect. In order to maintain the same number of total recruits over the duration of the cycle, a penalty is introduced so that the cumulative effect of the cycle produces the same number of recruits as $\text{Ncycles}*R_{0}$. Because the cyclic factor operates as an exponential, this penalty is different from a penalty that would cause the sum of the cyclic factors to be 0.0. This is done by adding a penalty to the parameter likelihood. %, where:

%\begin{equation}
%	\begin{split}
%				 X & = \sum(e^p) \\
%				 Y & = Ncycle \\
%				 Penalty & = 100000*(X-Y)^2
%	\end{split}
%\end{equation}

\myparagraph{Initial Age Composition}
A non-equilibrium initial age composition is achieved by setting the first year of the recruitment deviations before the model start year. These pre-start year recruitment deviations will be applied to the initial equilibrium age composition to adjust this composition before starting the time series. The model first applies the initial $F$ level to an equilibrium age composition to get a preliminary N-at-age vector and the catch that comes from applying the $F$s to that vector, then it applies the recruitment deviations for the specified number of younger ages in this vector. If the number of estimated ages in the initial age composition is less than maximum age, then the older ages will retain their equilibrium levels. Because the older ages in the initial age composition will have progressively less information from which to estimate their true deviation, the start of the bias adjustment should be set accordingly.

\hypertarget{FMethod}{}
\subsection[Fishing Mortality Method]{\protect\hyperlink{FMethod}{Fishing Mortality Method}}
The implementation and reporting of fishing mortality, $F$, in SS3 is more complex than in simpler models and can be confusing. The description provides an overview of the ways in which $F$ is calculated, used, and reported.

\myparagraph{Nomenclature}

The nomenclature below ignores sex, morphs and areas for simplicity. The quantities associated with $F$ calculations are defined as:The quantities associated with $F$ calculations are defined as:

\begin{itemize}
	\item $f$ is fleet.
	\item $t$ is a time step; continuous across years $y$ and seasons $s$; equivalent to year if only 1 season.
	\item $a$ is age.
	\item $C_{t,f}$ is fleet-specific catch in a time step.
	\item $B_{t,f}$ is fleet specific available biomass, e.g., total biomass filtered by fleet-specific age selectivity, $s_{t,f,a}$.
	\item $s_{t,f,a}$ is age-specific selectivity for a fleet. If selectivity is length-specific, then age-specific selectivity is calculated as the dot product across length bins of length selectivity and the normal (or log-normal) distribution of length-at-age. If selectivity is both length- and age-based, which is an entirely normal concept in SS3, then age selectivity due to length selectivity is calculated first, then multiplied by the direct age selectivity. This compound age selectivity is used in the mortality calculations and is reported as $Asel2$ in report:32 of \texttt{Report.sso}. See appendix to \citet{methotstock2013} for more detail on this.
	\item $F_{t,f}'$ is the fully-selected fishing mortality for a fleet. The manual will refer to it as $F'$ or $\text{full\_}F$. If your model is using $F'\text{s}$ as parameters, then the parameter values are for $F'$.
	\item $\text{apical\_}F$ is the maximum $F$ among the ages. It is not used explicitly in SS3 although some sections of the manual may state $\text{apical\_}F$ instead of the correct term, full\_$F$.
	\item $F_{t,f,a}$ is age and fleet-specific fishing mortality rate equal to $F_{t,f}' * s_{t,f,a}$. Note that it is possible for no age to have a selectivity equal to 1.0. Some selectivity curves are forced to have maximum selectivity = 1.0 such that $\text{apical\_}F$ and $\text{full\_}F$ will be the same, but some curves never reach 1.0 and some non-parametric forms allow selectivity > 1.0. In all cases, $F'$ is still the rate for the hypothetical age that has selectivity equal to 1.0. The reported $F'$ values are not rescaled to be an $F$ for the age with peak selectivity. Users need to take this into account if they are comparing reported $F'$ values to reported vector of $F_{t,f,a}$ values.
	\item $\text{ann}F_y$ is a measure of the total fishing intensity for a year, based on one of several user-specified options (see below).
	\item $F\text{std}_y$ is a standardized measure of the total fishing intensity for a year and is reported in the derived quantities, so variance is calculated for this quantity. See below for how it relates to $\text{ann}F$.
	\item $SPR_y$ is the equilibrium spawning biomass per recruit that would result from fishing at the current year’s $F$ level and selectivity.
\end{itemize}

Terminology and reporting of $\text{ann}F$ and $F\text{\_std}$ has been slightly revised for clarity in v.3.30.15.00 and the description here follows the new conventions.

\myparagraph{F\_Method}
There are two approaches for estimating fishing mortality ($F$) in Stock Synthesis. One provides a mid-season harvest rate using Pope’s approximation, the other provides a season-long $F$ rate using the Baranov catch equation. Pope’s harvest rate is implemented as F\_Method = 1. The subsequent options model $F$ as a season-long rate using the Baranov catch equation.

\begin{itemize}
	\item F\_Method = 2 represents $F$ as a parameter, $F_{par}$, for all fishing fleets. Because it is a parameter, its estimation is influenced by all data in the model, with retained catch and discard catch having the greatest influence depending on the standard error for these observations. Starting values for the $F_{par}$ can be calculated in early model phases using the hybrid approach (below), then copying those $F_{hyb}$ values into the $F_{par}$ values beginning in a specified phase for all fleets;
	\item F\_Method = 3 represents $F$ as a tuned factor, $F_{hyb}$ using Pope's and Baranov catch equations sequentially in what is termed the hybrid method. The tuning is based on the retained catch for each fishing fleet;
	\item F\_Method = 4 is a fleet-specific superset of F\_Methods 2 and 3 and is the recommended method for modeling $F$ in Stock Synthesis.
	\item Discards: SS3 is calculating the $F'$ to match the retained catch conditional on the fraction of total catch that is retained if the discard/retention feature is used. The $F$ creates the total catch, then the retention curve partitions it into retained and discarded portions. With hybrid and Pope’s methods, the close tuning to retained catch can result in very imprecise fits to the discard data. If the precision of discard data and catch data are of comparable magnitudes, then it is better to use $F$ as parameters. SS3 will be using one $F’$ value to attempt to match two data types. Time-varying retention curves can allow SS3 to fit both catch and discard precisely. But with a non-time-varying retention curve, the fit to catch and discard data will depend on the relative precision of the two data types.
\end{itemize}

The $F_{hyb}$ approach works by:
\begin{enumerate}[a.]
	\item Applying the Pope’s method to get a harvest rate for each fleet in the current season;
	\item Converting that harvest rate to the equivalent $F_{hyb}$. This is exact with one fleet and approximate with multiple fleets;
	\item Adjusting those $F_{hyb}$ values over a fixed number of iterations (2-4) using the ratio of observed to calculated catch for each fleet; and
	\item Proceeding with those $F_{hyb}$ values into subsequent model steps. $F_{par}$ and $F_{hyb}$ values are used in the same Baranov catch equation and a catch log likelihood is calculated based on the observed retained catch and the annual standard error of the catch.
\end{enumerate}

Some notes:
\begin{itemize}
	\item At moderate $F$ levels, hybrid should get a near exact match to the retained catch even if the catch standard error is high. This may result in poor fit to discard catch data if it exists.
	\item At high $F$ and/or with many fleets, the hybrid approach may not get to an exact match to the observed catch.
	\item At high $F$, the problem becomes quite computationally stiff for Pope’s approximation and the hybrid method so convergence in \gls{admb} may slow due to more sensitive gradients in the log likelihood with regard to other model parameters. Whereas, \gls{admb} adjusts the $F_{par}$ values slowly over the entire sequence of iterations, so it may converge with fewer iterations.
	\item The hybrid approach performs best when the catch is known with high precision (standard error < ~ 0.05) and the total $F$ across all fleets is not much greater than natural mortality. The $F$ as parameter approach works best when total $F$ is high; also where a fleet has both retained catch and discarded catch, because the $F$ is influenced by both. 
	\item With F\_Method 4, fleets with low $F$ can apply $F_{hyb}$ across all model phases and high $F$ fleets can switch to $F_{par}$ during later phases.
	\item It is always advisable to allow the model to start with good starting values for parameters. This can be done by specifying a later phase (> 1) under the conditional input for F\_Method = 2 where early phases will use the hybrid method, then switch to $F$ as parameter in later phases and transfer the hybrid $F$ values to the parameter initial values. Same advice for using the F\_Method = 4. However, bycatch fleets do not have retained catch, so cannot use the hybrid method. They must use $F_{par}$ with user-specified starting value starting in phase 1.
	\item Tests have demonstrated that the $F$ approach has negligible impact on the variance of derived quantities, such as spawning biomass in the final year.
	\item It is possible to estimate $F_{par}$ for a particular fleet $\times$ time even if it has an unknown catch observation (for example, if you have years of catch data followed by a gap and then catch data again, can you estimate the missing catch data in SS3). This certainly is true if there is a discard observation for that fleet $\times$ time, but the effect of the $F_{par}$ on the population age composition and trends also allows the survey and composition data to influence the estimates of the $F_{par}$s. A catch observation must exist in order to trigger SS3 to estimate a $F_{par}$ for that fleet $\times$ time, so enter a dummy (but reasonable) value for the catch observation and give it a very large \gls{se} so that the deviations from the input catch observations will only be slightly penalized. Make sure that you use F\_Method = 4 so that the parameter approach will be used for that fleet. If the $F$ values for those years fluctuate dramatically, you can stabilize those $F$ values by adding a dummy effort (survey type = 2) time series. For example, if you are missing catch for 2012--2014, enter an effort value of 1.0 for those years and at least one adjacent year for which SS3 is already able to estimate $F$. This will stabilize the missing year $F$s to be similar to the $F$s for the adjacent years.

\end{itemize}

\begin{longtable}{p{1cm} p{3cm} p{11cm}}
	\multicolumn{3}{l}{Control file continued:} \\
	\hline
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endfirsthead

	\hline
	\multicolumn{2}{l}{Typical Value} & Description and Options \Tstrut\Bstrut\\
	\hline
	\endhead

	\hline
	\endfoot
	\endlastfoot

	0.2 \Tstrut & & $F$ ballpark \\
		& & This value is compared to the sum of the $F$'s for the specified year (defined on the next line). The sum is over all seasons and areas. In older versions of SS3, the lambda was automatically set to 0.0 in the final phase, the user now has control over whether to reduce the \hyperlink{Lambdas}{lambda} in later phases. \Bstrut\\
	\hline

	-1990\Tstrut & & $F$ ballpark year \\
		& & Negative value disable $F$ ballpark. \Bstrut\\
	\hline

	3 \Tstrut & & F\_Method \\
	   & & 1 = Pope's (discrete); \\
	   & & 2 = Baranov (continuous) $F$ as a parameter; \\
	   & & 3 = Hybrid $F$; and \\
	   & & 4 = Fleet-specific parameter/hybrid $F$ (recommended). \Bstrut\\
	\hline

	2.9 \Tstrut & & Maximum $F$ \\
	 & & This maximum is applied within each season and area. A value of 0.9 is recommended for F\_Method 1, and a value of about 4 is recommended for F\_Methods 2 and 3. \Bstrut\\
	\hline

	\multicolumn{3}{l}{COND: F\_Method = 1, no additional input for Pope's approximation.} \Tstrut\Bstrut\\
	\hline

	\multicolumn{3}{l}{COND: F\_Method = 2:} \Tstrut\\
	& 0.10 1 1 & Initial $F$ value, phase, and the number of $F$ detail setup lines to read (example has 1). \\
	&  & For phases prior to the phase of the $F$ value becoming active, the hybrid option will be used and the $F$ values so calculated become the starting values for the $F$ parameters when this phase is reached. \\
	\multicolumn{3}{l}{If N for $F$ detail is > 0, read that number of input lines} \Tstrut\\
	\multicolumn{2}{l}{1 1980 1 0.20 0.05 4} & Fleet, year, season, $F$, \gls{se}, phase - these fleet-time specific values override corresponding values in the data file and the overall starting $F$ value and phase read just above. \Bstrut\\
	\hline

	\multicolumn{3}{l}{COND: F\_Method = 3:} \Tstrut\\
	& 4 & Number of tuning iterations in hybrid fleets. A value of 3 is sufficient with a single fleet and low $F$s. Larger values match the catch more exactly when there are many fleets and high $F$. \Bstrut\\
	\hline
	
	\multicolumn{3}{l}{COND: F\_Method = 4} \Tstrut\\
	& & Read list of fleets needing parameters, starting $F$ values, and phases. To treat a fleet $F$ as hybrid only either select a phase of 99 or do not enter a parameter line for that fleet. A parameter line is not required for all fleets and if not specified will be treated as hybrid across all phases, except for bycatch fleets which are required to have an input parameter line. Use a negative phase to set $F$ as constant (i.e., not estimated) in v.3.30.19 and higher. \Tstrut\\
	Fleet & Parameter Value & Phase \Tstrut\\
	1 & 0.05 & 2 \\
	2 & 0.01 & 1 \# bycatch fleet \\
	-9999 & 1 & 1 \Bstrut\\
	or & & \\
	-9998 & 1 & 1 \# to invoke reading $F$ details after reading hybrid tuning loop \Bstrut\\
 
	& 4 & Number of hybrid tuning iterations. A value of 2 is OK if fleet switches to parameters; 3 is sufficient with a single fleet and low $F$s; larger values match the catch near exactly when there are many fleets and high $F$. \Tstrut\Bstrut\\

	\hline
	\multicolumn{3}{l}{COND: list terminator was -9998, so read $F$ details } \Tstrut\\
	\multicolumn{2}{l}{1 1980 1 0.20 0.05 4} & Fleet, year, season, $F$, \gls{se}, phase. \Bstrut\\
	\multicolumn{2}{l}{1 1981 1 0.25 0.05 4} & Fleet, year, season, $F$, \gls{se}, phase. \Bstrut\\
	\multicolumn{2}{l}{-9999 1980 1 0.20 0.05 4} & terminator. \Bstrut\\
	\hline

\end{longtable}

\hypertarget{EquilSPR}{}
\subsubsection[Equilibrium SPR]{\protect\hyperlink{EquilSPR}{Equilibrium SPR}}
$SPR_y$ is the equilibrium spawning biomass per recruit that would result from fishing at the current year’s $F$ level and selectivity. It is a measure of the expected long-term effect of fishing. It is calculated as the ratio of the equilibrium reproductive output per recruit that would occur with the current year's $F$ intensities and biology, to the equilibrium reproductive output per recruit that would occur with the current year's biology and no fishing. Thus, it internalizes all seasonality, movement, weird selectivity patterns, and other factors. Because this index moves in the opposite direction than $F$ itself, it is usually reported as $1-SPR$. A benefit of this index is that it is a direct measure of common proxies used for $F_{MSY}$, such as $F_{40\%}$. A shortcoming of this index is that it does not directly demonstrate the fraction of the stock that is caught each year. The \gls{spr} value is also calculated in the benchmarks (see below). 

The derived quantities report shows an annual \gls{spr} statistic. The options, as specified in the \texttt{starter.ss} file, are:
\begin{itemize}
	\item 0 = skip
	\item 1 = $(1-SPR)/(1-SPR_{TARGET})$
	\item 2 = $(1-SPR)/(1-SPR_{MSY})$
	\item 3 = $(1-SPR)/(1-SPR_{B_{TARGET}})$
	\item 4 = raw \gls{spr}
\end{itemize}

\hypertarget{InitF}{}
\subsubsection[Initial Fishing Mortality]{\protect\hyperlink{InitF}{Initial Fishing Mortality}}
Read a short parameter setup line for each fishery and season when there is non-zero equilibrium catch in a season for the fleet (equilibrium catches are input in the \hyperlink{CatchFormat}{catch section of the data file}). The parameters are the fishing mortalities for the initial equilibrium catches. Do not try to estimate parameters for fisheries with zero initial equilibrium catch - no parameter line is needed fleets and seasons with zero equilibrium catch.

If there is catch, then give a starting value greater than zero, and it generally is best to estimate the parameter in phase 1. The initial $F$ parameter lines are ordered as shown in the example below - by season, then within a season, by fleet.

If the initial equilibrium catch is near \gls{msy}, than a logical inconsistency may occur as documented in the \hyperlink{EquilRecr}{Equilibrium Recruitment section}. 

It is possible to use the initial $F$ method to achieve an estimate of the initial equilibrium $Z$ in cases where the initial equilibrium catch is unknown. To do this requires 2 changes to the input files:
\begin{enumerate}
	\item Data File: Include a positive value for the initial equilibrium catch for at least one fleet, often with a higher standard error depending upon the situation.
	\item Control File: Add an initial $F$ parameter line (short parameter line) for each fleet and season with initial equilibrium catch to be estimated immediately after the Fishing Mortality setup. It will be influenced by the early age and size comps which should have some information about the early levels of $Z$.
\end{enumerate}

\begin{longtable}{p{1.3cm} p{1cm} p{1cm} p{1cm} p{1.5cm} p{1.2cm} p{1cm} p{2.5cm}}
	\multicolumn{8}{l}{An example setup with two fishery fleets and two seasons with initial equilibrium catches:} \\
	\hline
	0.1 & \multicolumn{7}{l}{\# $F$ ballpark} \Tstrut\Bstrut\\
	\hline
	-2001 & \multicolumn{7}{l}{\# $F$ ballpark year (negative value to disable)} \Tstrut\Bstrut\\
	\hline
	3 & \multicolumn{7}{l}{\# F\_method: 1=Pope; 2=Baranov; 3=Hybrid} \Tstrut\Bstrut\\
	\hline
	3 & \multicolumn{7}{l}{\# Maximum $F$ value} \Tstrut\Bstrut\\
	\hline
	4 & \multicolumn{7}{l}{\# Number of iterations for tuning $F$ in hybrid method} \Tstrut\Bstrut\\
	\hline
	\multicolumn{8}{l}{\# Initial $F$ parameters} \Tstrut\Bstrut\\
	LO & HI & INIT & Prior & Pr. \gls{sd} & Pr. Type & Phase & Label \Bstrut\\
	\hline
	0 & 3 & 0.1 & 0 & 99 & 0 & 1 & \#InitF\_seas\_1\_fleet\_1 \Tstrut\\
	\hline
	0 & 3 & 0.1 & 0 & 99 & 0 & 1 & \#InitF\_seas\_1\_fleet\_2 \Tstrut\\
	\hline
	0 & 3 & 0.1 & 0 & 99 & 0 & 1 & \#InitF\_seas\_2\_fleet\_1 \Tstrut\\
	\hline
	0 & 3 & 0.1 & 0 & 99 & 0 & 1 & \#InitF\_seas\_2\_fleet\_2 \Tstrut\\
	\hline
\end{longtable}


\hypertarget{Qsetup}{}
\subsection[Catchability]{\protect\hyperlink{Qsetup}{Catchability}}
Catchability is the model process that converts selected numbers or biomass for a fleet into the expected value for a survey or \gls{cpue} by that fleet. In SS3, the concept has been extended so that, for example, a time series of an environmental factor could be treated as a survey of the time series of deviations for some parameter. Thus, the concept of catchability is expanded to include a family of link functions beyond simple proportionality.

Collectively, all factors that need a catchability are considered to be an index. Note that the catchability options entered in this section of the control file have a strong relationship with the index units (i.e., biomass vs. numbers vs. deviations) and index error type (i.e., normal vs. T-distribution) as entered in the data file.

For each fleet that has index observations, enter a row with six entries as described below. Fleets with no index observations are omitted.

\begin{enumerate}
	\item Fleet Number
	\item Link type or index of deviation vector: An assumed functional form between Q, the expected value, and the survey observation. See \hyperlink{QParams}{example Q parameter lines} below for an example set up for link types 4-6.
	\begin{enumerate}[(a)]
		\item 1 = simple Q, e.g., proportional: $y=Q*x$ where $x$ is a model quantity, like selected biomass, and $y$ is the expected value for the index.
		\item 2 = mirror simple Q - this will mirror the Q value from another fleet. Mirror in Q must refer to a lower number fleet relative to the fleet with the mirrored Q (example: fleet 3 mirror fleet 2). Requires a Q parameter line for the fleet but will not be used.
		\item 3 = power function to allow non-linearity in the expected value for the index: $y=Qx^{(1+c)}$. Therefore, $c > 0$ leads to hyper-stability and $c < 0$ leads to hyper-depletion. The power function option cannot be used with deviation surveys (type 35 or 36) because of negative values in the deviation vectors.
		\item 4 = mirror Q with scale (2 parameter lines required) with the second parameter (scale) being added to the Q being mirrored. The mirrored Q will be reported as base Q + scale value. Mirror in Q must refer to a lower number fleet relative to the fleet with the mirrored Q. An example usage is when the \gls{cpue} of a fleet in one area is assumed to have the same catchability as the \gls{cpue} for a comparable fleet operating in another area. The scale parameter could be used to adjust for the relative spatial areas because Q relates \gls{cpue} to area-specific population abundance, not population density per area.
		\item 5 = offset (2 parameter lines required). This option, new with v.3.30.23, requires a second parameter that is added to the expected values before multiplying Q. This is most useful for survey types 35 and 36, even if those survey input vectors have already been zero centered. $y=Q*(x+B)$
		\item 6 = offset and power (3 parameter lines required). This requires 2 parameters in addition to the Q parameter. The first is for the offset and the second is for the power, $y=Q*(x+b)^{(1+c)}$.
	\end{enumerate}
	\item \hypertarget{link_info}{Extra input for link information (i.e., mirror fleet or dev index number)}
	\begin{enumerate}[(a)]
		\item > 0 = mirror the Q from another (lower numbered survey designated by referencing the fleet number).
		\item If an index of a deviation vector , option 35, use this column to enter the index of the deviation vector to which the index is related. For example, if only using one index in your model, this number would be 1.
		\item If a depletion survey, option 34, approach is being applied the following values in this column determines how phases are adjusted:
		\begin{itemize}
			\item 0 = add 1 to phases of all parameters. Only $R_{0}$ active in new phase 1. Mimics the default option of previous model versions;
			\item 1 = only $R_{0}$ active in phase 1. Then finish with no other parameters becoming active; useful for data-limited draws of other fixed parameters. Essentially, this option allows the model to mimic \gls{dbsra}; and
			\item 2 = no phase adjustments, can be used when profiling on fixed $R_{0}$.
		\end{itemize}
	\end{enumerate}
	\item Extra\_se: Estimable extra standard error for an index
	\begin{enumerate}[(a)]
		\item 0 = skip (typical); and
		\item 1 = include a parameter that will contain a value to be added to the input standard deviation of the survey variability.
	\end{enumerate}
	\item Bias\_adj: Adjusts for log-normal bias when using an informative prior on Q. \textbf{NOTE: Bias adjustment to Q is ONLY applied when also using the float approach. See below for Q float specifications.} An expanded bias adjustment approach is under development.
	\begin{enumerate}[(a)]
		\item 0 = no bias adjustment applied; and
		\item 1 = apply bias adjustment. Bias correction will be applied to the estimated Q value.
	\end{enumerate}
	\item Float: Allows Q parameter to be automatically calculated to maintain no deviation between the index and the expected value. Only available for link = 1.
	\begin{enumerate}[(a)]
		\item 0 = no float, parameter is estimated; and
		\item 1 = float, analytical solution is used, but parameter line still required.
		\item Additional information regarding the use of and appropriate application of float in Q can be found in the \hyperlink{FloatQ}{Float Q} section below.
	\end{enumerate}
\end{enumerate}

\begin{longtable}{p{2cm} p{2cm} p{2cm} p{2cm} p{2cm} p{1.3cm} p{2.3cm}}
	\multicolumn{7}{l}{For a setup with a single survey, the Q setup matrix could be:} \\
	\hline
	Fleet \Tstrut & Link & Link & Extra    & Bias   & & \\
	Num.          & Type & Info & \gls{sd} & Adjust & Float & Label \Bstrut\\
	\hline
	3 & 1 & 0 & 1 & 1 & 0 & \#Survey \Tstrut\\
	-9999 & 0 & 0 & 0 & 0 & 0 & \#End Read \Bstrut\\
	\hline
\end{longtable}


\begin{longtable}{p{1cm} p{1cm} p{1cm} p{1.5cm} p{1.5cm} p{1.5cm} p{1.75cm} p{4cm}}
	\hline
	LO \Tstrut & HI & INIT & <other entries> & PHASE & <other entries> & Block Fxn & Parameter Label \Bstrut\\
	\hline
	\endfirsthead

	\hline
	LO \Tstrut & HI & INIT & <other entries> & PHASE & <other entries> & Block Fxn & Parameter Label \Bstrut\\
	\hline
	\endhead

	\hline
	\endfoot
	\endlastfoot

	-5 & 5 & -0.12 & \multicolumn{1}{c}{...} &  1 & \multicolumn{1}{c}{...} & 0 & \#Survey1 LnQ base \Tstrut\\
	 0 & 0.5 & 0.1 & \multicolumn{1}{c}{...} & -1 & \multicolumn{1}{c}{...} & 0 & \#Survey1 Extra \gls{sd} \Bstrut\\
	\hline
\end{longtable}

If the Q base parameter specifies that it is time-varying by the annual deviation method, short parameter lines to specify the specifications of the deviation vector come after all the base Q parameters.

\hypertarget{QParams}{}
\subsubsection[Example Q parameter lines]{\protect\hyperlink{QParams}{Example Q parameter lines}}
Below is an example setup for fleets with a mirrored Q and scale from another fleet (link type = 4), scale from another fleet with offset (link type = 5), and scale from another fleet with offset and power (link type = 5):
\begin{longtable}{p{1cm} p{1cm} p{1cm} p{1cm} p{1cm} p{1cm} p{7.6cm}}
	\multicolumn{7}{l}{For a setup with a single survey, the Q setup matrix could be:} \\
	\hline
	Fleet \Tstrut & Link & Link & Extra    & Bias   & & \\
	Num.          & Type & Info & \gls{sd} & Adjust & Float & Label \Bstrut\\
	\hline
	1 & 1 & 0 & 1 & 0 & 0 & \#Fleet 1 \Tstrut\\
	2 & 4 & 1 & 0 & 0 & 0 & \#Fleet 2 \\
	3 & 5 & 0 & 0 & 0 & 0 & \#Fleet 3 using Q with offset parameter \\
    4 & 6 & 0 & 0 & 0 & 0 & \#Fleet 4 using Q with offset and power parameters \\
	-9999 & 0 & 0 & 0 & 0 & 0 & \#End Read \Bstrut\\
	\hline
\end{longtable}


\begin{longtable}{p{1cm} p{1cm} p{1cm} p{1.5cm} p{1.5cm} p{1.5cm} p{1.75cm} p{4cm}}
	\multicolumn{8}{l}{A long parameter line is expected for each link parameter (i.e., Q)} \\
	\hline
	LO \Tstrut & HI & INIT & <other entries> & PHASE & <other entries> & Block Fxn & Parameter Label \Bstrut\\
	\hline
	-7  & 5   & 0.51 & \multicolumn{1}{c}{...} &  1 & \multicolumn{1}{c}{...} & 0 & \#Fleet 1 LnQ base \Tstrut\\
	 0  & 0.5 & 0.1  & \multicolumn{1}{c}{...} & -1 & \multicolumn{1}{c}{...} & 0 & \#Fleet 1 Extra \gls{sd} \\
	-7  & 5   & -6   & \multicolumn{1}{c}{...} & -1 & \multicolumn{1}{c}{...} & 0 & \#Fleet 2 LnQ base \\
	-8  & 5   & -7   & \multicolumn{1}{c}{...} & -1 & \multicolumn{1}{c}{...} & 0 & \#Fleet 2 Mirror Q offset \\
	-15 & 15  & 0.84 & \multicolumn{1}{c}{...} &  1 & \multicolumn{1}{c}{...} & 0 & \#Fleet 3 Q base \\
    -15 & 15  & 0    & \multicolumn{1}{c}{...} &  1 & \multicolumn{1}{c}{...} & 0 & \#Fleet 3 Q offset \\
	-10 & 10  & 0.74 & \multicolumn{1}{c}{...} &  1 & \multicolumn{1}{c}{...} & 0 & \#Fleet 4 Q base \\
    -10 & 10  & 0    & \multicolumn{1}{c}{...} &  1 & \multicolumn{1}{c}{...} & 0 & \#Fleet 4 Q offset \\
    0.2 & 3.0 & 0.5  & \multicolumn{1}{c}{...} &  3 & \multicolumn{1}{c}{...} & 0 & \#Fleet 4 Q power \Bstrut\\
	\hline
\end{longtable}

\hypertarget{FloatQ}{}
\subsubsection[Float Q]{\protect\hyperlink{FloatQ}{Float Q}}
The use and development of float in Q has evolved over time within SS3. The original approach in earlier versions of SS3 (version 3.24 and before) is that with Q ``float'' the units of the survey or fishery \gls{cpue} were treated as dimensionless so the Q was adjusted within each model iteration to maintain a mean difference of 0.0 between observed and expected (usually in natural log space). In contrast, Q as a parameter (float = 0) one had the ability to interpret the absolute scaling of Q and put a prior on it to help guide the model solution. Also, with Q as a parameter the code allowed for Q to be time-varying.

Then midway through the evolution of the v.3.24 code lineage a new Q option was introduced based on user recommendations. This option allowed Q to float and to compare the resulting Q value to a prior, hence the information in that prior would pull the model solution in direction of a floated Q that came close to the prior.

Currently, in v.3.30, that float with prior capability is fully embraced. All fleets that have any survey or \gls{cpue} options need to have a catchability specification and get a base Q parameter in the list. Any of these Q's can be either:

\begin{itemize}
	\item Fixed: by not floating and not estimating.

	\item Floating: not estimated as an active parameter, set phase to negative, and not capable of being time-varying. Can have a prior, or not. Future versions may allow Q to be time-varying and then rescaling that Q vector according to the float logic, but this is not yet currently implemented.

	\item Estimated as active parameter: so not floating. Can be time-varying and can have a prior.
\end{itemize}


Q relates the units of the survey or \gls{cpue} to the population abundance, not the population density per unit area. But many surveys and most fishery \gls{cpue} is a proportional to mean fish density per unit area. This does not have any impact in a one area model because the role of area is absorbed into the value of Q. In a multi-area model, one may want to assert that the relative difference in \gls{cpue} between two areas is informative about the relative abundance between the areas. However, \gls{cpue} is a measure of fish density per unit area, so one may want to multiply \gls{cpue} by area before putting the data into the model so that asserting the same Q for the two areas will be informative about relative abundance.

In v.3.30.13, a new catchability option has been added that allows Q to be mirrored and to add an offset to ln(Q) of the primary area when calculating the ln(Q) for the dependent area. The offset is a parameter and, hence, can be estimated and have a prior. This option allows the \gls{cpue} data to stay in density units and the effect of relative stock area is contained in the value of the ln(Q) offset.

\hypertarget{Q-TV}{}
\subsubsection[Catchability Time-Varying Parameters]{\protect\hyperlink{Q-TV}{Catchability Time-Varying Parameters}}
Time-Varying catchability can be used. Details on how to specify time-varying parameters can be found in the \hyperlink{tvOrder}{Time-Varying Parameter Specification and Setup} section.

\hypertarget{QConversion}{}
\subsubsection[Q Conversion Issues Between Stock Synthesis v.3.24 and v.3.30]{\protect\hyperlink{QConversion}{Q Conversion Issues Between Stock Synthesis v.3.24 and v.3.30}}
In v.3.24 it was common to use the deviation approach implemented as if it was survey specific blocks to create a time-varying Q for a single survey. In some cases, only one year's deviation was made active in order to implement, in effect, a block for Q. The transition executable (\texttt{ss\_trans.exe}) cannot convert this, but an analogous approach is available in v.3.30 because true blocks can now be used, as well as environmental links and annual deviations. Also note that deviations in v.3.24 were survey specific (so no parameter for years with no survey). In v.3.30, deviations are always year-specific, so you might have a deviation created for a year with no survey.

\hypertarget{SelDiscard}{}
\subsection[Selectivity and Discard]{\protect\hyperlink{SelDiscard}{Selectivity and Discard}}
For each fleet and survey, read a definition line for size selectivity and retention. 

\begin{center}
	\begin{longtable}{p{2cm} p{2cm} p{2cm} p{2cm} p{6.5cm}}
		\multicolumn{5}{l}{Example Setup for Selectivity:} \Tstrut\\
		\hline
		\multicolumn{5}{l}{Size Selectivity:} \Tstrut\\
		Pattern & Discard & Male & Special & Label \Bstrut\\
		\hline
		1 & 2 & 0 & 0 & \#Fishery1 \Tstrut\\
		1 & 0 & 0 & 0 & \#Survey1 \\
		0 & 0 & 0 & 0 & \#Survey2 \Bstrut\\
		\hline
		
		\multicolumn{5}{l}{Age Selectivity:} \Tstrut\\
		Pattern & Discard & Male & Special & Label \Bstrut\\
		\hline
		11 & 0 & 0 & 0 & \#Fishery1 \Tstrut\\
		11 & 0 & 0 & 0 & \#Survey1 \\
		11 & 0 & 0 & 0 & \#Survey2 \Bstrut\\
		\hline
	\end{longtable}
\end{center}

\myparagraph{Pattern}
Specify the size/age selectivity pattern. See the \hyperlink{SelexPattern}{Selectivity Pattern} section for user options.

\myparagraph{Discard}
\hypertarget{DomeRetention}{}
Discard options:
\begin{itemize}
	\item Option = 0: no discarding by fleet.
	\item Option = 1: program will read 4 retention parameters after reading the specified number of selectivity parameters and all discarded fish are assumed dead.
	\item Option = 2: program will read 4 retention parameters and 4 discard mortality parameters.
	\item Option = 3: no additional parameters are read and all fish are assumed discarded and dead.
	\item Option = 4: program will read 7 retention parameters for dome-shaped retention and 4 discard mortality parameters.
	\item Option = negative fleet number: will mirror the retention and discard mortality pattern of the lower numbered fleet.
\end{itemize}

\myparagraph{Male}
Male specific selectivity options:
\begin{itemize}
	\item Option = 0: no male specific selectivity parameters required. Male and female selectivity will be the same.
	\item Option = 1: program will read 4 additional parameters to define the male selectivity relative to the female selectivity. Anytime the male selectivity is caused to be greater than 1.0; the entire male/female matrix of selectivity values is scaled by the max so that the realized max is 1.0. Note, this may cause gradient problems.
	\item Option 2: main selectivity parameters define male selectivity and female selectivity is estimated as an offset from male selectivity. This alternative is preferable if female selectivity is less than male selectivity.
	\item Option 3: only available if the selectivity pattern is 1, 20, or 24, and it causes the male selectivity parameters to be offset from the female parameters, rather than the male selectivity being an offset from the female selectivity.
	\item Option 4: similar to Option 3 only with the female parameters offset from the male parameters.
\end{itemize}

\myparagraph{Special}
Special (0/value): This value is used in different ways depending on the context. If the selectivity type is to mirror another selectivity type, then put the index of that source fleet or survey here. It must refer to a lower numbered fleet/survey. If the selectivity type is 6 (linear segment), then put the number of segments here. If the selectivity type is 7, then put a 1 here to keep selectivity constant above the mean average size for old fish of morph 1. If selectivity type is 27 (cubic spline), then put the number of nodes (knots) here.

\myparagraph{Age Selectivity}
For each fleet and survey, read a definition line for age selectivity. The 4 values to be read are the same as for the size-selectivity. 

As of v.3.30.15, for some selectivity patterns the user can specify the minimum age of selected fish. Most selectivity curves by default select age 0 fish (i.e., inherently specify the minimum age of selected fish as 0). However, it is fairly common for the age bins specified in the data file to start at age 1. This means that any age 0 fish selected are pooled up into the age 1' bin, which will have a detrimental effect on fitting age-composition data. In order to prevent the selection of age 0 (or older) fish, the user can specify the minimum selected age for some selectivity patterns (12, 13, 14, 16, 18, 26, or 27) in versions of v.3.30.15 and later. For example, if the minimum selected age is 1 (so that age 0 fish are not selected), selectivity pattern type can be specified as 1XX, where XX is the selectivity pattern. A more specific example is if selectivity is age-logistic and the minimum selected age desired is 1, the selectivity pattern would be specified as 112 (the regular age-logistic selectivity pattern is option 12). The user can also select higher minimum selected ages, if desired; for example, 212 would be the age-logistic selectivity pattern with a minimum selected age of 2 (so that age 0 and 1 fish are not selected).

\hypertarget{SelRetParam}{}
\subsubsection[Reading the Selectivity and Retention Parameters]{\protect\hyperlink{SelRetParam}{Reading the Selectivity and Retention Parameters}}
Read the required number of parameter setup lines as specified by the definition lines above. The complete order of the parameter setup lines is:
\begin{enumerate}
	\item Size selectivity for fishery 1;
	\item Retention for fishery 1 (if discard specified);
	\item Discard Mortality for fishery 1 (if discard specified);
	\item Male offsets for size selectivity for fishery 1 (if offsets used);
	\item <repeat for additional fleets and surveys>;
	\item Age selectivity for fishery 1;
	\item Retention for fishery 1 (if discard specified);
	\item Discard Mortality for fishery 1 (if discard specified);
	\item Male offsets for age selectivity for fishery 1 (if offsets used); and
	\item <repeat for additional fleets and surveys>.
\end{enumerate}


\begin{longtable}{p{0.75cm} p{0.75cm} p{0.75cm} p{1.25cm} p{2.75cm} p{1.75cm} p{5cm}}
	\multicolumn{7}{l}{The list of parameters to be read from the above setup would be:} \\
	\hline
	LO \Tstrut & HI & INIT & PRIOR & <other entries> & Block Fxn & Parameter Label \Bstrut\\
	\hline
	\endfirsthead

	\hline
	LO \Tstrut & HI & INIT & PRIOR & <other entries> & Block Fxn & Parameter Label \Bstrut\\
	\hline
	\endhead
		
	19    & 80   & 53.5 & 50  & \multicolumn{1}{c}{...}  & 0   & \#SizeSel p1 fishery 1 \Tstrut\\
	0.01  & 60   & 18.9 & 15  & \multicolumn{1}{c}{...}  & 0   & \#SizeSel p2 fishery 1 \\
	20    & 70   & 38.6 & 40  & \multicolumn{1}{c}{...}  & 0   & \#Retain\_L\_infl\_fishery 1 \\
	0.1   & 10   & 6.5  & 1   & \multicolumn{1}{c}{...}  & 0   & \#Retain\_L\_width\_fishery 1 \\
	0.001 & 1    & 0.98 & 1   & \multicolumn{1}{c}{...}  & 0   & \#Retain\_L\_asymptote\_logit\_fishery 1 \\
	-10   & 10   & 1    & 0   & \multicolumn{1}{c}{...}  & 0   & \#Retain\_L\_maleoffset\_fishery 1 \\
	0.1   & 1    & 0.6  & 0.6 & \multicolumn{1}{c}{...}  & 0   & \#DiscMort\_L\_infl\_fishery 1 \\
	-2    & 2    & 0    & 0   & \multicolumn{1}{c}{...}  & 0   & \#DiscMort\_L\_width\_fishery 1 \\
	20    & 70   & 40   & 40  & \multicolumn{1}{c}{...}  & 0   & \#DiscMort\_L\_level\_old\_fishery 1 \\
	0.1   & 10   & 1    & 1   & \multicolumn{1}{c}{...}  & 0   & \#DiscMort\_L\_male\_offset\_fishery 1 \\
	19    & 80   & 53.5 & 50  & \multicolumn{1}{c}{...}  & 0   & \#SizeSel p1 survey 1 \\
	0.01  & 60   & 18.9 & 15  & \multicolumn{1}{c}{...}  & 0   & \#SizeSel p2 survey 1 \\
	0     & 40   & 0    & 5   & \multicolumn{1}{c}{...}  & 0   & \#AgeSel p1 fishery 1 \\
	0     & 40   & 40   & 5   & \multicolumn{1}{c}{...}  & 0   & \#AgeSel p2 fishery 1 \\
	0     & 40   & 0    & 5   & \multicolumn{1}{c}{...}  & 0   & \#AgeSel p1 survey 1 \\
	0     & 40   & 40   & 5   & \multicolumn{1}{c}{...}  & 0   & \#AgeSel p2 survey 1 \\
	0     & 40   & 0    & 5   & \multicolumn{1}{c}{...}  & 0   & \#AgeSel p1 survey 2 \\
	0     & 40   & 0    & 5   & \multicolumn{1}{c}{...}  & 0   & \#AgeSel p2 survey 2 \Bstrut\\
	\hline
\end{longtable}


\hypertarget{SelexPattern}{}
\subsubsection[Selectivity Patterns]{\protect\hyperlink{SelexPattern}{Selectivity Patterns}}
The currently defined selectivity patterns, and corresponding required number of parameters, are:


\begin{longtable}{p{2cm} p{3cm} p{10cm}}
	\multicolumn{3}{c}{SIZE BASED SELECTIVITY} \Bstrut\\	
	\endfirsthead

	\hline
	Pattern & N Parameters & Description \Tstrut\Bstrut\\
	\hline
	\endhead

	\hline
	\endfoot
	\endlastfoot

	\hline
		
	Pattern & N Parameters & Description \Tstrut\Bstrut\\
	\hline
	0 \Tstrut & 0 & Selectivity = 1.0 for all sizes. \\
	1 \Tstrut & 2 & \hyperlink{LogisticSelectivity}{Logistic selectivity}. \\
	2 \Tstrut & 6 & \hyperlink{Pattern2}{Older version} of selectivity pattern 24 (double normal with peak and tail controls) for backward compatibility in treatment of sex-specific scaling. \\
	5 \Tstrut & 2 & \hyperlink{MirrorSelectivity}{Mirror selectivity}. The two parameters select bin range. \\
	6 \Tstrut & 2 + N breaks & \hyperlink{NonParamSelectivity6}{Older non-parametric size selectivity} (see also Patterns 21 and 43). \\
	8 \Tstrut & 8 & \hyperlink{DoubleLogSelectivity}{Double logistic selectivity}, with defined peak, uses smooth joiners; special = 1 causes constant selectivity above $L_{inf}$ for morph 1. Recommend using pattern 24 instead. \\
	9 \Tstrut & 6 & \hyperlink{SimpleDoubleLog}{Simple double logistic selectivity with no defined peak}. \\
	11 \Tstrut & 2 & \hyperlink{SelectivityOneRange}{Selectivity = 1.0 for a specified length-bin range}. \\
	15 \Tstrut & 0 & \hyperlink{MirrorAnotherSelectivity}{Mirror another selectivity} (same for age selectivity). \\
	21 \Tstrut & 2 & \hyperlink{NonParamSelectivity21}{Newer non-parametric size selectivity} (see also Patterns 6 and 43). \\
	22 \Tstrut & 4 & \hyperlink{DoubleNormalPlateau}{Double normal selectivity}; similar to \href{https://casal2.github.io/}{\gls{casal}}. \\
	23 \Tstrut & 6 & \hyperlink{DoubleNormalPeak}{Same as the selectivity pattern 24 (double normal with peak and tail controls) except the final selectivity is now directly interpreted as the terminal selectivity value}. Cannot be used with Pope's $F$ method because maximum selectivity may be greater than 1. \\
	24 \Tstrut & 6 & \hyperlink{DoubleNormalPeak}{Double normal selectivity with defined initial and final selectivity level - Recommended option}. \\
	25 \Tstrut & 3 & \hyperlink{ExponentialLogistic}{Exponential logistic selectivity}. \\
	27 \Tstrut & 3 + 2*N nodes & \hyperlink{cubic-spline}{Cubic spline selectivity with N nodes}. \\
	42 \Tstrut & 5 + 2*N nodes & \hyperlink{CubicSplineScaling}{Selectivity pattern 27 (cubic spline) but with 2 additional scaling parameters}. \\
	43 \Tstrut & 4 + N breaks & \hyperlink{NonParamScaling}{Selectivity pattern 6 (non-parametric) but with 2 additional scaling parameters} (see also Patterns 6 and 21). \Bstrut\\
	\hline
\end{longtable}


\begin{longtable}{p{2cm} p{3cm} p{10cm}}
	\multicolumn{3}{c}{AGE BASED SELECTIVITY} \\
	\endfirsthead

	\hline
	Pattern & N Parameters & Description \Tstrut\Bstrut\\
	\hline
	\endhead

	\hline
	\endfoot
	\endlastfoot
	
	\hline
	Pattern & N Parameters & Description \Tstrut\Bstrut\\
	\hline
	0  \Tstrut & 0 & Selectivity = 1.0 for ages 0+.\\
	10 \Tstrut & 0 & Selectivity = 1.0 for all ages beginning at age 1. If it is desired that age-0 fish be selected, then use \hyperlink{DoubleLogSelectivity}{selectivity pattern 11} and set minimum age to 0.0. \\
	11 \Tstrut & 2 & \hyperlink{SelectivityOneRange}{Selectivity = 1.0 for a specified age range}. \\
	12 \Tstrut & 2 & \hyperlink{LogisticSelectivity}{Logistic selectivity}. \\
	13 \Tstrut & 8 & Double logistic selectivity, IF joiners. Use discouraged. Use \hyperlink{DoubleLogSelectivity}{selectivity pattern 18 (double logistic selectivity)} instead. \\
	14 \Tstrut & N ages + 1 & \hyperlink{ReviseAge}{Separate parameter for each age (empirical)}, value at age is $\frac{1}{1+exp(-x)}$. \\
	15 \Tstrut & 0 & \hyperlink{MirrorAnotherSelectivity}{Mirror another age-specific selectivity pattern}. \\
	16 \Tstrut & 2 & \hyperlink{GaussianSelectivity}{Coleraine single Gaussian Selectivity}. \\
	17 \Tstrut & N ages + 1 or special + 1 & \hyperlink{RandomWalk}{Empirical as a random walk from previous age}. \\
	18 \Tstrut & 8 & \hyperlink{DoubleLogSelectivity}{Double logistic selectivity}, with defined peak, uses smooth joiners. \\
	19 \Tstrut & 6 & \hyperlink{SimpleDoubleLog}{Simple double logistic selectivity with no defined peak}. \\
	20 \Tstrut & 6 & \hyperlink{DoubleNormalPeak}{Double normal selectivity with defined initial and final level}. Recommended option. \\
	26 \Tstrut & 3 & \hyperlink{ExponentialLogistic}{Exponential logistic selectivity}. \\
	27 \Tstrut & 3 + 2*N nodes & \hyperlink{cubic-spline}{Cubic spline selectivity in age based on N nodes}. \\
	41 \Tstrut & 2 + N ages + 1 & \hyperlink{RandomWalkScaling}{Selectivity pattern 17 (random walk) but with 2 additional scaling parameters}. \\
	42 \Tstrut & 5 + 2*N nodes & \hyperlink{CubicSplineScaling}{Selectivity pattern 27 (cubic spline) but with 2 additional scaling parameters}. \\
	44 \Tstrut & 4 + N ages & \hyperlink{Pattern44}{Selectivity pattern 17 (random walk) but with separate parameters for males and females and with revised controls}. \\
	45 \Tstrut & 4 + N ages & \hyperlink{Pattern45}{Selectivity pattern 14 (revise age) but with separate parameters for males and females and with revised controls}. \Bstrut\\
	\hline
\end{longtable}

\myparagraph{Special Selectivity Options}
Special selectivity options (type 30 in size based selectivity) are no longer specified within the control file. Specifying the use of one of these selectivity types is now done within the data file by selecting the survey ``units'' (see the section on \hyperlink{IndexUnits}{Index units}).

\hypertarget{SelPattern}{}
\subsubsection[Selectivity Pattern Details]{\protect\hyperlink{SelPattern}{Selectivity Pattern Details}}

\hypertarget{LogisticSelectivity}{}
\myparagraph{Pattern 1 (size) and 12 (age) - Simple Logistic}
Logistic selectivity for the primary sex (if selectivity varies by sex) is formulated as:
	\begin{equation}
	S_l = \frac{1.0}{1+exp(-ln(19)(L_l - p1)/p2)}
	\end{equation}
where $L_l$ is the length bin. If age based selectivity is selected then the length bin is replaced by the age vector. If sex specific selectivity is specified the non-primary sex the p1 and p2 parameters are estimated as offsets. Note that with a large p2 parameter, selectivity may not reach 1.0 at the largest size bin. The parameters are:
\begin{itemize}
	\item p1 - size/age at inflection; and
	\item p2 - width for 95\% selection; a negative width causes a descending curve.
\end{itemize}

\hypertarget{Pattern2}{}
\myparagraph{Pattern 2 (size) - Older version of selectivity pattern 24 for backward compatibility}
Pattern 2 differs from pattern 24 only in the treatment of sex-specific offset parameter 5. See note in \hyperlink{MaleSelectivityOffset}{Male Selectivity Estimated as Offsets from Female Selectivity} for more information. Pattern 24 was changed in v.3.30.19 with the old parameterization now provided in Pattern 2.

\hypertarget{MirrorSelectivity}{}
\myparagraph{Pattern 5 (size) - Mirror Selectivity}
Two parameters select the min and max bin number (not min max size) of the source selectivity pattern. If first parameter has value $<=$ 0, then interpreted as a value of 1 (e.g., first bin). If second parameter has value $<=$ 0, then interpreted as maximum length bin (e.g., last bin specified in the data file). The mirrored selectivity pattern must be from a lower fleet number (e.g., already specified before the mirrored fleet).

\hypertarget{NonParamSelectivity6}{}
\myparagraph{Pattern 6 (size) - Older non-parametric Selectivity}
Non-parametric size selectivity uses a set of linear segments. The first break point is at Length = p1 and the last break point is at Length = p2. The total number of break points is specified by the value of the Special factor in the selectivity setup, so the N intervals is one less than the number of break points. Intermediate break points are located at equidistant intervals between p1 and p2. Parameters 3 to N are the selectivity values at the break points, entered as logistic, e.g., $1/(1+exp(-x))$. Ramps from $exp(-10)$ to p3 if L < p1. Constant at Np if L > p2. Note that prior to version 3.03 the break points were specified in terms of bin number, rather than length.

See also \hyperlink{NonParamSelectivity21}{Pattern 21} for a newer non-parametric size selectivity option, and \hyperlink{NonParamScaling}{Pattern 43} which is based on Pattern 6 with additional controls over the scaling.

\hypertarget{DoubleLogSelectivity}{}
\myparagraph{Pattern 8 (size) and 18 (age) - Double Logistic Selectivity}
Users are discouraged from using the double logistic selectivity. The double normal selectivity pattern (size pattern 24, age pattern 20) provides similar functionality but with only 6 parameters.
	\begin{itemize}
		\item p1 - peak: size (age) for peak. Should be an integer and should be at bin boundary and not estimated. But options 7 and 18 may allow estimation.
		\item p2 - initial: selectivity at length bin = 1 (minimum length) or age = 0.
		\item p3 - inflection: a logit transform $(1/(1+exp(-x))$ is used so that the transformed value will be between 0 and 1. So a p1 value of -1.1 will be transformed to 0.25 and used to set the selectivity equal to 0.5 at a size (age) equal to 0.25 of the way between minimum length and peak. 
		\item p4 - slope1: ln(slope) of left side (ascending) selectivity.
		\item p5 - final: logit transform for selectivity at maximum length (or maximum age).
		\item p6 - inflection2: logit transform for size (age) at right side selectivity equal to halfway between peak + peak width and maximum length (or maximum age).
		\item p7 - slope2: ln(slope) of right side (descending) selectivity.
		\item p8 - peak width: width of flattop.
	\end{itemize}

\hypertarget{SelectivityOneRange}{}
\myparagraph{Pattern 11 (size or age) - Selectivity = 1.0 for range}
Length- or age-selectivity can be set equal to 1.0 for a range of lengths or ages. Like other selectivity types, it is specified in terms of the population, not the data bins.

For age-based selectivity, parameters p1 and p2 are set in terms of population age. For example, p1 = 0 and p2 = 4 would mean selectivity of 1.0 for age-0, age-1, age-2, age-3, and age-4 fish. These parameters must be less than or equal to the maximum age, not the maximum age bin. All ages before and after p1 and p2 have selectivity equal to 0.

If the selectivity is length-based, the input parameters should match the population length bin \textbf{number} that will have selectivity = 1.0. A simple example how this works is as follows:

\begin{longtable}{p{4cm} p{0.9cm} p{0.9cm} p{0.9cm} p{0.9cm} p{0.9cm} p{0.9cm} p{0.9cm} p{0.9cm}}
	\hline	
	Population Length Bin \# \Tstrut & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 \\
	Population Length (cm)      & 10 & 12 & 14 & 16 & 18 & 20 & 22 & 24 \Bstrut\\
	\hline
\end{longtable} 

\begin{itemize}
	\item p1 The first length-bin to set selectivity equal to 1.0. Using the above bin structure if p1 = 3 then selectivity = 1.0 mid-bin length of 15 cm.
	\item p2 The final length-bin to set selectivity equal to 1.0. Using the above bin structure if p2 = 7 then selectivity = 1.0 mid-bin length of 23 cm.
	\item All length bins before and after p1 and p2 will be set near zero (1e-010).
\end{itemize}

\hypertarget{ReviseAge}{}
\myparagraph{Pattern 14 (age) - Revise Age}
Age-selectivity pattern 14 to allow selectivity-at-age to be the same as selectivity at the next younger age. When using this option, the range on each parameter should be approximately -5 to 9 to prevent the parameters from drifting into extreme values with nil gradient. The age-based selectivity is calculated as $a = 1$ to $a = Amax + 1$:

\begin{equation}
	S_a = \frac{1}{1+exp(-(p_{a+1} + (9 - max(p_a))))}
\end{equation}	

\hypertarget{RandomWalk}{}
\myparagraph{Pattern 17 (age) - Random Walk}
This selectivity pattern provides for a random walk in ln(selectivity). For each age $a \geq A_{\text{min}}$, where $A_{\text{min}}$ is the minimum age for which selectivity is allowed to be non-zero, there is a selectivity parameter, $p_a$, controlling the changing selectivity from age $a-1$ to age $a$.
	
The selectivity at age $a$ is computed as:

	\begin{equation}
	S_a = \exp (S'_a - S'_{\text{max}}),
	\end{equation}
where

	\begin{equation}
	S'_a = \sum_{i = a_{\text{min}}}^A p_i
	\end{equation}
and
 
	\begin{equation}
	S'_{\text{max}} = \mbox{max} \{S'_a\}.
	\end{equation}

Selectivity is fixed at $S_a = 0$ for $a < A_{\text{min}}$. 
	
This formulation has the properties that the maximum selectivity equals 1, positive values of $p_a$ are associated with increasing selectivity between ages $a-1$ and $a$, and negative values are associated with decreasing selectivity between those ages and $p_a = 0$ gives constant selectivity.
	
The condition that maximum selectivity equals 1 results in one fewer degree of freedom than the number of estimated $p_a$. Therefore, at least one parameter should be fixed at an arbitrary value, typically $p_{A_{\text{min}}}=0$.

The number of parameters lines required to the control file for pattern 17 is N ages + 1, unless a greater than zero value is included in the special column. If special is greater than 0, then special + 1 is the number of parameter lines needed in the control file. The value of special should be less than or equal to N ages. Input to the special column is used to reduce the number of parameters lines required (selectivity is constant above the age represented by the last parameter value read when using special). 
	
In typical usage:
	\begin{itemize}
		\item First parameter (for age 0) could have a value of -1000 so that the age 0 fish would get a selectivity of 0.0;
		\item Second parameter (for age 1) could have a value of 0.0 and not be estimated, so age 1 is the reference age against which subsequent changes occur.
		\item Next parameters get estimated values. To assure that selectivity increases for the younger ages, the parameter min for these parameters could be set to 0.0 or a slightly negative value.
		\item If dome-shaped selectivity is expected, then the parameters for older ages could have a range with the max set to 0.0, so they cannot increase further.
		\item To keep selectivity at a particular age the same as selectivity at the next younger age, set its parameter value to 0.0 and not estimated. This allows for all older ages to have the same selectivity.
		\item To keep a constant rate of change in selectivity across a range of ages, use the -999 flag to keep the same rate of change in ln(selectivity) as for the previous age.
	\end{itemize}

Code for implementing random walk selectivity can be found in \href{https://github.com/nmfs-ost/ss3-source-code/blob/main/SS_selex.tpl}{\texttt{SS\_selex.tpl}}, search for ``SS\_Label\_Info\_22.7.17''.

\hypertarget{DoubleNormalPlateau}{}
\myparagraph{Pattern 22 (size) - Double Normal Selectivity with Plateau}
	\begin{itemize}
		\item p1 - peak1: beginning size for the plateau (in cm).
		\item p2 - peak2: ending size for the plateau. Calculated as a fraction of the distance between peak1 and 99\% of the lower edge of the last size bin in the model. Transformed as $1/(1+exp(-p2))$. So a value of 0 results in peak2 being halfway between peak1 and 99\% of the last bin.
		\item p3 - upslope: ln(variance) on ascending side.
		\item p4 - downslope: ln(variance) on descending side.
	\end{itemize}

\hypertarget{DoubleNormalPeak}{}
\myparagraph{Pattern 23 (size), 24 (size), 2 (legacy), and 20 (age) - Double Normal Selectivity with Defined Peak and Tail Controls}	
	\begin{itemize}
		\item p1 - peak: beginning size (or age) for the plateau (in cm or year).
		\item p2 - top: width of plateau, as logistic between peak and maximum length (or age). See section on \hyperlink{PriorDescrip}{Parameter Priors} regarding challenges with estimation of this parameter.
		\item p3 - ascending width: parameter value is ln(width).
		\item p4 - descending width: parameter value is ln(width).
		\item p5 - initial: selectivity at start bin, as logistic between 0 and 1, or a code.
		\item p6 - final: selectivity at last bin, as logistic between 0 and 1 (for pattern 24). For pattern 23 age selectivity at last bin, as absolute value, so can be > 1.0. Warning: do not allow this value to go above 1.0 if the F\_method uses Pope's approximation. It can above 1.0 when $F$ is in exponential form. When this parameter is above 1.0, the overall selectivity pattern will have an intermediate plateau at 1.0 (according to peak and top), then will ascend further to the final value.
	\end{itemize}
	
Notes for Double Normal with Defined Peak and Tail Controls:
	\begin{itemize}
		\item Selectivity calculations are made based on the mid-length of a population size bin. The start bin is set to the larger value in bin 1 or the first population length bin that overlaps with the data length bin.
		\item For the initial selectivity parameter
		\begin{itemize}
			\item p5 > -999: use p5 with p1 and p3 to do logistic calculations,
			\item p5 = -999 or -1000: do not use p5 and extend the logistic decay of small fish selectivity down to the start bin,
			\item p5 < -1000: ignore the initial selectivity algorithm as above and set selectivity equal to 1.0e-06 for size bins 1 through bin = -1001 - value. So a value of -1003 would set selectivity to a nil level for bins 1 through 2 and begin using the modeled selectivity in bin 3.
		\end{itemize}
		\item For the final selectivity parameter
		\begin{itemize}
			\item p6 = -999 or -1000: ignore the final selectivity algorithm and simply decay the large fish selectivity according to parameter 4,
			\item p6 < -1000: set selectivity constant for bins greater than bin number $=$ -1000 - value.
		\end{itemize}
		\item If start\_bin < 1 and p5 $\geq$ -1000, then selectivity for lengths less than start\_bin are decayed according to the square of their mid-length.
	\end{itemize}

\hypertarget{MirrorAnotherSelectivity}{}
\myparagraph{Pattern 15 (size or age) - Mirror Another Selectivity}
No parameters. Whole age range is mirrored from another fleet. The mirrored selectivity pattern must be from a lower fleet number (e.g., already specified before the mirrored fleet).

\hypertarget{GaussianSelectivity}{}
\myparagraph{Pattern 16 (age) - Gaussian Selectivity(similar to Coleraine)}
	\begin{itemize}
		\item p1 - age below which selectivity declines
		\item p2 - scaling factor for decline
	\end{itemize}

\hypertarget{SimpleDoubleLog}{}
\myparagraph{Pattern 9 (size) and 19 (age) - Simple Double Logistic Selectivity}

This pattern has 4 parameters and 2 fixed input values.

The shape of the selectivity is provided by the function (here in terms of age $a$, but similarly applicable to length bin $l$)

\begin{equation}
    S'_a =  
    \begin{cases}
      \hfil 0 & \text{if $a < p_5$,} \\
      \left( \frac{1}{\exp\left(-p_2 \left( a - p_1 \right) \right) } \right)
      \left(1 - \frac{1}{\exp\left(-p_4 \left( a - [p_6 p_1 - p_3]\right) \right) } \right)
      & \text{if $a \geq p_5$.}
    \end{cases}
 \end{equation}

which is then rescaled by first adding a small constant to all values and then rescaling to have a maximum of 1.0:
 
 \begin{equation}
    S_a = (S'_a + 0.000001) / \max_{a'}\{S'_a + 0.000001\}
 \end{equation}

where
	\begin{itemize}
		\item p1 - ascending inflection age/size (in cm).
		\item p2 - ascending slope. 
		\item p3 - descending inflection age/size (in cm).
		\item p4 - descending slope.
		\item p5 - age or size at first selection; this is a specification parameter, so must not be estimated. Enter integer that is age for pattern 19 and is bin number for pattern 9.
		\item p6 - (0/1) where a value of 0 causes the descending inflection to be a standalone parameter, and a value of 1 causes the descending inflection to be interpreted as an offset from the ascending inflection. This is a specification parameter, so must not be estimated.
	\end{itemize}

\hypertarget{NonParamSelectivity21}{}
\myparagraph{Pattern 21 (size) - Newer non-parametric selectivity}
Non-parametric size selectivity which uses a set of linear segments like Pattern 6, but you have full control over the break points (as opposed to equidistant points over a specified range) and the parameters represent the absolute selectivity without the logistic transformation used in Pattern 6. This allows direct input of an empirical selectivity vector as fixed parameters if desired. The Special column in the selectivity setup specifies the number of break points where the required number of parameter lines is twice this value, with the first set of N parameters providing the length at each break point (which should be fixed via a negative phase) and the second set of N provides the absolute selectivity at each point. 

All of the selectivity parameters must to be non-negative, having a lower bound at 0 (or higher). There is no rescaling to ensure a maximum of 1.0. Therefore it may make sense to have upper bounds at 1.0. Alternatively, a prior centered at 1.0 could be added to the parameter associated with a length bin which is expected to have peak selectivity. If the largest parameter is not fixed at 1.0 or estimated close to 1.0, then care should be taken in interpreting the associated fishing mortality values for the fleet in question.

Selectivity ramps linearly from the origin up to the first selectivity parameter at the first break point and is constant beyond the last break point.

See also \hyperlink{NonParamSelectivity6}{Pattern 6} for an older non-parametric size selectivity option, and \hyperlink{NonParamScaling}{Pattern 43} which is based on Pattern 6 with additional controls over the scaling.

\hypertarget{ExponentialLogistic}{}
\myparagraph{Pattern 25 (size) and 26 (age) - Exponential Logistic Selectivity}
The exponential logistic included is based on the exponential logistic selectivity detailed by \citet{thompson-confounding-1994}; however, the parameterization within SS3 differs. Explorations using this selectivity form has shown that the estimation of p1 can be highly unstable. Users are strongly encouraged to use the double normal selectivity rather than the exponential logistic selectivity.
	\begin{itemize}
		\item p1 - ascending rate, min: 0.02, max: 1.0, reasonable start value: 0.1.
		\item p2 - peak, as fraction of way between min size and max size. Parameter min value: 0.01; max: 0.99; reasonable start value: 0.5.
		\item p3 - descending rate, min: 0.001, max: 0.5, reasonable start value: 0.01. A value of 0.001 provides a nearly asymptotic curve. Values above 0.2 provide strongly dome-shaped function in which the p3 and p1 parameters interact strongly.
	\end{itemize}

The exponential logistic selectivity is calculated as:
	\begin{equation}
	peak = \text{min}(L_l) + p2(\text{max}(L_l) - \text{min}(L_l) )
	\end{equation}
where $L_l$ is the length bins at bin $l$ (if age-based substitute with age bins) and:
	\begin{equation}
	S_l = \frac{e^{p3*p1(peak-L_l)}}{1-p3(1-e^{p1(peak- L_l)})}
	\end{equation}

\hypertarget{cubic-spline}{}
\myparagraph{Pattern 27 (size or age) - Cubic Spline Selectivity}
This selectivity pattern uses the \gls{admb} implementation of the cubic spline
function. This function requires input of the number of nodes, the positions
of those nodes, the parameter values at those nodes, and the slope of the
function at the first and last node.

An alternative to specifying or estimating the slope at the first and last
nodes is to fix those values at 1e30 which will cause create a \texttt{natural.cubic spline} 
which allows the slope (first derivative) to be flexible but
sets the curvature (second derivative) to be 0 at the first and last nodes.

The number of nodes is specified in the ``special'' column of the selectivity
setup. The pattern number 27 is used to invoke cubic spline for size
selectivity and for age selectivity; the input syntax is identical.
	
For a 3 node setup, the input parameters would be:
	\begin{itemize}
		\item p1 - Code for initial setup which controls whether auto-generation is applied (input options are 0, 1, 2, 10, 11, or 12) as explained below
		\item p2 - Gradient at the first node (should be a small positive value, or fixed at 1e30 to implement a ``natural cubic spline'')
		\item p3 - Gradient at the last node (should be zero, a small negative value, or fixed at 1e30 to implement a ``natural cubic spline'')
		\item p4-p6 - The nodes in units of cm; must be in rank order and inside the range of the population length bins. These must be held constant (not estimated, e.g., negative phase value) during a model run.
		\item p7-p9 - The values at the nodes. Units are ln(selectivity) before rescaling.
	\end{itemize}

Notes:
	\begin{itemize}
		\item There must be at least 3 nodes.
		\item One of the node selectivity parameter values should be held constant so others are estimated relative to it.
		\item Selectivity is forced to be constant for sizes greater than the size at the last node.
		\item The overall selectivity curve is scaled to have a peak equal to 1.0.
		\item Last node cannot be at the max population length bin.
	\end{itemize}
	
Code for implementing cubic spline selectivity can be found in
\href{https://github.com/nmfs-ost/ss3-source-code/blob/main/SS_selex.tpl}{\texttt{SS\_selex.tpl}},
search for ``SS\_Label\_Info\_22.7.27''.

One potential problem that may occur with a cubic spline is a U-shaped pattern in the selectivity around the first node. If this occurs, the initial setup code (auto-generation options described below) can be changed from 0, 1 or 2 to 10, 11, or 12 which will cause selectivity to be fixed at 0.0 for all bins below the first node. A natural cubic spline (noted above) may be an alternative solution to this issue.

Auto-Generation of Cubic Spline Control File Setup: A new feature pioneered with the cubic spline function is a capability to produce more specific parameter labels and to auto-generate selectivity parameter setup. The auto-generation feature is controlled by the first selectivity parameter value for each fleet that is specified to use the cubic spline. There are 6 possible values for this setup parameter:
	\begin{itemize}
		\item 0: no auto-generation, process parameter setup as read.
		\item 1: auto-generate the node locations based on the specified number of nodes and on the cumulative size distribution of the data for this fleet/survey.
		\item 2: auto-generate the nodes and also the min, max, prior, initial, and phase for each parameter. 
		\item 10: no auto-generation as in 0 above and fix selectivity = 0.0 below the first knot
		\item 11: auto-generate the node locations as in 1 above and also fix selectivity = 0.0 below the first knot
		\item 12: auto-generate the nodes and other inputs as in 2 above and also fix selectivity = 0.0 below the first knot 
	\end{itemize}
	
With either the auto-generate option 1, 2, 11, or 12, it still is necessary to include in the parameter file placeholder rows of values so that the init\_matrix command can input the current number of values because all selectivity parameter lines are read as a single matrix with the dimension of N parameters $\times$ 14 columns. The read values of min, max, initial, prior, prior type, prior standard deviation, and phase will be overwritten.
	
Cumulative size and age distribution is calculated for each fleet, summing across all samples and both sexes. These distributions are output in \texttt{echoinput.sso} and in a new OVERALL\_COMPS section of \texttt{report.sso}.
	
When the nodes are auto-generated, the first node is placed at the size corresponding to the 2.5\% percentile of the cumulative size distribution, the last is placed at the 97.5\% percentile of the size distribution, and the remainder are placed at equally spaced percentiles along the cumulative size distribution. These calculated node values are output into \texttt{control.ss\_new}. So, the user could extract these nodes from \texttt{control.ss\_new}, edit them to desired values, then, insert them into the input control file. Remember to turn off auto-generation in the revised control file.
	
When the complete auto-generation is selected, the \texttt{control.ss\_new} would look like the table below:	

\begin{longtable}{p{1cm} p{1cm} p{1cm} p{2.9cm} p{1.9cm} p{4.2cm}}
	\hline
	LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
	\hline
	\endfirsthead

	\hline
	LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
	\hline
	\endhead

	0 \Tstrut &		2 &   2.0 & \multicolumn{1}{c}{...} & 0 & \#SizeSpline Code \\
	-0.001    &		1 &  0.13 & \multicolumn{1}{c}{...} & 0 & \#SizeSpline GradLo \\
	-1        & 0.001 & -0.03 & \multicolumn{1}{c}{...} & 0 & \#SizeSpline GradHi \\
	11        &	   95 & 	38 & \multicolumn{1}{c}{...} & 0 & \#SizeSpline Knot1 \\
	11        &	   95 & 	59 & \multicolumn{1}{c}{...} & 0 & \#SizeSpline Knot2 \\
	11        &	   95 & 	74 & \multicolumn{1}{c}{...} & 0 & \#SizeSpline Knot3 \\
	-9        & 	7 & 	-3 & \multicolumn{1}{c}{...} & 0 & \#SizeSpline Value1 \\
	-9        &		7 & 	-1 & \multicolumn{1}{c}{...} & 0 & \#SizeSpline Value2 \\
	-9        &		7 & -0.78 & \multicolumn{1}{c}{...} & 0 & \#SizeSpline Value3 \Bstrut\\
	\hline
\end{longtable}

\hypertarget{RandomWalkScaling}{}
\myparagraph{Pattern 41 (age) - Random Walk Selectivity with User-Defined Scaling}
Selectivity pattern 17 with two additional parameters. The two additional parameters are the bin numbers to define the range of bins for scaling. All the selectivity values will be scaled (divided) by the mean value over this range. The low and high bin numbers are defined before the other selectivity parameters.

	\begin{longtable}{p{1cm} p{1cm} p{1cm} p{2.9cm} p{1.9cm} p{4.2cm}}
		\hline
		LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
		\hline
		\endfirsthead
	
		\hline
		LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
		\hline
		\endhead

		0 & 20 & 10 & \multicolumn{1}{c}{...} & 0 & \#AgeSel\_ScaleAgeLo \Tstrut\\
		0 & 20 & 20 & \multicolumn{1}{c}{...} & 0 & \#AgeSel\_ScaleAgeHi \Bstrut\\
		\hline
	\end{longtable}

\hypertarget{CubicSplineScaling}{}
\myparagraph{Pattern 42 (size or age) - Cubic Spline Selectivity with User-Defined Scaling}
Selectivity pattern 27 with two additional parameters. The two additional parameters are the bin numbers to define the range of bins for scaling. All the selectivity values will be scaled (divided) by the mean value over this range. The low and high bin numbers are defined before the other selectivity parameters.

	\begin{longtable}{p{1cm} p{1cm} p{1cm} p{2.9cm} p{1.9cm} p{4.2cm}}
		\hline
		LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
		\hline
		\endfirsthead
	
		\hline
		LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
		\hline
		\endhead

		0 & 20 & 10 & \multicolumn{1}{c}{...} & 0 & \#AgeSpline\_ScaleAgeLo \Tstrut\\
		0 & 20 & 20 & \multicolumn{1}{c}{...} & 0 & \#AgeSpline\_ScaleAgeHi \Bstrut\\
		\hline
	\end{longtable}

\hypertarget{NonParamScaling}{}
\myparagraph{Pattern 43 (size) - Non-parametric Selectivity with User-Defined Scaling}
Selectivity pattern 6 with two additional parameters. The two additional parameters are the bin numbers to define the range of bins for scaling. All the selectivity values will be scaled (divided) by the mean value over this range. The low and high bin numbers are defined before the other selectivity parameters.
	
	\begin{longtable}{p{1cm} p{1cm} p{1cm} p{2.9cm} p{1.9cm} p{4.2cm}}
		\hline
		LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
		\hline
		\endfirsthead
	
		\hline
		LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
		\hline
		\endhead

		1 & 80 & 50 & \multicolumn{1}{c}{...} & 0 & \#SizeSel\_ScaleBinLo \Tstrut\\
		1 & 80 & 70 & \multicolumn{1}{c}{...} & 0 & \#SizeSel\_ScaleBinHi \Bstrut\\
		\hline
	\end{longtable}

See also \hyperlink{NonParamSelectivity21}{Pattern 21} for a newer non-parametric size selectivity option.

\hypertarget{Pattern44}{}
\myparagraph{Pattern 44 (age) - Random Walk Selectivity with Separate Parameters for Males and Females}
Similar to pattern 17 (random walk) but with separate parameters for males and females. This selectivity pattern provides for a random walk in ln(selectivity). In typical usage:
	\begin{itemize}
		\item p1 - First parameter (for age 0) could have a value of -1000 so that the age 0 fish would get a selectivity of 0.0.
		\item p2 - The first age for which mean selectivity = 1.
		\item p3 - The last age for which mean selectivity = 1.
		\item p4 - Male mean selectivity relative to the female selectivity mean entered as ln(ratio) for the male relative female selectivity.
		\item p5 - p\textsubscript{n} - Additional parameter lines for the natural log of the selectivity change between ages corresponding to the user specified number of changes in the ``special'' column for the selectivity specification for each sex with females entered first then males.
		\item -999 input indicates to the model to keep the change unchanged from the previous age (keeps same rate of change).
		\item -1000 input indicates used only for male selectivity indicates to the model to set the change in male selectivity equal to the female change in selectivity.
	\end{itemize}
	
An example specification and setup for this selectivity option where selectivity is dome-shaped, peaking at age 2 with female and male selectivity are equal with 4 change points per sex:
	\begin{center}
		\begin{longtable}{p{1.5cm} p{1.5cm} p{1.5cm} p{1.5cm}}
			\hline
			\#Pattern & Discard & Male & Special \Tstrut\Bstrut\\
			\hline
			44 & 0 & 0 & 4 \Tstrut\Bstrut\\
			\hline
		\end{longtable}
	\end{center}

	\begin{longtable}{p{1cm} p{1cm} p{1cm} p{2.9cm} p{1.8cm} p{5.1cm}}
		\hline
		LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
		\hline
		\endfirsthead
	
		\hline
		LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
		\hline
		\endhead

		0     & 20 &  0     & \multicolumn{1}{c}{...} & 0 & \#first selex age \Tstrut\\
		0     & 20 &  2     & \multicolumn{1}{c}{...} & 0 & \#first age peak selex (mean) \\
		0     & 20 &  2     & \multicolumn{1}{c}{...} & 0 & \#last age peak selex (mean) \\
		-1    & 2  & -0.001 & \multicolumn{1}{c}{...} & 0 & \#male ln(ratio) \\
		-10   & 10 &  3.01  & \multicolumn{1}{c}{...} & 0 & \#female ln(selex) change 1 \\
		-10   & 10 &  1.56  & \multicolumn{1}{c}{...} & 0 & \#female ln(selex) change 2 \\
		-10   & 10 & -0.15  & \multicolumn{1}{c}{...} & 0 & \#female ln(selex) change 3 \\
		-10   & 10 & -0.15  & \multicolumn{1}{c}{...} & 0 & \#female ln(selex) change 4 \\
		-1000 & 10 & -1000  & \multicolumn{1}{c}{...} & 0 & \#male ln(selex) change 1 \\
		-1000 & 10 & -1000  & \multicolumn{1}{c}{...} & 0 & \#male ln(selex) change 2 \\
		-1000 & 10 & -1000  & \multicolumn{1}{c}{...} & 0 & \#male ln(selex) change 3 \\
		-1000 & 10 & -1000  & \multicolumn{1}{c}{...} & 0 & \#male ln(selex) change 4 \Bstrut\\
		\hline
	\end{longtable}

\hypertarget{Pattern45}{}
\myparagraph{Pattern 45 (age) - Revise Age Selectivity with Separate Parameters for Males and Females}
Similar to pattern 14 (revise age) but with separate parameters for males and females. Age-selectivity pattern 45 to allow selectivity-at-age to be the same as selectivity at the next younger age.
	\begin{itemize}
		\item p1 - is the first age with non-zero selectivity.
		\item p2 - The first age in mean for peak selectivity
		\item p3 - The last age in mean for peak selectivity
		\item p4 - The male mean selectivity relative to the female mean, entered as ln(ratio) for the male relative female selectivity
		\item -999 input indicates to the model to keep the change unchanged from the previous age (keeps same rate of change).
		\item -1000 input indicates used only for male selectivity indicates to the model to set the change in male selectivity equal to the female change in selectivity.
	\end{itemize}
		
An example specification and setup for this selectivity option where selectivity is asymptotic, with female and male selectivity are equal with 4 change points per sex:
	\begin{center}
		\begin{longtable}{p{1.5cm} p{1.5cm} p{1.5cm} p{1.5cm}}
			\hline
			\#Pattern & Discard & Male & Special \Tstrut\Bstrut\\
			\hline
			45 & 0 & 0 & 3 \Tstrut\Bstrut\\
			\hline
		\end{longtable}
	\end{center}
		

	\begin{longtable}{p{1cm} p{1cm} p{1cm} p{2.9cm} p{1.8cm} p{5.1cm}}
		\hline
		LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
		\hline
		\endfirsthead
		
		\hline
		LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
		\hline
		\endhead

		0     & 20 &  2     &  \multicolumn{1}{c}{...} & 0 & \#first selex age \Tstrut\\
		0     & 20 &  5     &  \multicolumn{1}{c}{...} & 0 & \#first age peak selex (mean) \\
		0     & 20 &  5     &  \multicolumn{1}{c}{...} & 0 & \#last age peak selex (mean) \\
		-1    &  2 & -0.001 &  \multicolumn{1}{c}{...} & 0 & \#male ln(ratio) \\
		-10   & 10 & -8.1   &  \multicolumn{1}{c}{...} & 0 & \#female ln(selex) change 1 \\
		-10   & 10 & -4.1   &  \multicolumn{1}{c}{...} & 0 & \#female ln(selex) change 2 \\
		-10   & 10 & -1.8   &  \multicolumn{1}{c}{...} & 0 & \#female ln(selex) change 3 \\
		-1000 & 10 & -1000  &  \multicolumn{1}{c}{...} & 0 & \#male ln(selex) change 1 \\
		-1000 & 10 & -1000  &  \multicolumn{1}{c}{...} & 0 & \#male ln(selex) change 2 \\
		-1000 & 10 & -1000  &  \multicolumn{1}{c}{...} & 0 & \#male ln(selex) change 3 \Bstrut\\
		\hline
	\end{longtable}

\hypertarget{Retention}{}
\subsubsection[Retention]{\protect\hyperlink{Retention}{Retention}}
Retention is defined as a logistic function of size or age. It does not apply to surveys. Four parameters (for asymptotic retention) or seven parameters (for dome-shaped retention) are used:
\begin{itemize}
	\item Asymptotic (4 parameters):
	\begin{itemize}
		\item p1 - ascending inflection,
		\item p2 - ascending slope,
		\item p3 - maximum retention controlling the height of the asymptote (smaller values result in lower asymptotes), often a time-varying quantity to match the observed amount of discard. As of v.3.30.01, this parameter is now input in logit space ranging between -10 and 10. A fixed value of -999 would assume no retention of fish and a value of 999 would set asymptotic retention equal to 1.0,
		\item p4 - male offset to ascending inflection (arithmetic, not multiplicative),
	\end{itemize}
	\item Dome-shaped (add the following 3 parameters):
	\begin{itemize}
		\item p5 - descending inflection,
		\item p6 - descending slope, and
		\item p7 - male offset to descending inflection (arithmetic, not multiplicative).
	\end{itemize}
\end{itemize}

\begin{equation}
	\text{Retention}_l = \left(\frac{P3'}{1 + e^{\frac{-(L_l-(P1+P4*male))}{P2}}}\right)*\left(1 - \frac{1}{1 + e^{\frac{-(L_l-(P5+P7*male))}{P6}}}\right)
\end{equation}
where $P3' = 1/(1+e^{-P3})$ is the asymptotic retention calculated from the $P3$ parameter which is in logit space.

\hypertarget{DiscardM}{}
\subsubsection[Discard Mortality]{\protect\hyperlink{DiscardM}{Discard Mortality}}
Discard mortality is defined as a logistic function of size such that mortality declines from 1.0 to an asymptotic level as fish get larger. It does not apply to surveys, and it does not affect the calculation of expected values for discard data. It is applied so that the total mortality rate is:
\begin{center}
	dead fish = selectivity * (retain + (1.0-retain)*discard mortality)
\end{center}
If discard mortality is 1.0, all selected fish are dead; if discard mortality is 0.0, only the retained fish are dead.

Four parameters are used:
\begin{itemize}
	\item p1 - descending inflection
	\item p2 - descending slope
	\item p3 - maximum discard mortality
	\item p4 - male offset to descending inflection (arithmetic, not multiplicative)
\end{itemize}

Discard mortality is calculated as:
\begin{equation}
	\text{Discard Mortality}_l = 1 - \frac{1-P3}{1+e^{\frac{-(L_l-(P1+P4*male))}{P2}}}
\end{equation}

\hypertarget{SexSelex}{}
\subsubsection[Sex-Specific Selectivity]{\protect\hyperlink{SexSelex}{Sex-Specific Selectivity}}
There are two approaches to specifying sex specific selectivity. One approach allows male selectivity to be specified as a fraction of female selectivity (or vice versa). This first approach can be used for any selectivity pattern. The other option allows for separate selectivity parameters for each sex plus an additional parameter to define the scaling of one sex's peak selectivity relative to the other sex's peak. This second approach has only been implemented for a few selectivity patterns.

\myparagraph{Male Selectivity as a Fraction of Female Selectivity (or vice versa):}
If the ``domale'' flag is set to 1, then the selectivity parameters define female selectivity and the offset defined below sets male selectivity relative to female selectivity. The two sexes switch roles if the ``domale'' flag is set to 2. Generally it is best to select the option so that the dependent sex has lower selectivity, thus obviating the need to rescale for selectivities that are greater than 1.0. Sex specific selectivity is done the same way for all size and age selectivity options.
\begin{itemize}
	\item p1 - size (age) at which a dogleg occurs (set to an integer at a bin boundary and do not estimate).
	\item p2 - ln(relative selectivity) at minimum length or age = 0. Typically, this will be set to a value of 0.0 (for no offset) and not estimated. It would be a rare circumstance in which the youngest/smallest fish had sex-specific selectivity.
	\item p3 - ln(relative selectivity) at the dogleg.
	\item p4 - ln(relative selectivity) at maximum length or max age.
\end{itemize}

For intermediate ages, the natural log values are linearly interpolated on size (age).

If selectivity for the dependent sex is greater than the selectivity for the first sex (which always peaks at 1.0), then the male-female selectivity matrix is rescaled to have a maximum of 1.0.

\hypertarget{MaleSelectivityOffset}{}
\myparagraph{Male Selectivity Estimated as Offsets from Female Selectivity (or vice versa):}
A new sex selectivity option (3 or 4) has been implemented for size selectivity patterns 1 (logistic) and 23 and 24 (double normal) or age selectivity pattern 20 (double normal age). Rather than calculate male selectivity as an offset from female selectivity, here the male selectivity is calculated by making the male parameters an offset from the female parameters (option 3), or females are offset from males with option 4. The description below applies to option 3. If the size selectivity pattern is 1 (logistic), then read 3 parameters:
\begin{itemize}
	\item male parameter 1 is added to the first selectivity parameter (inflection)
	\item male parameter 2 is added to the second selectivity parameter (width of curve)
	\item male parameter 3 is the asymptotic selectivity
\end{itemize}

If the size selectivity pattern is 2, 20, 23 or 24 (double normal), then:
\begin{itemize}
	\item male parameter 1 is added to the first selectivity parameter (peak)
	\item male parameter 2 is added to the third selectivity parameter (width of ascending side); then exp(this sum) per previous transform
	\item male parameter 3 is added to the fourth selectivity parameter (width of descending side); then exp(sum) per previous transform
	\item male parameter 4 is added to the sixth selectivity parameter (selectivity at final size bin); then 1/(1+exp(-sum)) per previous transform
	\item male parameter 5 in selectivity pattern 24 is the apical selectivity and the descending limb for males (see note below). For selectivity pattern 2, 20, and 23 it applies only to the apical selectivity.
\end{itemize}

Notes:
\begin{itemize}
	\item Male selectivity offsets currently cannot be time-varying because they are offsets from female selectivity, they inherit the time-varying characteristics of the female selectivity.
    \item Prior to v.3.30.19 male parameter 5 in pattern 24 scaled only the apical selectivity. This sometimes resulted in strange shapes when the final selectivity, which was shared between females and males in that parameterization, was higher than the estimated apical selectivity. For backwards compatibility to the pattern 24 parameterization prior to v.3.30.19, use selectivity pattern 2.
\end{itemize}

\hypertarget{Dirichletparameter}{}
\subsubsection[Dirichlet-multinomial Error for Data Weighting]{\protect\hyperlink{Dirichletparameter}{Dirichlet-multinomial Error for Data Weighting}}
If the Dirichlet-multinomial error distribution was selected in the data file for length or age data weighting, add additional parameter line(s) immediately following the age selectivity parameter block. There should be 1 parameter line for each parameter in the data file.

For additional information about the Dirichlet-multinomial please see \citet{thorson-model-based-2017} and the detailed \hyperlink{DataWeight}{Data Weighting} section.

	
\begin{longtable}{p{1cm} p{1cm} p{1cm} p{2.9cm} p{1.8cm} p{6.5cm}}
	\multicolumn{6}{l}{The list of parameters would be something like:} \\
	\hline
	LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
	\hline
	\endfirsthead
	
	\hline
	LO \Tstrut & HI & INIT & <other entries> & Block Fxn & Parameter Label \Bstrut\\
	\hline
	\endhead

	-5 & 10 & 0.5 & \multicolumn{1}{c}{...} & 0 & \#ln(DM theta) Age or Length 1 \Tstrut\\
	-5 & 10 & 0.5 & \multicolumn{1}{c}{...} & 0 & \#ln(DM theta) Age or Length 2 \Bstrut\\
	\hline
\end{longtable}

\hypertarget{Selex-TV}{}
\subsubsection[Selectivity Time-Varying Parameters]{\protect\hyperlink{Selex-TV}{Selectivity Time-Varying Parameters}}
Time-Varying selectivity can be used. Details on how to specify time-varying parameters can be found in the \hyperlink{tvOrder}{Time-Varying Parameter Specification and Setup} section.

\hypertarget{TwoDAR}{}
\subsubsection[Two-Dimensional Auto-Regressive Selectivity (2DAR; Semi-parametric selectivity)]{\protect\hyperlink{TwoDAR}{Two-Dimensional Auto-Regressive Selectivity (2DAR; Semi-parametric selectivity)}}
This features combines a baseline parametric selectivity per existing options with a matrix of auto-correlated deviations by year and age (or length) to achieve semi-parametric selectivity as described in \citet{xu-new-2019}. For brevity, only ages will be referred to here. With 2DAR, these deviations are not in the selectivity parameters themselves. Instead, the deviations are exponentiated then used as year and age-specific multipliers on the chosen baseline selectivity.

There are a range of controls for this feature. The deviations can be applied to either the age selectivity or the length selectivity over a specified range of ages (or lengths) and years. The variance of the devs can be the same for all ages, or can be age-specific up to a specified age, then constant variance for all older ages that are within the 2DAR range. Ages outside the 2DAR range revert to the parametric selectivity. The user can select a range of years for which devs will be created and can specify whether selectivity for years outside this range revert to the parametric selectivity or continue with the semi-parametric from the terminal year with devs; thus devs could be defined for just one year, the first year, then mirrored for all subsequent years. Finally, the controls allow for there to be a user-specified level of auto-correlation along the age dimension separate from a user-specified level of auto-correlation in the year dimension.

The 2DAR option has not yet been explored adequately to provide guidance on best practices. However, a preliminary guidance includes the following. When using this option for age-based selectivity, if there are not too many ages, a good choice for the baseline selectivity might be random walk selectivity (pattern 17) because it provides the most flexibility, allowing the 2DAR deviations to be used only for the annual deviations around this baseline rather than the account for misspecification of the underlying functional form. Otherwise, a simple parametric selectivity form like logistic or exponential logistic would be a reasonable choice. With regard to the variability, never estimate the sigma parameters as estimates will biased toward zero. Setting the sigma near 1.0 is advised as an initial default unless the user explicitly determines superior performance of a different value.

\begin{tabular}{p{2cm} p{14cm}}
	\hline
	Typical Value & Description and Options \Tstrut\Bstrut\\
	\hline
	1 \Tstrut & Two-dimensional auto-regressive selectivity: \\
	  & 0 = Not used, \\
	  & 1 = Use 2DAR. \\
	COND = 1 & Then read a specification line for the first fleet that uses 2DAR, then any short parameter lines invoked by those specifications, then enter another specification for next fleet using 2DAR (if any) and its parameter lines, then finish with a specification line containing negative value for the fleet. \Bstrut\\
	\hline
\end{tabular}

The specification line contains 11 values:
\begin{enumerate}
	\item Fleet: Fleet number to which semi-parametric deviations should be added.
	\item Ymin: First year with deviations.
	\item Ymax: Last year with deviations.
	\item Amin: First integer age (or population length bin index) with deviations.
	\item Amax: Last integer age (or population length bin index) with deviations.
	\item Sigma\_Amax: the last age (or population length bin index) for which a separate sigma should be read. The number of sigma parameter lines to be read will be Sigma\_Amax - Amin + 1. The feature allows for the expected situation in which annual variability in selectivity is higher for younger ages. For simplicity, only a single sigma parameter line needs to be read if Sigma\_Amax equals Amin, or if Sigma\_Amax < 0.
	\item Use Rho (0): Use autocorrelation parameters. The rho feature of 2DAR is not implemented and should not be used (value must be 0).
	\item Len(1) / Age(2): to specify whether the deviations should be applied to length- or age-based selectivity.
	\item Phase: Phase to begin estimation of the deviation parameters.
	\item Before Range: How should selectivity be modeled in the years prior to Ymin? Available options are (0) apply no deviations, (1) use deviations from the first year with deviations (Ymin), and (3) use average across all years with deviations (Ymin to Ymax).
	\item After Range: Similar to Before Range but defines how selectivity should be modeled after Ymax.
\end{enumerate}

Following each fleet-specific specification line are short parameter lines for the standard deviation of the devs (sigma\_selex).

\begin{enumerate}
	\item Short parameter line for sigma\_selex at Amin;
	\item If Sigma\_Amax > Amin, then additional parameter lines for each age up to Sigma\_Amax
\end{enumerate}

\begin{longtable}{p{1cm} p{1cm} p{1cm} p{1.25cm} p{1.25cm} p{1.25cm} p{1.2cm} p{1.2cm} p{1cm} p{1cm} p{1cm}}
	\multicolumn{11}{l}{If multiple fleets are specified for 2DAR, the following lines are repeated for each fleet:} \\
	\hline
	\Tstrut &    &      &      &      & Sigma & Use & Len(1)/ &       & Before & After \\
	Fleet & Ymin & Ymax & Amin & Amax & Amax  & Rho & Age(2)  & Phase & Range  & Range \Bstrut\\
	\hline
	   1    & 1979 & 2015 &  2   &  10  & 1     & 0   & 2       & 5     & 0   & 0 \Tstrut\\
	\hline
	     &    &      &     & PRIOR    & PRIOR &       &     & & & \Tstrut\\
	LO & HI & INIT & PRIOR & \gls{sd} & TYPE  & PHASE & \multicolumn{4}{l}{LABEL} \Bstrut\\
	\hline
	 0 & 4 & 1 & 1 & 0.1 & 6 & -4 & \multicolumn{4}{l}{\#Sigma selex fleet 1, first age} \Tstrut\\
	 0 & 4 & 1 & 1 & 0.1 & 6 & -4 & \multicolumn{4}{l}{\#Sigma selex fleet 1, second age} \Tstrut\\
	 0 & 4 & 1 & 1 & 0.1 & 6 & -4 & \multicolumn{4}{l}{\#Sigma selex fleet 1,... age} \Tstrut\\
	\hline
	\multicolumn{11}{l}{\# Additional fleets (e.g., fleet 2) with 2DAR selectivity} \\
	\Tstrut &    &      &      &      & Sigma & Use & Len(1)/ &       & Before & After \\
	Fleet & Ymin & Ymax & Amin & Amax & Amax  & Rho & Age(2)  & Phase & Range  & Range \Bstrut\\
	\hline
	2    & 1979 & 2015 &  2   &  10  & 1     & 0   & 2       & 5     & 0   & 0 \Tstrut\\
	\hline
	   &    &      &       & PRIOR    & PRIOR &       &     & & & \Tstrut\\
	LO & HI & INIT & PRIOR & \gls{sd} & TYPE  & PHASE & \multicolumn{4}{l}{LABEL} \Bstrut\\
	\hline
	0 & 4 & 1 & 1 & 0.1 & 6 & -4 & \multicolumn{4}{l}{\#Sigma selex fleet 2, first age} \Tstrut\\
	0 & 4 & 1 & 1 & 0.1 & 6 & -4 & \multicolumn{4}{l}{\#Sigma selex fleet 2, second age} \Tstrut\\
	0 & 4 & 1 & 1 & 0.1 & 6 & -4 & \multicolumn{4}{l}{\#Sigma selex fleet 2,... age} \Tstrut\\
	\hline
	\multicolumn{11}{l}{\# Terminator line of 11 in length indicates the end of parameter input lines} \\
	-9999 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 \\
	\hline
\end{longtable}


\hypertarget{tagrecapture}{}
\subsection[Tag Recapture Parameters]{\protect\hyperlink{tagrecapture}{Tag Recapture Parameters}}
Specify if tagging data are being used:


\begin{longtable}{p{1cm} p{1cm} p{1cm} p{1.5cm} p{2.9cm} p{1.25cm} p{4.25cm}}
	\hline
	\multicolumn{3}{l}{Typical Value} & \multicolumn{4}{l}{Description and Options} \Tstrut\Bstrut\\
	\hline
	\multicolumn{3}{l}{1} & \multicolumn{4}{l}{Tagging Data Present:} \Tstrut\\
	\multicolumn{3}{l}{}  & \multicolumn{4}{l}{0 = No tagging data, or if tagging data is present in the data file, a value of 0} \\
	\multicolumn{3}{l}{}  & \multicolumn{4}{l}{here will auto-generate the tag parameter section in the \texttt{control.ss\_new} file.} \\
	\multicolumn{3}{l}{}  & \multicolumn{4}{l}{1 = Read following lines of tagging data.} \Bstrut\\


	\multicolumn{7}{l}{COND = 1 Read the following long parameter lines:} \Tstrut\\
	\hline
	LO \Tstrut & HI & INIT & PRIOR &  <other entries> & Block Fxn & Parameter Label \Bstrut\\
	\hline
	\endfirsthead

	\hline
	LO \Tstrut & HI & INIT & PRIOR & <other entries> & Block Fxn & Parameter Label \Bstrut\\
	\hline
	\endhead

	\hline
	\endfoot
	\endlastfoot

	-10 & 10 & 9 & 9 & \multicolumn{1}{c}{...} & 0 & \#TG loss init 1 \Tstrut\\
	-10 & 10 & 9 & 9 & \multicolumn{1}{c}{...} & 0 & \#TG loss chronic 1 \\
	  1 & 10 & 2 & 2 & \multicolumn{1}{c}{...} & 0 & \#TG loss overdispersion 1 \\
	-10 & 10 & 9 & 9 & \multicolumn{1}{c}{...} & 0 & \#TG report fleet 1 \\
	 -4 &  0 & 0 & 0 & \multicolumn{1}{c}{...} & 0 & \#TG report decay 1 \Bstrut\\
	 \hline
\end{longtable}

If there are multiple tagging groups or multiple fleets reporting tagged fish the additional needed parameter lines should be entered in order for each parameter type (i.e., TG loss init 1, TG loss init 2, TG loss chronic 1, TG loss chronic 2,..., TG report decay 1, TG report decay 2). 

Five parameter types are required for tagging data. Both the tag loss parameters and the reporting rate parameters are input as any real number and a logistic transformation is used to keep the resulting rates between 0 and 1:
\begin{itemize}
	\item Initial tag loss, representing fraction of tags that are shed or associated with tag-induced mortality immediately after tagging (1 parameter per tag group). 
	\item Chronic tag loss, representing annual rate of tag loss (1 parameter per tag group).
	\item Overdispersion parameter for the negative binomial likelihood associated with the total number of tag recaptures per tag group (1 parameter per tag group). This value represents the ratio of the variance to the mean of the distribution. As parameterized in ADMB, the likelihood is only defined for overdispersion parameters > 1, but a value of 1.001 will produce results essentially equal to those associated with a Poisson likelihood in which the variance is equal to the mean. This parameter is not transformed like the other 4 types.
	\item Initial reporting rate (1 parameter per fleet), the reporting rate of tags for a specific fleet.
	\item Reporting rate decay representing annual reduction in reporting rate (1 parameter per fleet).
\end{itemize}

The tagging reporting rate parameter is transformed during estimation to maintain a positive value and is reported according to the transformation:
\begin{equation}
	\text{Tagging Reporting Rate} = \frac{e^{\text{input parameter}}}{1+e^{\text{input parameter}}}
\end{equation}

Currently, tag parameters cannot be time-varying.

A shortcoming was identified in the recapture calculations when using Pope's $F$ Method and multiple seasons in SS3 prior to v.3.30.14. The internal calculations were corrected in v.3.30.14. Now the Z-at-age is applied internally for calculations of fishing pressure on the population when using the Pope calculations.

\myparagraph{Mirroring of Tagging Parameters}
In v.3.30.14, the ability to mirror the tagging parameters from another tag group or fleet was added. With this approach, the user can have just one parameter value for each of the five tagging parameter types and mirror all other parameters. Note that parameter lines are still required for the mirrored parameters and only lower numbered parameters can be mirrored. Mirroring is evoked through the phase input in the tagging parameter section. The options are:
\begin{itemize}
	\item No mirroring among tag groups or fleets: phase > -1000,
	\item Mirror the next lower (i.e., already specified) tag group or fleet: phase = -1000 and set other parameter values the same as next lower Tag Group or fleet,
	\item Mirror a lower (i.e., already specified) tag group of fleet x: phase = -100x and set other parameter values the same as the mirrored tag group or fleet (i.e., if you would like to mirror fleet 1 then the phase should -1001).
\end{itemize}

To avoid having to specify mirrored parameter lines, the tag parameters can be auto-generated. The \texttt{control.ss\_new} file created after running this model will have a full set of tagging parameter lines to use in future model runs.

\hypertarget{GcompVar}{}
\subsection[Variance Adjustment Factors]{\protect\hyperlink{GcompVar}{Variance Adjustment Factors}}
When doing iterative re-weighting of the input variance factors, it is convenient to do this in the control file, rather than the data file. This section creates that capability.

\begin{longtable}{p{3cm} p{3cm} p{2.5cm} p{6.25cm}}

	\multicolumn{4}{l}{Read variance adjustment factors to be applied:} \\
	\hline
	Factor & Fleet & Value & Description \Tstrut\Bstrut\\
	\hline
	1 & 2 & 0.5 & \# Survey \gls{cv} for survey/fleet 2 \Tstrut\\
	4 & 1 & 0.25 & \# Length data for fleet 1 \\
	4 & 2 & 0.75 & \# Length data for fleet 2 \\
	-9999 & 0 & 0 & \# End read \Bstrut\\
	\hline
\end{longtable}


\myparagraph{Additive Survey \gls{cv} - Factor 1}
While this functionality has been retained for backward compatibility with older model versions, this approach is no longer considered the best practice for tuning indices. Tuning indices should be conducted using the ability to estimate additional standard deviation which can be done in the \hyperlink{Qsetup}{Catchability} setup.   

The survey input variance (labeled survey \gls{cv}) is actually the standard deviation of the ln(survey). The variance adjustment is added directly to this standard deviation. Set to 0.0 for no effect. Negative values are OK, but will crash if adjusted standard deviation value becomes negative.

\myparagraph{Additive Discard - Factor 2}	
The input variance is the \gls{cv} of the observation. Because this will cause observations of near zero discard to appear overly precise, the variance adjustment is added to the discard standard deviation, not to the \gls{cv}. Set to 0.0 for no effect.

\myparagraph{Additive Mean Body Weight - Factor 3}	
The input variance is in terms of the \gls{cv} of the observation. Because such data are typically not very noisy, the variance adjustment is added to the \gls{cv} and then multiplied by the observation to get the adjusted standard deviation of the observation.

\myparagraph{Multiplicative Length Composition - Factor 4}
The input variance is in terms of an effective sample size. The variance adjustment is multiplied times this sample size. Set variance adjustment to 1.0 for no effect.

\myparagraph{Multiplicative Age Composition - Factor 5}
Age composition is treated the same way as length composition.
	
\myparagraph{Multiplicative Size-at-Age - Factor 6}	
Size-at-age input variance is the sample size for the N observations at each age. The variance adjustment is multiplied by these N values. Set to 1.0 for no effect.
	
\myparagraph{Multiplicative Generalized Size Composition - Factor 7}	
Generalized size composition input variance is the sample size for each observation. The variance adjustment for each fleet is multiplied by these sample sizes. Set to 1.0 for no effect.
		
\myparagraph{Variance Adjustment Usage Notes}
The \texttt{report.sso} output file contains information in the ``FIT\_LEN\_COMPS'' and ``FIT\_AGE\_COMPS''  useful for determining if an adjustment of these input values is warranted to better match the scale of the average residual to the input variance scale.
	
Because the actual input variance factors are modified, it is these modified variance factors that are used when creating parametric bootstrap data files. So, the control files used to analyze bootstrap generated data files should have the variance adjustment factors reset to null levels.


\hypertarget{Lambdas}{}
\subsection[Lambdas (Emphasis Factors)]{\protect\hyperlink{Lambdas}{Lambdas (Emphasis Factors)}}
These values are multiplied by the corresponding likelihood component to calculate the overall negative log likelihood to be minimized.


\begin{tabular}{p{3cm} p{13cm}}
	\hline
	Typical Value & Description and Options \Tstrut\Bstrut\\
	\hline
	4 \Tstrut & Max lambda phase: read this number of lambda values for each element below. The last lambda value is used for all higher numbered phases. \Bstrut\\
	1 & \gls{sd} offset: \\
	  & 0 = The ln(like) to omit the + ln(s) term, \\
	  & 1 = The ln(like) to include the ln(s) term for \gls{cpue}, discard, growth \gls{cv}, mean body weight, recruitment deviations. If you are estimating any variance parameters, \gls{sd} offset must be set to 1. \Bstrut\\
	\hline
\end{tabular}

\myparagraph{Lambda Usage Notes}
\hypertarget{SaAlambda}{}
If the \gls{cv} for size-at-age is being estimated and the model contains mean size-at-age data, then the flag for inclusion of the + ln(\gls{sd}) term in the likelihood must be included. Otherwise, the model will always get a better fit to the mean size-at-age data by increasing the parameter for \gls{cv} of size-at-age.

The reading of the lambda values has been substantially altered with v.3.30. Instead of reading a matrix containing all the needed lambda values, the model now just reads those elements that will be given a value other than 1.0. After reading the datafile, the model sets lambda equal to 0.0 if there are no data for a particular fleet/data type, and a value of 1.0 if data exist. So beware if your data files had data, but you had set the lambda to 0.0 in a previous version of SS3. First read an integer for the number of changes.

You can put any placeholder value like 0 or 999 for fleet if the likelihood component is not fleet specific (like recdevs).

You can also put any placeholder value like 0 or 999 for the SizeFreq Method unless the likelihood component you are changing the lambda for is 6 = size frequency, in which case you need to have a row for each size frequency method you want to modify and put the associated method number in that fourth column.

\begin{longtable}{p{3cm} p{3cm} p{2cm} p{3cm} p{3cm}}

	\multicolumn{5}{l}{Read the lambda adjustments by fleet and data type:} \\
	\hline
	Likelihood &       &       & Lambda & SizeFreq \Tstrut\\
	Component  & Fleet & Phase & Value  & Method \Bstrut\\
	\hline
	1 & 2 & 2 & 1.5 & 1 \Tstrut\\
	4 & 2 & 2 & 10 & 1 \\
	10 & 0 & 2 & 1 & 0 \\ \#not\_fleet\_specific
	6 & 2 & 2 & 1.5 & 1 \\ \#size\_frequency\_method\_1
	6 & 2 & 2 & 1 & 2 \\ \#size\_frequency\_method\_2
	4 & 2 & 3 & 0.2 & 1 \\
	-9999 & 1 & 1 & 1 & 1 \Bstrut\\
	\hline
\end{longtable}


\begin{center}
	\begin{longtable}{p{7.5cm} p{7.5cm}}
		\multicolumn{2}{l}{The codes for component are:}\\
		\hline
		1 = survey  				   & 10 = recruitment deviations \Tstrut\\	
		2 = discard 				   & 11 = parameter priors \\		
		3 = mean weight 			   & 12 = parameter deviations \\	
		4 = length 					   & 13 = crash penalty \\		
		5 = age 					   & 14 = morph composition \\
		6 = size frequency  		   & 15 = tag composition \\		
		7 = size-at-age 			   & 16 = tag negative binomial \\
		8 = catch 					   & 17 = $F$ ballpark \\		
		9 = initial equilibrium catch (see note below) & 18 = regime shift \Bstrut\\
		\hline
	\end{longtable}
\end{center}

Starting in v.3.30.16, the application of a lambda to initial equilibrium catch is now fleet specific. In previous versions, a single lambda was applied in the same manner across all fleets with an initial equilibrium catch specified.

\hypertarget{ControlsVarDer}{}
\subsection[Controls for Variance of Derived Quantities]{\protect\hyperlink{ControlsVarDer}{Controls for Variance of Derived Quantities}}
Additional standard deviation reported may be selected:

\begin{longtable}{p{1.1cm} p{1.4cm} p{1.2cm} p{1.2cm} p{1.3cm} p{1.6cm} p{1.4cm} p{1.4cm} p{1.4cm}}

	\hline
	\multicolumn{3}{l}{Typical Value} & \multicolumn{6}{l}{Description and Options} \Tstrut\Bstrut\\
	\hline
	\endfirsthead


	\multicolumn{3}{l}{0} & \multicolumn{6}{l}{0 = No additional \gls{sd} reporting;} \Tstrut\\
	\multicolumn{3}{l}{ } & \multicolumn{6}{l}{1 = read specification for reporting \gls{sd} for selectivity, size, numbers; and} \Bstrut\\
	\multicolumn{3}{l}{ } & \multicolumn{6}{l}{2 = read specification for reporting \gls{sd} for selectivity, size, numbers,} \Bstrut\\
	\multicolumn{3}{l}{ } & \multicolumn{6}{l}{natural mortality, dynamic $B_{0}$, and Summary Bio} \Bstrut\\
	\hline

\end{longtable}

COND = 1 or 2: Read the following lines (split into 3 rows for readability):
\begin{itemize}
	\item 4 values related to selectivity:
	\begin{enumerate}
		\item fleet number (or 0 if not used),
		\item type of selectivity to report: 1 = length, 2 = age, or 3 = combined (age with length),
		\item year (enter -1 for end year), and
		\item number of bins to report, list entered below (note - combined will report in age bins).
	\end{enumerate}	
	\item 2 values related to growth:
	\begin{enumerate}
		\item growth pattern (or 0 if not used), and
		\item number of ages for reporting: list entered below (note - each sex will be reported).
	\end{enumerate}	
	\item 3 values related to numbers-at-age:
	\begin{enumerate}
		\item area (enter -1 for sum of all areas), or 0 for not used,
		\item year (enter -1 for end year + 1), and
		\item number of ages to report, list entered below (note - each sex will be reported and summed across growth patterns).
	\end{enumerate}
\end{itemize}

COND = 2, enter the above quantities plus (available in versions 3.30.15 and higher):  
\begin{itemize}
	\item 2 additional values related to natural mortality-at-age:
	\begin{enumerate}
		\item growth pattern (or 0 for not used), and
		\item number of ages for reporting, list entered below (note each sex will be reported).
	\end{enumerate}
	\item 1 additional value related to dynamic $B_{0}$ (needed in versions 3.30.17 and higher):
	\begin{enumerate}
		\item 0 for not used, 1 to report \gls{ssb} for dynamic $B_{0}$, 2 to report \gls{ssb} and recruitment
	\end{enumerate}
	\item 1 additional value related to Summary Bio (needed in versions 3.30.17 and higher):
	   \begin{enumerate}
	     \item 0 for not used, 1 to report
	   \end{enumerate}
	   
\end{itemize}

Depending upon the entered options above subsequent conditional inputs may be need.
\begin{itemize}
	\item COND if selectivity specs number of bins to report > 0:
		\begin{itemize}
			\item Vector of bin indexes or -1 in first bin will overwrite entered vector with auto-generated list to cover logical range
	\end{itemize}
	\item COND if growth specs number of bins to report > 0 and empirical weight-at-age not used:
		\begin{itemize}
			\item \ldots~as for selectivity bins
		\end{itemize}
	\item COND if numbers-at-age specs number of ages > 0:
		\begin{itemize}
			\item \ldots~as for selectivity bins
		\end{itemize}
	\item COND == 2 and mortality-at-age specs number of ages > 0:
		\begin{itemize}
			\item \ldots~as for selectivity bins
		\end{itemize}
\end{itemize}

\begin{longtable}{p{1.1cm} p{1.4cm} p{1.2cm} p{1.2cm} p{1.3cm} p{1.6cm} p{1.4cm} p{1.4cm} p{1.4cm}}
	
	\hline
	\multicolumn{9}{l}{Example Input:} \Tstrut\Bstrut\\
	\hline
	
	\multicolumn{3}{l}{2} & \multicolumn{6}{l}{\# 0 = No additional \gls{sd} reporting;} \Tstrut\\
	\multicolumn{3}{l}{ } & \multicolumn{6}{l}{\# 1 = read values below; and} \Bstrut\\
	\multicolumn{3}{l}{ } & \multicolumn{6}{l}{\# 2 = read specification for reporting \gls{sd} for selectivity, size, numbers,} \Bstrut\\
	\multicolumn{3}{l}{ } & \multicolumn{6}{l}{and natural mortality.} \Bstrut\\
	\hline
	
	\multicolumn{4}{l}{1 1 -1 5}  & \multicolumn{5}{l}{\# Selectivity} \Bstrut\\
	\multicolumn{4}{l}{1 5}       & \multicolumn{5}{l}{\# Growth} \Bstrut\\
	\multicolumn{4}{l}{1 -1 5}    & \multicolumn{5}{l}{\# Numbers-at-age} \Bstrut\\
	\multicolumn{4}{l}{1 5}       & \multicolumn{5}{l}{\# M-at-age} \Bstrut\\
	\multicolumn{4}{l}{1}         & \multicolumn{5}{l}{\# Dynamic Bzero} \Bstrut\\
	\multicolumn{4}{l}{1}         & \multicolumn{5}{l}{\# Summary Biomass} \Bstrut\\
	
	\multicolumn{4}{l}{5 15 25 35 38} & \multicolumn{5}{l}{\# Vector with selectivity std bins (-1 in first bin to self-generate)} \Bstrut\\
	\multicolumn{4}{l}{1 2 5 10 15}  & \multicolumn{5}{l}{\# Vector with growth std ages picks (-1 in first bin to self-generate)} \Bstrut\\
	\multicolumn{4}{l}{1 2 5 10 15}  & \multicolumn{5}{l}{\# Vector with numbers-at-age std ages (-1 in first bin to self-generate)} \Bstrut\\
	\multicolumn{4}{l}{1 2 5 10 15}  & \multicolumn{5}{l}{\# Vector with M-at-age std ages (-1 in first bin to self-generate)} \Bstrut\\
	
	\hline
	\bfseries{999} & \multicolumn{8}{l}{\#End of the control file input} \Tstrut\Bstrut\\
	\hline			
\end{longtable}

\pagebreak