Skip to content

Commit

Permalink
update spelling
Browse files Browse the repository at this point in the history
  • Loading branch information
@e-perl-NOAA
e-perl-NOAA committed May 14, 2024
1 parent 789606f commit 7f70529
Show file tree
Hide file tree
Showing 6 changed files with 70 additions and 21 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/build-ss3-manual-pdf.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ jobs:
id: spellcheck
with:
root_file: SS330_User_Manual.tex
args: --check en --dict dictionary.txt --ignore sh:nobreak,lt:en:UNIT_SPACE,lt:en:UPPERCASE_SENTENCE_START
args: --check en --dict dictionary.txt --ignore sh:nobreak,sh:stacked,lt:en:UNIT_SPACE,lt:en:UPPERCASE_SENTENCE_START,lt:en:COMMA_COMPOUND_SENTENCE_2

# - name: Throw error if spellcheck warnings exist
# if: ${{ steps.spellcheck.outputs.num_warnings != 0 }}
Expand Down
10 changes: 5 additions & 5 deletions 1_4sections.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ \section{Introduction}\label{sec:intro}

SS3 has a population sub-model that simulates a stock's growth, maturity, fecundity, recruitment, movement, and mortality processes, an observation sub-model estimates expected values for various types of data, a statistical sub-model characterizes the data's goodness of fit and obtains best-fitting parameters with associated variance, and a forecast sub-model projects needed management quantities. SS3 outputs the quantities, with confidence intervals, needed to implement risk-averse fishery control rules. The model is coded in C++ with parameter estimation enabled by automatic differentiation (\href{http://www.admb-project.org}{admb}). Windows, Linux, and iOS versions are available. Output processing and associated tools are in R, and a graphical interface is in QT. SS3 executables and support material is available on \href{https://github.com/nmfs-ost}{GitHub}. The rich feature set in SS3 allows it to be configured for a wide range of situations. SS3 has become the basis for a large fraction of U.S. assessments and many other assessments around the world.

This manual provides a guide for using SS3. The guide contains a description of the input and output files and usage instructions. An overview and technical description of the model itself is in \citet{methotstock2013}. However, SS3 has continued to evolve and grow since the publication in 2013, with this manual reflecting the most up to date information regarding SS3. The model and a graphical user interface are available on \href{https://github.com/nmfs-ost}{GitHub} with older archived versions also available online at \href{https://vlab.noaa.gov/web/stock-synthesis}{NOAA VLAB}. The VLAB site also provides a user forum for posting questions and for accessing various additional materials. An output processor package, r4ss, in R is available for download from CRAN or \href{https://github.com/r4ss/r4ss}{GitHub}.
This manual provides a guide for using SS3. The guide contains a description of the input and output files and usage instructions. An overview and technical description of the model itself is in \citet{methotstock2013}. However, SS3 has continued to evolve and grow since the publication in 2013, with this manual reflecting the most up-to-date information regarding SS3. The model and a graphical user interface are available on \href{https://github.com/nmfs-ost}{GitHub} with older archived versions also available online at \href{https://vlab.noaa.gov/web/stock-synthesis}{NOAA VLAB}. The VLAB site also provides a user forum for posting questions and for accessing various additional materials. An output processor package, r4ss, in R is available for download from CRAN or \href{https://github.com/r4ss/r4ss}{GitHub}.

Additional guidance for new users can be found online in the \href{https://nmfs-ost.github.io/ss3-doc/Getting_Started_SS3.html}{Getting Started Tutorial} and on the \href{https://github.com/nmfs-ost/ss3-source-code#how-can-i-learn-how-to-use-stock-synthesis}{Stock Synthesis GitHub} page.

Expand All @@ -25,7 +25,7 @@ \section{Introduction}\label{sec:intro}

Please cite the Stock Synthesis User Manual as:

Methot, R. D., Jr., C. R. Wetzel, I. G. Taylor, and K. Doering. (2020). Stock Synthesis User Manual Version 3.30.15. U.S. Department of Commerce, NOAA Processed Report NMFS-NWFSC-PR-2020-05.\href{https://doi.org/10.25923/5wpn-qt71}{https://doi.org/10.25923/5wpn-qt71}
Methot, R. D., Jr., C. R. Wetzel, I. G. Taylor, and K. Doering. (2020). Stock Synthesis User Manual Version 3.30.15. U.S. Department of Commerce, NOAA Processed Report NMFS-NWFSC-PR-2020-05. \href{https://doi.org/10.25923/5wpn-qt71}{https://doi.org/10.25923/5wpn-qt71}

\pagebreak

Expand All @@ -46,7 +46,7 @@ \section{File Organization}\label{FileOrganization}
\begin{enumerate}
\item data\_echo.ss\_new: Contains the input data as read by the model. In model versions prior to v.3.30.19 a single data.ss\_new file was created that included the echoed data, the expected data values (data\_expval.ss), and any bootstrap data files selected (data\_boot\_x.ss).
\item data\_expval.ss: Contains the expected data values given the model fit. This file is only created if the value for ``Number of datafiles to produce'' in the starter file is set to 2 or greater.
\item data\_boot\_x.ss: A new data file filled with bootstrap data based on the original input data and variances. This file is only created if the value in the ``Number of datafiles to produc'' in the starter file is set to 3 or greater. A separate bootstrap data file will be written for the number of bootstrap data file requests where x in the file name indicates the bootstrap simulation number (e.g., data\_boot\_001.ss, data\_boot\_002.ss,...).
\item data\_boot\_x.ss: A new data file filled with bootstrap data based on the original input data and variances. This file is only created if the value in the ``Number of datafiles to produce'' in the starter file is set to 3 or greater. A separate bootstrap data file will be written for the number of bootstrap data file requests where x in the file name indicates the bootstrap simulation number (e.g., data\_boot\_001.ss, data\_boot\_002.ss, ...).
\item control.ss\_ new: Updated version of the control file with final parameter values replacing the initial parameter values.
\item starter.ss\_ new: New version of the starter file with annotations.
\item Forecast.ss\_ new: New version of the forecast file with annotations.
Expand All @@ -56,7 +56,7 @@ \section{File Organization}\label{FileOrganization}
\item ss\_summary.sso: Output file that contains all the likelihood components, parameters, derived quantities, total biomass, summary biomass, and catch. This file offers an abridged version of the report file that is useful for quick model evaluation. This file is only available in v.3.30.08.03 and greater.
\item CompReport.sso: Observed and expected composition data in a list-based format.
\item Forecast-report.sso: Output of management quantities and for forecasts.
\item CumReport.sso: This file contains a brief version of the run output, output is appended to current content of file so results of several runs can be collected together. This is useful when a batch of runs is being processed.
\item CumReport.sso: This file contains a brief version of the run output, output is appended to current content of file so that the results of several runs can be collected together. This is useful when a batch of runs is being processed.
\item Covar.sso: This file replaces the standard ADMB ss.cor with an output of the parameter and derived quantity correlations in database format.
\item ss3.par (previously ss.par): This file contains all estimated and fixed parameters from the model run.
\item ss.std, ss.rep, ss.cor etc.: Standard ADMB output files.
Expand All @@ -73,6 +73,6 @@ \section{File Organization}\label{FileOrganization}
\section{Starting Stock Synthesis}
SS3 is typically run through the command line interface, although it can also be called from another program, R, the Stock Synthesis Interface, or a script file (such as a DOS batch file). SS3 is compiled for Windows, Mac, and Linux operating systems. The memory requirements depend on the complexity of the model you run, but in general, SS3 will run much slower on computers with inadequate memory. See \hyperref[sec:RunningSS3]{Running Stock Synthesis} for additional notes on methods of running SS3.

Communication with the program is through text files. When the program first starts, it reads the file starter.ss, which typically must be located in the same directory from which SS3 is being run. The file starter.ss contains required input information plus references to other required input files, as described in the \hyperref[FileOrganization]{File Organization section}. The names of the control and data files must match the names specified in the starter.ss file. File names, including starter.ss, are case-sensitive on Linux and Mac systems but not on Windows. The echoinput.sso file outputs how the executable reads each input file and can be used for troubleshooting when trying to setup a model correctly. Output from SS3 consists of text files containing specific keywords. Output processing programs, such as Excel, or R can search for these keywords and parse the specific information located below that keyword in the text file.
Communication with the program is through text files. When the program first starts, it reads the file starter.ss, which typically must be located in the same directory from which SS3 is being run. The file starter.ss contains required input information plus references to other required input files, as described in the \hyperref[FileOrganization]{File Organization section}. The names of the control and data files must match the names specified in the starter.ss file. File names, including starter.ss, are case-sensitive on Linux and Mac systems but not on Windows. The echoinput.sso file outputs how the executable reads each input file and can be used for troubleshooting when trying to set up a model correctly. Output from SS3 consists of text files containing specific keywords. Output processing programs, such as Excel, or R can search for these keywords and parse the specific information located below that keyword in the text file.

\pagebreak
10 changes: 5 additions & 5 deletions 6starter.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ \subsection{Starter File Options (starter.ss)}
\hline
1 & Detailed age-structure report: & \multirow{1}{1cm}[-0.15cm]{\parbox{12.5cm}{Option 0 will forgo the writing of the Report file, but the ss\_summary file will be written that has minimal derived and estimated quantities. This is a useful option for some data-limited assessment approaches (e.g., XSSS or SSS). Option 1 will write out the full Report file. Option 2 will write out select items in the Report file and will omit some more detailed sections (e.g., numbers-at-age).}} \Tstrut\\
& 0 = minimal output for data-limited methods; & \\
& 1 = include all output (with wtatage.ss\_new); & \\
& 1 = include all output (with wtatage.ss\_new); & \\
& 2 = brief output, no growth; and & \\
& 3 = custom output & \\
\pagebreak
Expand All @@ -72,7 +72,7 @@ \subsection{Starter File Options (starter.ss)}
& 1 = write detailed intermediate calculations to echoinput.sso during first call. & \Bstrut\\

\hline
0 & Parameter Trace: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{This controls the output to parmtrace.sso. The contents of this output can be used to determine which values are changing when a model approaches a crash condition. It also can be used to investigate patterns of parameter changes as model convergence slowly moves along a ridge. In order to access parameter gradients option 4 should be selected which will write the gradient of each parameter with respect to each likelihood component}} \Tstrut\\
0 & Parameter Trace: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{This controls the output to parmtrace.sso. The contents of this output can be used to determine which values are changing when a model approaches a crash condition. It also can be used to investigate patterns of parameter changes as model convergence slowly moves along a ridge. In order to access parameter gradients option 4 should be selected which will write the gradient of each parameter with respect to each likelihood component}} \Tstrut\\
& 0 = omit; & \\
& 1 = write good iteration and active parameters; & \\
& 2 = write good iterations and all parameters; & \\
Expand Down Expand Up @@ -155,7 +155,7 @@ \subsection{Starter File Options (starter.ss)}

%\pagebreak
%\hline
\multicolumn{1}{r}{1940 1950} & \multirow{1}{1cm}[-0.25cm]{\parbox{19.5cm}{Vector of years for additional SD reporting. The number of years need to equal the value specified in the above line (Extra SD Report Years).}} \\
\multicolumn{1}{r}{1940 1950} & \multirow{1}{1cm}[-0.25cm]{\parbox{19.5cm}{Vector of years for additional SD reporting. The number of years needs to equal the value specified in the above line (Extra SD Report Years).}} \\
& & \\

\hline
Expand Down Expand Up @@ -183,7 +183,7 @@ \subsection{Starter File Options (starter.ss)}
& 4 = X*SB\textsubscript{endyr}. & Relative to spawning biomass in the model end year. \\
& 5 = X*Dynamic SB0 & Relative to the calculated dynamic SB0. \\
& & Use hundreds and tens place to invoke multi-year trailing average, the ones place for depletion basis value, and the decimal place invoke log(ratio). This approach for multi-year log(ratio) was implemented with v.3.30.24 (2024). \\
& & Example: 122.1 invokes a 12 year trailing average for X*SB\textsubscript{MSY} using log(ratio). \\
& & Example: 122.1 invokes a 12-year trailing average for X*SB\textsubscript{MSY} using log(ratio). \\
& & Note that the trailing average always goes up to the endyr and once it gets to the first forecast year it stops the trailing average. \Bstrut\\

\hline
Expand All @@ -200,7 +200,7 @@ \subsection{Starter File Options (starter.ss)}

% \pagebreak
\hline
4 & Annual F units: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{In addition to SPR, an additional proxy for annual F can be specified here. As with SPR, the selected quantity will be calculated annually and in the benchmarks section. The ratio of the annual value to the selected (see F report basis below) benchmark value is reported to the SD report vector. Options 1 and 2 use total catch for the year and summary abundance at the beginning of the year, so combines seasons and areas. But if most catch occurs in one area and there is little movement between areas, this ratio is not informative about the F in the area where the catch is occurring. Option 3 is a simple sum of the full F's by fleet, so may provide non-intuitive results when there are multi areas or seasons or when the selectivities by fleet do not have good overlap in age. Option 4 is a real annual F calculated as a numbers weighted F for a specified range of ages (read below). The F is calculated as Z-M where Z and M are each calculated an ln(N\textsubscript{t+1}/N\textsubscript{t}) with and without F active, respectively. The numbers are summed over all biology morphs and all areas for the beginning of the year, so subsumes any seasonal pattern.}} \Tstrut\Bstrut\\
4 & Annual F units: & \multirow{1}{1cm}[-0.25cm]{\parbox{12.5cm}{In addition to SPR, an additional proxy for annual F can be specified here. As with SPR, the selected quantity will be calculated annually and in the benchmarks section. The ratio of the annual value to the selected (see F report basis below) benchmark value is reported to the SD report vector. Options 1 and 2 use total catch for the year and summary abundance at the beginning of the year, so combines seasons and areas. But if most catch occurs in one area and there is little movement between areas, this ratio is not informative about the F in the area where the catch is occurring. Option 3 is a simple sum of the full F's by fleet, so may provide non-intuitive results when there are multi areas or seasons or when the selectivities by fleet do not have good overlap in age. Option 4 is a real annual F calculated as a numbers weighted F for a specified range of ages (read below). The F is calculated as Z-M where Z and M are each calculated a ln(N\textsubscript{t+1}/N\textsubscript{t}) with and without F active, respectively. The numbers are summed over all biology morphs and all areas for the beginning of the year, so subsumes any seasonal pattern.}} \Tstrut\Bstrut\\
& 0 = skip; & \\
& 1 = exploitation rate in biomass; & \\
& 2 = exploitation rate in numbers; & \\
Expand Down
6 changes: 3 additions & 3 deletions 7forecast.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,8 +79,8 @@ \subsection{Forecast File Options (forecast.ss)}
\hline
\multirow{1}{1cm}[-0.15cm]{\parbox{2cm}{0 0 0 0 0 0 0 0 0 0}} & Benchmark Years: & \multirow{1}{1cm}[-0.15cm]{\parbox{12cm}{Requires 5 pairs of year values over which the mean of derived vectors will be calculated to use in the benchmark (e.g. MSY) calculations. First pair of years is for biology (e.g., growth, natural mortality, maturity, fecundity); second is selectivity; third is relative Fs among fleets; fourth is movement and recruitment distribution; fifth is stock-recruitment (as the parameters, not as derived quantities). If a factor is not time-varying, select the first model year for the beginning year for the factor or else the variance will be artificially reduced.}} \Tstrut\\
& -999: start year; & \\
& >0: absolute year; and & \\
& <= 0: year relative to end year. & \Bstrut\\
& > 0: absolute year; and & \\
& $<=$ 0: year relative to end year. & \Bstrut\\
& & \\
& & \\
& & \\
Expand Down Expand Up @@ -201,7 +201,7 @@ \subsection{Forecast File Options (forecast.ss)}

\pagebreak
%\hline
\multicolumn{2}{l}{COND -1: Conditional input for annual control rule buffer} & \multirow{1}{1cm}[-0.25cm]{\parbox{12cm}{Year and control rule buffer value. Can enter a value for each year, or starting sequence of years. The final control rule buffer value will apply to all sequent forecast years.}} \\
\multicolumn{2}{l}{COND -1: Conditional input for annual control rule buffer} & \multirow{1}{1cm}[-0.25cm]{\parbox{12cm}{Year and control rule buffer value. Can enter a value for each year, or starting sequence of years. The final control rule buffer value will apply to all subsequent forecast years.}} \\
\multicolumn{1}{r}{2019 0.8} & & \\
\multicolumn{1}{r}{2020 0.6} & & \\
\multicolumn{1}{r}{2021 0.5} & & \\
Expand Down
Loading

0 comments on commit 7f70529

Please sign in to comment.