13output.tex

\hypertarget{OutputFiles}{}
\section[Output Files]{\protect\hyperlink{OutputFiles}{Output Files}}

When Stock Synthesis is run, numerous text files are produced in the same folder as the input files. Many of these are automatically created by ADMB and can be ignored. The files in the following table are typically used by SS3 users to see the model results, understand how SS3 is interpreting the inputs, and debug models.

\begin{longtable}{| p{5cm} | p{5cm} | p{5cm} |}
	\hline
	\textbf{Output with Results} & \textbf{Output Mirroring Input} & \textbf{Output for Debugging} \Tstrut\Bstrut\\ 
	\hline
    Report.sso & starter.ss\_new & warning.sso \\
    ss\_summary.sso & control.ss\_new & echoinput.sso \\
    CompReport.sso & data\_echo.ss\_new & ParmTrace.sso \\
    covar.sso & forecast.ss\_new & \\
    Forecast-report.sso & wtatage.ss\_new & \\
    ss3.par & & \\
    \hline
\end{longtable}

\begin{landscape}
    \hypertarget{MainOutput}{}
    \subsection[Main Output File, \texttt{Report.sso}]{\protect\hyperlink{MainOutput}{Main Output File, \texttt{Report.sso}}}
    This is the primary output file. The file starts with KeyWords\_of\_tables\_available\_in\_report\_sso which is a list of tables organized by category indicating which tables are included in the Report file. The full list of tables (as of v.3.30.23) is listed below.

	\begin{longtable}{p{1.5cm} p{5.5cm} >{\RaggedRight\arraybackslash}p{4.25cm} p{9.75cm}}
	\hline
	\multirow{1}{1cm}[-0.25cm]{\parbox{1.5cm}{\textbf{Report Number}}} & \textbf{Report file notation} & \textbf{r4ss notation} & \textbf{Notes} \\
    \textbf{} & \textbf{\textit{Description (if needed)}} & \textbf{} & \textbf{} \Bstrut\\ 
	\hline
	\endfirsthead
		
    \hline
    \multirow{1}{1cm}[-0.25cm]{\parbox{1.5cm}{\textbf{Report Number}}} & \textbf{Report file notation} & \textbf{r4ss notation} & \textbf{Notes} \\
    \textbf{} & \textbf{\textit{Description (if needed)}} & \textbf{} & \textbf{} \Bstrut\\  
	\hline
	\endhead

    1 & DEFINITIONS & Split into variables: \$nseasons, \$seasfracs, \$seasdurations, and \$FleetNames & List of definitions (e.g., fleet names, model start year) assigned in the data and control files. \Bstrut\\
    2 & LIKELIHOOD & \$likelihoods\_used and \$likelihoods\_by\_fleet & Final values of the negative log likelihood are presented. \Bstrut\\
    3 & Input\_Variance\_Adjustment & NA & The matrix of input variance adjustments is output here because these values affect the log likelihood calculations. \Bstrut\\
    4 & Parm\_devs\_detail & \$Parm\_devs\_detail & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{Details about parameter deviations, if used in the model. Will be missing if no parameter deviations were used. Shows controlling parameters \gls{sd} and Rho as well as statistics of time series of deviations. The statistics include the mean, \gls{rmse}, var, est\_rho (estimated autocorrelation), and D-W (Durbin-Watson) statistic.}} \Bstrut\\
      & \textit{Parameter deviations detail} & & \\
      & & & \Bstrut\\
      & & & \Bstrut\\
    5 & PARAMETERS & \$parameters & The parameters are listed here. For the estimated parameters, the display shows: Num (count of parameters), Label (as internally generated by SS3), Value, Active\_Cnt, Phase, Min, Max, Init, Prior, Prior\_type, Prior\_SD, Prior\_Like, Parm\_StD (standard deviation of parameter as calculated from inverse Hessian), Status (e.g., near bound), and Pr\_atMin (value of prior penalty if parameter was near bound). The Active\_Cnt entry is a count of the parameters in the same order they appear in the \texttt{ss.cor} file. Also included are values derived from the prior distribution (Value-1.96*\gls{sd}, Value+1.96*\gls{sd}, V\_1\%, V\_10\%, etc.). \Bstrut\\ 
    6 & DERIVED\_QUANTITIES & \$derived\_quants & This section starts by showing the options selected from the \texttt{starter.ss} and texttt{forecast.ss} input files: 
    \begin{itemize}
        \item \gls{spr} ratio basis, 
        \item $F$ report basis, 
        \item B ratio denominator
    \end{itemize}
    Then the time series of output, with standard deviation of estimates, are produced with internally generated labels. Note that these time series extend through the forecast era. The order of the output is: spawning biomass, recruitment, SPRratio, Fratio, Bratio, management quantities, forecast catch (as a target level), forecast catch as a limit level (\gls{ofl}), Selex\_std, Grow\_std, NatAge\_std. For the three “ratio” quantities, there is an additional column of output showing a Z-score calculation of the probability that the ratio differs from 1.0. The “management quantities” section is designed to meet the terms of reference for west coast groundfish assessments; other formats could be made available upon request. The standard deviation quantities at the end are set up according to specifications at the end of the control input file. In some cases, a user may specify that no derived quantity output of a certain type be produced. In those cases, SS3 substitutes a repeat output of the virgin spawning biomass so that vectors of null length are not created. \Bstrut\\
    7 & MGparm\_By\_Year\_after \_adjustments & \$MGparmAdj & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{This block shows the time series of mortality and growth parameters by year after adjustments by environmental links, blocks and deviations.}} \\
      & \textit{Mortality and growth parameters by year after adjustments} & & \Bstrut\\
    \pagebreak
    8 & selparm(Size)\_By\_Year \_after\_adjustments & \$SelSizeAdj & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{This block shows the size selectivity parameters by year after adjustments by environmental links, blocks, and deviations}} \\
      & \textit{Selectivity parameters (size) by year after adjustments} & & \Bstrut\\
    9 & selparm(Age)\_By\_Year \_after\_adjustments & \$SelAgeAdj & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{This block shows the age selectivity parameters by year after adjustments by environmental links, blocks, and deviations.}} \\
      & \textit{Selectivity parameters (age) by year after adjustments} & & \Bstrut\\
    10 & RECRUITMENT\_DIST & \multirow{1}{1cm}[-0.25cm]{\parbox{4cm}{\$recruitment\_dist (a list containing \$recruit\_dist, \$recruit\_dist\_Bmark, and \$recruit\_dist\_endyr}} & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{This block shows the distribution of recruitment across growth patterns, sexes, settlement events, and areas in the end year of the model.}} \\
       & \textit{Recruitment distribution} & & \\
       & & & \\
       & & & \\
       & & & \Bstrut\\
    11 & MORPH\_INDEXING & \$morph\_indexing & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{This block shows the internal index values for various quantities. It can be a useful reference for complex model setups. Bio\_Pattern refers to a collection of cohorts with the same defined growth and natural mortality parameters; sex is the next main index. If recruitment occurs in multiple events, then settlement event is the index for that factor. The index labeled ``Platoon'' is used as a continuous index across all the other factor-specific indices. If sub-platoons are used, they are nested within the Bio\_Pattern $\times$ Sex $\times$ Birth Season platoon. However, some output tables use the column label ``platoon'' as a continuous index across platoons and sub-platoons. Note that there is no index here for area. Each of the cohorts is distributed across areas and they retain their biological characteristics as they move among areas.}} \\
       & \textit{Growth morph indexing} & & \Bstrut\\
       & & & \Bstrut\\
       & & & \Bstrut\\
       & & & \Bstrut\\
       & & & \Bstrut\\
       & & & \Bstrut\\
       & & & \Bstrut\\
       & & & \Bstrut\\
       & & & \Bstrut\\
       & & & \Bstrut\\
    12 & SIZEFREQ\_TRANSLATION & \multirow{1}{1cm}[-0.25cm]{\parbox{4cm}{NA (only present when using generalized size frequency data)}} & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{If the generalized size frequency approach is used, this block shows the translation probabilities between population length bins and the units of the defined size frequency method. If the method uses body weight as the accumulator, then output is in corresponding units.}} \\
       & \textit{Size frequency translation} & & \\
       & & & \\
       & & & \\
       & & & \Bstrut\\
    13 & MOVEMENT & \$movement & Movement rate between areas in a multi-area model. \Bstrut\\
    14 & EXPLOITATION & \$exploitation & Time series of the selected $F\text{\_std}$ unit and the $F$ for each fleet in terms of harvest rate (if Pope's approximation is used) or fully selected $F$. Also included are $\text{annual\_}F$ and $\text{annual\_}M$ from $Z = ln(N_{t+1}/N_{t})$ and $F = Z-M$. \Bstrut\\
    15 & CATCH & \$catch & Observed and expected catch and $F$. Also vuln\_bio, sel\_bio, dead\_bio, ret\_bio, vuln\_num, sel\_num, dead\_num, and ret\_num by fleet, area, year, and season \Bstrut\\
    16 & TIME\_SERIES & \$timeseries & Biomass and recruitment by area, year, and season. Also has the same (e.g. redundant) detailed catch output as in the CATCH table. \Bstrut\\
    17 & SPR\_SERIES & \$sprseries & Table shows per recruit quantities (e.g. equilibrium) using the current year's biology-at-age and fishery characteristics and levels. \Bstrut\\
    18 & Kobe\_plot & \$Kobe (also \$Kobe\_warn and \$Kobe\_MSY\_basis) & Reports $B/B_{MSY}$ and $F/F_{MSY}$ needed to create a Kobe Plot. \Bstrut\\
    19 & SPAWN\_RECRUIT & \$recruit & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{Extensive information on Spawn-recruit setup, summary statistics, and time series. The summary statistics include the est\_rho (estimated autocorrelation) and the D-W (Durbin-Watson) statistic.}} \\
       & \textit{Spawn recruit parameters and table} & & \Bstrut\\
    20 & SPAWN\_RECR\_CURVE & \$SPAWN\_RECR\_CURVE & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{A table containing values for plotting the spawn-recruit curve.}} \\ 
       & \textit{Spawn recruit curve} & & \Bstrut\\
    21 & INDEX\_1 & \$index\_variance\_tuning \_check & Table shows summary statistics for the fit to each survey or index, including the \gls{rmse} of the fit to each index compared to the mean input error level to assist the user in gauging the goodness-of-fit and potentially adjusting the input level of imprecision. \Bstrut\\
    22 & INDEX\_2 & \$cpue & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{This section reports the observed and expected values for each survey, \gls{cpue}, or other index. All are reported in one list with index number included as a selection field. }} \\
       & \textit{Survey+} & & \\
       & & & \Bstrut\\
    23 & INDEX\_3 & NA & Parameter number for each catchability parameter. The first column is the base parameter, the second is the extra \gls{sd} parameter, the third is environmental link, and the fourth is the block or trend parameter. \Bstrut\\
    24 & DISCARD\_SPECIFICATION & \$discard\_spec & Information on discard units and error type for each fleet with discards. \Bstrut\\
    25 & DISCARD\_OUTPUT & \$discard & This is the list of observed and expected values for the amount (or fraction) discard. \Bstrut\\
    26 & MEAN\_BODY\_WT\_OUTPUT & \$mean\_body\_wt & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{This is the list of observed and expected values for the mean body weight (of all selected sizes of fish).}} \\
       & \textit{Mean body weight} & & \Bstrut\\
    27 & FIT\_LEN\_COMPS & \multirow{1}{1cm}[-0.25cm]{\parbox{4cm}{\$len\_comp\_fit\_table and \$Len\_Comp\_Fit\_Summary}} & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{List of the goodness-of-fit to each length composition observation. The input and output levels of effective sample size are shown as a guide to adjusting the input levels to better match the model’s ability to replicate these observations. Also shown are the observed and expected mean length for females, males, and combined. Below the list are summary statistics for each fleet.}} \\
       & \textit{Fit length compositions} & & \\
       & & & \\
       & & & \\
       & & & \Bstrut\\
       & & & \Bstrut\\
    28 & FIT\_AGE\_COMPS & \multirow{1}{1cm}[-0.25cm]{\parbox{4cm}{\$age\_comp\_fit\_table and \$Age\_Comp\_Fit\_Summary}} & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{This age composition information has the same format as the length composition section.}} \\
       & \textit{Fit age compositions} & & \\
    29 & FIT\_SIZE\_COMPS & \multirow{1}{1cm}[-0.25cm]{\parbox{4cm}{\$size\_comp\_fit\_table and \$Size\_Comp\_Fit\_Summary}} & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{This generalized size composition section has the same format as the length composition section.}} \\
       & \textit{Fit size compositions} & & \\
	   & & & \Bstrut\\
    30 & OVERALL\_COMPS & NA & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{This is the unweighted average of composition data across all the samples for a given fleet. Cumulative vector is used for auto-placing knots of cubic spline selectivity.}} \\
       & \textit{Overall compositions} & & \\
       & & & \Bstrut\\
    31 & LEN\_SELEX & \multirow{1}{1cm}[-0.25cm]{\parbox{4cm}{\$sizeselex}} & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{Length selectivity and other length specific quantities for each fishery and survey.}} \\
       & \textit{Length Selectivity} & & \Bstrut\\
    32 & AGE\_SELEX & \$ageselex & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{Time series of age selectivity and other age-related quantities for each fishery and survey. Some are directly computed in terms of age, and others are derived from the combination of a length-based factor and the distribution of size-at-age. Includes F-at-age for fishing fleets and body weight-at-age.}} \\
       & \textit{Age Selectivity} & & \\
       & & & \\
       & & & \\
       & & & \\
       & & & \Bstrut\\
    33 & ENVIRONMENTAL\_DATA & NA & The input values of environmental data are echoed here. Density-dependence can be used by linking to population quantities that have already been calculated at the start of the year. These include summary biomass, spawning biomass, and recruitment deviations. These three quantities are mapped into the -1, -2, and -3 columns of the environmental data matrix where they can be used as if there were environmental data input. \Bstrut\\
    34 & TAG\_Recapture & \multirow{1}{1cm}[-0.25cm]{\parbox{4cm}{\$tagrelease, \#tagsalive, \$tagtotrecap, \$tagfirstperiod, \$tagaccumperiod, and \$tagreportrates}} & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{Multiple tables of information on tagged fish (if included in the model) including details on each tag group, tags alive by release group and period, total recaptures by release group and period, and reporting rates by fishery.}} \\
       & \textit{Tag recapture information} & & \\
	   & & & \Bstrut\\
    35 & NUMBERS\_AT\_AGE & \$natage & The abundance at age (in thousands of fish) for each area, year, and season is shown for each cohort (labelled Morph) tracked in the model. Biological identity of each Morph is in other columns. $B$ is beginning of the season and $M$ is the midpoint of the season. \Bstrut\\
    36 & BIOMASS\_AT\_AGE & \$batage & The abundance at age (in metric tons) for each area, year, and season. Formatted the same way as the numbers-at-age table. \Bstrut\\
    37 & NUMBERS\_AT\_LENGTH & \$natlen & The output is shown for each cohort tracked in the model. \Bstrut\\
    38 & BIOMASS\_AT\_LENGTH & \$batlen & The output is shown for each cohort tracked in the model. \Bstrut\\
    39 & F\_AT\_AGE & \$fatage & Dedicated table for the time series of F-at-age for each fleet. Redundant with the F-at-age shown in the Age\_selex table. \Bstrut\\
    40 & CATCH\_AT\_AGE & \$catage & The output is shown for each fleet. It is not necessary to show by area because each fleet operates in only one area. \Bstrut\\
    41 & DISCARD\_AT\_AGE & \$discard\_at\_age & Similar to the catch-at-age report. \Bstrut\\
    42 & BIOLOGY & \$biology & The first biology section shows the length-specific quantities in the ending year of the time series only. The derived quantity spawn is the product of female body weight, maturity and fecundity per weight. \Bstrut\\
    43 & Natural\_Mortality & \$Natural\_Mortality & Time series of natural mortality by area, year, and season. Includes $M2$ in models with predators. \Bstrut\\
    44 & AGE\_SPECIFIC\_K & NA & Values for age-specific von Bertalanffy $k$ values for each Bio\_Pattern and sex (if implemented in the model via growth options 3--5.)\Bstrut\\
    45 & Growth\_Parameters & \$Growth\_Parameters & This section shows the growth parameters and associated derived quantities for each year in which a change is estimated. This information overlaps with that in the MGPARM\_by\_year report. \Bstrut\\
    46 & Seas\_Effects & \$Seas\_Effects & Table with seasonal effects on biology. \\
       & \textit{Seasonal effects} & & \Bstrut\\
    47 & Biology\_at\_age\_in\_endyr & \$endgrowth & This section shows derived size-at-age and other quantities. As of v.3.30.21 sex ratio is reported by area in this output table. \Bstrut\\
    48 & MEAN\_BODY\_WT(Begin) & \$mean\_body\_wt & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{This section reports the time series of mean body weight for each morph. Values shown are for the beginning of each season of each year. Not included are the morph descriptors as found in report 35.}} \\
       & \textit{Mean body weight (start)} & & \\
       & & & \\
       & & & \Bstrut\\
    49 & MEAN\_SIZE\_TIMESERIES & \$growthseries & This section shows the time series of mean length-at-age for each morph. At the bottom is the average mean size as the weighted average across all morphs for each sex. \Bstrut\\
    50 & AGE\_LENGTH\_KEY & \$ALK & This is reported for values in endyear. Table values for each sub-season (Subseas) of each season. Subseas = 1 is the beginning of the season and subseas = 2 is the midpoint of the season. There are only 2 sub-seasons. \Bstrut\\
    51 & AGE\_AGE\_KEY & \$AAK & This is the calculated distribution of observed ages for each true age for each of the defined ageing keys. \Bstrut\\
    52 & COMPOSITION\_DATABASE & Separate variables by data type: \$lendbase, \$sizedbase, \$agebase, \$condbase, \$ghostagedbase, \$ghostcondbase, \$ghostlendbase, \$ladbase, \$wadbase, \$tagbase1, \$tagbase2, and \$morphcompdbase & Written to a separate file, \texttt{CompReport.sso}. Contains the length composition, age composition, and mean size-at-age observed and expected values. It is arranged in a database format, rather than an array of vectors which enables the use of dynamic filtering when using a spreadsheet program. \Bstrut\\
    53 & SELEX\_database & NA & \multirow{1}{1cm}[-0.25cm]{\parbox{9.5cm}{This section contains the selectivities organized as a database, rather than as a set of vectors.}} \\
       & \textit{Selectivity database} & & \Bstrut\\
    54 & SPR/YPR\_Profile & \$equil\_yield & This table displays per recruit quantities across a range of $F$ levels and using the biology- and selectivity-at-age from the benchmark(a.k.a. reference point) calculations. The SPRloop is various ways of defining a range of iterations to get good coverage. \Bstrut\\
    55 & GLOBAL\_MSY & NA & This table show \gls{msy} calculations using the actual fishery selectivity and by replacing with a range of knife-edge and per-age alternatives. \Bstrut\\
    56 & \texttt{SS\_summary.sso} & Read by \texttt{SS\_read\_summary()} & See \hyperlink{SS3Summary}{Stock Synthesis Summary section}. \Bstrut\\
    57 & \texttt{rebuilder.sso} & NA & Specific to the U.S. West Coast rebuilding plans. See the \href{https://github.com/pfmc-assessments/rebuilder}{Pacific Fishery Management Council rebuilder code on GitHub} related to this output. \Bstrut\\
    58 & \texttt{SIStable.sso} & NA & See \hyperlink{SIStable}{SIS table section}. \Bstrut\\
    59 & Dynamic\_Bzero & \$Dynamic\_Bzero & Dynamic $B_{0}$ report \Bstrut\\
    60 & \texttt{wtatage.ss\_new} & \$wtatage & Contains mean weight-at-age for the population and each fleet as well as maturity $\times$ fecundity. For models that use the \texttt{wtatage.ss} file as an input, the values will match. For models with parametric growth, the values will be based on internal calculations of mean weight-at-age. SS3 generates a \texttt{wtatage.ss\_new} file even when these biological quantities are generated internally from parameters. \Bstrut\\
    61 & ANNUAL\_TIME\_SERIES & \$annual\_time\_series & Table shows the annual abundance at the beginning of each year (collapses all areas) and the total catch across all fleets. \\ 
    \hline
    \end{longtable}
\end{landscape}

\hypertarget{CustomReporting}{}
\subsection[Custom Reporting]{\protect\hyperlink{CustomReporting}{Custom Reporting}}
\hypertarget{custom}{} 
Additional user control for what is included in the \texttt{Report.sso} file was added in v.3.30.16. This approach allows for full customizing of what is printed to the Report file by selecting custom reporting (option = 3) in the starter file where specific items now can be included or excluded depending upon a list passed to SS3 from the starter file. The ``Report Number'' in the table above is used to select which outputs are included when using this option.

\hypertarget{ADMBOutput}{}
\subsection[Standard ADMB output files]{\protect\hyperlink{ADMBOutput}{Standard ADMB output files}}
Standard \gls{admb} files are created by SS3. These are:

\texttt{ss3.par} (previously \texttt{ss.par}) - This file has the final parameter values. They are listed in the order they are declared in SS3. This file can be read back into SS3 to restart a run with these values (see \hyperref[sec:RunningSS3]{Running Stock Synthesis} for more info).

\texttt{ss.std} - This file has the parameter values and their estimated standard deviation for those parameters that were active during the model run. It also contains the derived quantities declared as standard deviation report variables. All of this information is also reported in the \texttt{covar.sso}. Also, the parameter section of \texttt{Report.sso} lists all the parameters with their SS3 generated names, denotes which were active in the reported run, displays the parameter standard deviations, then displays the derived quantities with their standard deviations.

\texttt{ss.rep} - This report file is created between phases so, unlike \texttt{Report.sso}, will be created even if the hessian fails. It does not contain as much output as shown in \texttt{Report.sso}.

\texttt{ss.cor} - This is the standard \gls{admb} report for parameter and standard deviation report correlations. It is in matrix form and challenging to interpret. This same information is reported in \texttt{covar.sso}.

\hypertarget{SS3Summary}{}
\subsection[Stock Synthesis Summary]{\protect\hyperlink{SS3Summary}{Stock Synthesis Summary}}
The \texttt{ss\_summary.sso} file (available for versions 3.30.08.03 and later) is designed to put key model outputs all in one concise place. It is organized as a list. At the top of the file are descriptors, followed by the 1) likelihoods for each component, 2) parameters and their standard errors, and 3) derived quantities and their standard errors. Total biomass, summary biomass, and catch were added to the quantities reported in this file in v.3.30.11 and later.

Before v.3.30.17, TotBio and SmryBio did not always match values reported in columns of the TIME\_SERIES table of \texttt{Report.sso}. The report file should be used instead of \texttt{ss\_summary.sso} for correct calculation of these quantities before v.3.30.17. Care should be taken when using the TotBio and SmryBio if the model configuration has recruitment after January 1 or in a later season, as TotBio and SmryBio quantities are always calculated on January 1. Consult the detailed age-, area-, and season-specific tables in \texttt{Report.sso} for calculations done at times other than January 1.

\hypertarget{SIStable}{}
\subsection[SIS table]{\protect\hyperlink{SIStable}{SIS table}}
The \texttt{SIS\_table.sso} is deprecated as of v.3.30.17. Please use the \texttt{r4ss} function \texttt{get\_SIS\_info()} to produce output formatted for reading into the \gls{nmfs} \href{https://www.st.nmfs.noaa.gov/sis/}{\gls{sis}} database.

\hypertarget{DerivedQuant}{}
\subsection[Derived Quantities]{\protect\hyperlink{DerivedQuant}{Derived Quantities}}
Before listing the derived quantities reported to the standard deviation report, there are a couple of topics that deserve further explanation.

\hypertarget{VirginUnfished}{}
\subsubsection[Virgin Spawning Biomass vs. Unfished Spawning Biomass]{\protect\hyperlink{VirginUnfished}{Virgin Spawning Biomass vs. Unfished Spawning Biomass}}
Unfished is the condition for which reference points (benchmark) are calculated. Virgin Spawning Biomass is the initial condition on which the start of the time series depends. If biology or spawner-recruitment parameters are time-varying, then the benchmark year input in the forecast file tells the model which years to average in order to calculate ``unfished''. In this case, virgin recruitment and/or the virgin spawning biomass will differ from their unfished counterparts. Virgin recruitment and spawning biomass are reported in the mgmt\_quant portion of the sd\_report and are now labeled as ``unfished'' for clarity. Note that if $ln(R_{0})$ is time-varying, then this will cause unfished to differ from virgin. However, if regime shift parameter is time-varying, then unfished will remain the same as virgin because the regime shift is treated as a temporary offset from virgin. Virgin spawning biomass is denoted as SSB\_virgin and spawning biomass unfished is denoted as SSB\_unfished in the report file.

Virgin Spawning Biomass is used in four ways within SS3:
\begin{enumerate}
	\item Anchor for the spawner-recruitment relationship as virgin spawning biomass.
	\item Basis for the initial equilibrium abundance. 
	\item Basis against which annual depletion is calculated.
	\item Benchmark calculations.
\end{enumerate}
However, if there is time-varying biology, then the 4th usage can have a different Virgin Spawning Biomass calculation compared to the other usages.

\hypertarget{FMortality}{}
\subsubsection[Metrics for Fishing Mortality]{\protect\hyperlink{FMortality}{Metrics for Fishing Mortality}}
\myparagraph{Annual Fishing Intensity}
Fishery management systems expect to have a measure of annual fishing mortality that describes the intensity of the fishery such that an optimal level of $F$ can be articulated, and accountability measures can be invoked if $F$ is too high, e.g., overfishing. This concept is simple and straightforward if the model is a simple biomass dynamics such that a single annual $F$ value operates on the entirety of a non-age structured population. It also is simple for age-structured models that have a single fishing fleet and knife-edge selectivity beginning at some specified age.

The simplicity of $F$ disappears quickly as models invoke a variety of realistic complexities such as: allowing the $F$ to differ among ages or to be based on size; using a collection of fleets with different $F$ levels and different age patterns for $F$; spreading the population across areas and allowing different fleets with different $F$ among the areas. An unambiguous measure of annual fishing intensity that represents the cumulative effect of all that complexity has not been defined. This problem has not been solved with SS3, but some logical alternatives have been made available. Two complementary approaches are reported: \gls{spr} shows the long-term effect of fishing on the stock’s spawning potential, $F\text{\_std}$ shows a statistic related to the fraction of the population removed each year. The various options for both of these are found in the \texttt{starter.ss} file and described in that section of this manual. $F\text{std}_y$ is reported in the derived quantities, so variance is calculated for this quantity.

\myparagraph{Additional $F$ output}

The $F$ statistics are displayed most explicitly in the \texttt{Report.sso} table ``EXPLOITATION report:14''. There, the table columns are:
\begin{quote}
	\begin{verbatim}
	Yr Seas Seas\_dur F\_std annual\_F annual\_M <each fleet's F\_scalar>
	\end{verbatim}
\end{quote}

In this table, the displayed value for $\text{annual\_}F$ will be from the $F=Z-M$ method regardless of which option was chosen for $F\text{\_std}$. If $F\text{\_std}$ uses option 4 or 5, then the $\text{annual\_}F$ will use the same range of ages. Otherwise, $\text{annual\_}F$ will be for the age that is the mid-age of the age range of the model.

\myparagraph{$F\text{-at-Age}$}
$F\text{-at-Age}$ for each fleet is presented in \texttt{Report.sso} as table 39. Its header looks like:
\begin{quote}
	\begin{verbatim}
	F\_AT\_AGE report:39
	Area Fleet Sex Morph Yr Seas Era 0 1 2
	\end{verbatim}
\end{quote}

In addition to the $F\_std$ and $\text{annual\_}F$ outputs, info on total $F\text{-at-Age}$ across all fleets is reported at the end of the \texttt{Report.sso} file. This section of the report calculates $Z\text{-at-Age}$ as $ln(N_{a+1,t+1}/N_{a,t})$. This is done for numbers at the beginning of each year and the N values are summed over all areas. It is done once using the fishing intensities as estimated (to get $Z\text{-at-Age}$), and once with the $F$ intensities set to 0.0 to get $M\text{-at-Age}$. This latter sequence also provides a measure of dynamic Virgin Spawning Biomass. The user can then subtract the table of $M\text{-at-Age/year}$ from the table of $Z\text{-at-Age/year}$ to get a table of $F\text{-at-Age/year}$. From this $\text{apical\_}F$, average $F$ over a range of ages, or other user-desired statistics could be calculated. The header for this table looks like:
\begin{quote}
	\begin{verbatim}
	Z\_AT\_AGE\_Annual\_2 With\_fishery
	Bio\_Pattern Sex Yr  0 1 2
	\end{verbatim}
\end{quote}

A more detailed report provides $Z$ for each area, bio group (sex, morph, platoon) and age. It is titled something like ``Report\_Z\_by\_area\_morph\_platoon\_1 No\_fishery''. This table is done with and without the $F$ turned on, so that pair pf reports could be processed to get total $F$ by area, bio, age.

\myparagraph{Relative $F$ and $F\text{mult}$}
The $F'$ is fleet-specific, so it is useful to have a concept of relative $F$, $\text{rel}F_f$, among fleets. In SS3, $\text{rel}F_f= F_{t,f}'/\sum_{f}^{}F_{t,f}'$ for a single time period $t$. In the benchmark and forecast routines, SS3 can calculate $\text{rel}F_f$ using $F_{t,f}'$ over a range of years, or the user can input custom $\text{rel}F$ values for benchmark and forecast in the \texttt{forecast.ss} file. Note that in a multi-season model setup, $\text{rel}F_f$ is implemented as $\text{rel}F_{s,f}$ where $s$ is the season. These get multiplied by season duration as they are used.

In the benchmark section of the code, SS3 searches for an $F\text{mult}$ to achieve various management reference points (often referred to as benchmarks). In this search, SS3 calculates a benchmark $F$ as $F_{ben,f}' = F\text{mult} * \text{rel}F_f$, then calculates equilibrium yield and spawning biomass per recruit (\gls{spr}). SS3 searches for the $F\text{mult}$ that satisfies the search conditions, first for user-specified \gls{spr}, then for user-specified spawning biomass at a management target ($B_{TARGET}$) or $F_{0.1}$), then for \gls{msy}. The resultant benchmark quantities are reported in the derived quantities, but $F\text{mult}$ and $F_{ben,f}'$ are only reported in the \texttt{Forecast\_report.sso} file. SS3 stores the benchmark $F\text{mult}$ values so that user can invoke them for the forecast.

\myparagraph{Additional Stock Synthesis inputs related to $F$}
Below is a list of items to consider in terms of units for $F$ in SS3:
\begin{itemize}
	\item If $F\text{\_ballpark}$ is specified in the \texttt{control.ss} file, its units are the same as $\text{ann}F$, so is not fleet-specific.
	\item $F$ as parameter values has units of fleet-specific $F'$.
	\item In the \texttt{forecast.ss} file there is an option to input a vector of $\text{rel}F$ values. These are dimensionless and will be rescaled to sum to 1.0.
	\item In the \texttt{forecast.ss} file there is an option to specify an $F$ scalar for the forecast. The units of $F$ scalar are the same as the $F\text{mult}$ values calculated in benchmark. There are a full set of options for forecast $F$ scalar that can be selected in the forecast file.
	%(-1 = none; 0 = simple; 1 = F\textsubscript{SPR}; 2 = F\textsubscript{MSY} 3 = F\textsubscript{BTGT} or F\textsubscript{0.1}; 4 = Ave F (uses first-last relative F years); and 5 = input annual F scalar). 
	If the forecast $F$ scalar is set as $F_\text{SPR}$, then SS3 will use $\text{SPR\_}F\text{mult}$ calculated in benchmark and reported in \texttt{Forecast-report.sso}. If user selects the option to input an annual $F$ scalar, option 5, then the value is input on a following line. Whichever method the user selects for forecast $F$ scalar ($F\text{mult}$), SS3 will start the forecast by creating a fleet-specific vector of $\text{full\_}F$ values from $F\text{mult}*\text{rel}F_f$.
	\item Also in the \texttt{forecast.ss} file, the last section of inputs allows for input of time and fleet specific $F_{t,f}'$ values that override the basic forecast $F$ specification described above.
\end{itemize}

\hypertarget{MSYandBenchmarks}{}
\subsubsection[MSY and other Benchmark Items]{\protect\hyperlink{MSYandBenchmarks}{MSY and other Benchmark Items}}
The following quantities are included in the sdreport vector mgmt\_quantities, so obtain estimates of variance. Some additional quantities can be found in the benchmarks section of the \texttt{forecast\_report.sso}.

\begin{center}
	\begin{longtable}{p{4cm} p{11cm}}
		\hline
		Benchmark Item & Description \Tstrut\Bstrut\\
		\hline
		\endfirsthead

		\hline
		Benchmark Item & Description \Tstrut\Bstrut\\
		\hline
		\endhead
		
		\endfoot
		\hline		
		\endlastfoot
		
		SSB\_Unfished \Tstrut & Unfished reproductive potential (gls{ssb} is commonly female mature spawning biomass). \\
		TotBio\_Unfished \Tstrut & Total age 0+ biomass on January 1. \\
		SmryBio\_Unfished \Tstrut & Biomass for ages at or above the summary age on January 1. \\
		Recr\_Unfished \Tstrut & Unfished recruitment. \\
		SSB\_Btgt \Tstrut & \gls{ssb} at user specified \gls{ssb} target. \\
		SPR\_Btgt \Tstrut & \gls{spr} at $F$ intensity that produces user specified \gls{ssb} target. \\
		Fstd\_Btgt \Tstrut & $F$ statistic at $F$ intensity that produces user specified \gls{ssb} target. \\
		TotYield\_Btgt \Tstrut & Total yield at $F$ intensity that produces user specified \gls{ssb} target. \\
		SSB\_SPRtgt \Tstrut & \gls{ssb} at user specified \gls{spr} target (but taking into account the spawner-recruitment relationship). \\
		Fstd\_SPRtgt \Tstrut & $F$ intensity that produces user specified \gls{spr} target. \\
		TotYield\_SPRtgt \Tstrut & Total yield at $F$ intensity that produces user specified \gls{spr} target. \\
		SSB\_MSY \Tstrut & \gls{ssb} at $F$ intensity that is associated with \gls{msy}; this $F$ intensity may be directly calculated to produce \gls{msy}, or can be mapped to $F_{SPR}$ or $F_{B_{TARGET}}$. \\
		SPR\_MSY \Tstrut & \gls{spr} at $F$ intensity associated with \gls{msy}. \\
		Fstd\_MSY \Tstrut & $F$ statistic at $F$ intensity associated with \gls{msy}. \\
		TotYield\_MSY \Tstrut & Total yield (biomass) at \gls{msy}. \\
		RetYield\_MSY \Tstrut & Retained yield (biomass) at \gls{msy}. \Bstrut\\ 
	\end{longtable}
\end{center}

\hypertarget{CumulativeOutput}{}
\subsection[Brief cumulative output]{\protect\hyperlink{CumulativeOutput}{Brief cumulative output}}
Cum\_Report.sso: contains a brief version of the run output, which is appended to current content of file so results of several runs can be collected together. This is especially useful when a batch of runs is being processed. Unless this file is deleted, it will contain a cumulative record of all runs done in that subdirectory. The first column contains the run number.  

\hypertarget{bootstrap}{}
\subsection[Bootstrap Data Files]{\protect\hyperlink{bootstrap}{Bootstrap Data Files}}
It is possible to create bootstrap data files for SS3 where an internal parametric bootstrap function generates a simulated data set by parametric bootstrap sampling the expected values given the input observation error. Starting in v.3.30.19, bootstrap data files are output separated in single numbered files (e.g., \texttt{data\_boot\_001.ss}). In version prior to v.3.30.19 a single file called \texttt{data.ss\_new} was output that contained multiple sections: the original data echoed out, the expected data values based on the model fit, and then subsequent bootstrap data files. 

Specifying the number of bootstrap data files has remained the same across model versions. Creating bootstrap data files is specified in the starter file via the ``Number of datafiles to produce'' line where a value of 3 or greater will create three files: the original data file, \texttt{data\_echo.ss\_new}, a data file with the model expected values, \texttt{data\_expval.ss}, and single bootstrap data file, \texttt{data\_boot\_001.ss}. The first output provides the unaltered input data file (with annotations added). The second provides the expected values for only the data elements used in the model run. The third and subsequent outputs provide parametric bootstraps around the expected values. 

The bootstrapping procedure within SS3 is done via the following steps:

\begin{itemize}
	\item Expected values of all input data are calculated (these are also used in the likelihood which compares observed to expected values for all data). The calculation of these expected values is described in detail under the ``Observation Model'' section of the appendix to \citet{methotstock2013}.
	
	\item Parametric bootstrap data are calculated for each observation by sampling from a probability distribution corresponding to the likelihood for that data type using the expected values noted above. Examples of how this happens include the following:
	
	\begin{itemize}
		\item Indices of abundance are sampled from the distribution used in the estimation model (as set in the ``Errtype'' column of the index configuration, most commonly log-normal but could be normal or T-distribution). The variability of the distribution from which the random sample is drawn is based on the combination of the input uncertainty and any estimated ``Extra SD'' parameter and any ``add\_to\_survey\_CV'' value included under the input variance adjustments factors.
		
		\item Length and age compositions are sampled from multinomial distributions with expected proportions in each bin based on the expected values and sample size equal to the adjusted input sample size (input sample size multiplied by any inputs for ``mult\_by\_lencomp\_N'' or ``mult\_by\_agecomp\_N'' under the input variance adjustments factors).
		
		\item Discard data (fractions or absolute amounts) are generated from the chosen distribution (T-distribution, normal, log-normal, truncated-normal).
		
		\item Tagging data is generated using a negative binomial distribution to get the total number of recaptures for each tag group and a multinomial distribution to allocate those recaptures among fleets.
	\end{itemize}
\end{itemize}

Given this, there are some assumptions implicit in the bootstrapping procedure (as implemented as of v.3.30.17) that users should be aware of:

\begin{itemize}

	\item This procedure is strictly an observation error approach (i.e., process error in recruitment or any other time-varying parameter is not added). For simulation analyses, a common approach has been to input a new time series of recruitment deviations for each bootstrap data set.
	
	\item The sample size for conditional age-at-length data matches the inputs for each length bin. If stratified sampling is used, this may be appropriate, but if the ages represent a random subset of the selected population, this may result in less variability than if the associated length distribution were resampled.
	
	\item Currently, the aging error matrix is multiplied by the expected distribution of proportions at age, while the more correct order of operations would be to sample true ages, and then sample the observed age including aging error (it is possible these are mathematically identical).
	
	\item Often there is need to explore the removal (not include in the model fitting) of specific years in a data set which can be done by specifying a negative fleet number. If bootstrapping a data file, note that specifying a negative fleet in the data inputs for indices, length composition, or age composition will include the ``observation'' in the model (hence generating predicted values and bootstrap data sets for the data), but not in the negative log likelihood. The ``observation values'' used with negative fleet do not influence the predicted values, except when using tail compression with length or age composition. Non-zero values greater than the minimum tail compression should be used for the observation values when tail compression is being used, as using zeros or values smaller than the minimum tail compression can cause the predicted values to be reported as zero and shift predictions to other bins.
	
	\item As of v.3.30.15, age and length composition data that use the Dirichlet-multinomial distribution in the model are generated using the Dirichlet-multinomial in bootstrap data sets.
	
\end{itemize}

\hypertarget{ForecastRefPoints}{}
\subsection[Forecast and Reference Points (\texttt{Forecast-report.sso})]{\protect\hyperlink{ForecastRefPoints}{Forecast and Reference Points (\texttt{Forecast-report.sso})}}
The Forecast-report file contains output of fishery reference points and forecasts. It is designed to meet the needs of the Pacific Fishery Management Council's Groundfish Fishery Management Plan, but it should be quite feasible to develop other regionally specific variants of this output.

The vector of forecast recruitment deviations is estimated during an additional model estimation phase. This vector includes any years after the end of the recruitment deviation time series and before or at the end year. When this vector starts before the ending year of the time series, then the estimates of these recruitments will be influenced by the data in these final years. This is problematic, because the original reason for not estimating these recruitments at the end of the time series was the poor signal/noise ratio in the available data. It is not that these data are worse than data from earlier in the time series, but the low amount of data accumulated for each cohort allows an individual datum to dominate the model's fit. Thus, an additional control is provided so that forecast recruitment deviations during these years can receive an extra weighting in order to counter-balance the influence of noisy data at the end of the time series.

An additional control is provided for the fraction of the log-bias adjustment to apply to the forecast recruitments. Recall that R is the expected mean level of recruitment for a particular year as specified by the spawner-recruitment curve and R' is the geometric mean recruitment level calculated by discounting R with the log-bias correction factor $e-0.5s^2$. Thus, a log-normal distribution of recruitment deviations centered on R' will produce a mean level of recruitment equal to R. During the modeled time series, the virgin recruitment level and any recruitments prior to the first year of recruitment deviations are set at the level of R, and the log-normal recruitment deviations are centered on the R' level. For the forecast recruitments, the fraction control can be set to 1.0 so that 100\% of the log-bias correction is applied and the forecast recruitment deviations will be based on the R' level. This is certainly the configuration to use when the model is in \gls{mcmc} mode. Setting the fraction to 0.0 during maximum likelihood forecasts would center the recruitment deviations, which all have a value of 0.0 in maximum likelihood mode, on R. Thus would provide a mean forecast that would be more comparable to the mean of the ensemble of forecasts produced in \gls{mcmc} mode. Further work on this topic is underway.

Note:
\begin{itemize}
	\item Cohorts continue growing according to their specific growth parameters in the forecast period rather than staying static at the end year values.
	\item Environmental data entered for future years can be used to adjust expected recruitment levels. However, environmental data will not affect growth or selectivity parameters in the forecast.
\end{itemize}

The top of the Forecast-report file shows the search for $F_{SPR}$ and the search for $F_{MSY}$, allowing the user to verify convergence. Note: if the STD file shows aberrant results, such as all the standard deviations being the same value for all recruitments, then check the $F_{MSY}$ search for convergence. The $F_{MSY}$ can be calculated, or set equal to one of the other $F$ reference points per the selection made in \texttt{starter.ss}. 

\pagebreak