diff --git a/.github/workflows/call-ss3-manual-html-release.yml b/.github/workflows/call-ss3-manual-html-release.yml index 4aa0c9b8..0815a5f5 100644 --- a/.github/workflows/call-ss3-manual-html-release.yml +++ b/.github/workflows/call-ss3-manual-html-release.yml @@ -2,7 +2,7 @@ name: Build html for last release using texlive on: [workflow_dispatch] jobs: call-workflow: - uses: nmfs-stock-synthesis/doc/.github/workflows/build-ss3-manual-html.yml@main + uses: nmfs-ost/ss3-doc/.github/workflows/build-ss3-manual-html.yml@main with: # Note: upon new releases, will need to update this ref ref: 'v3.30.22' diff --git a/.github/workflows/call-ss3-manual-pdf-release.yml b/.github/workflows/call-ss3-manual-pdf-release.yml index 204a660a..74e6a106 100644 --- a/.github/workflows/call-ss3-manual-pdf-release.yml +++ b/.github/workflows/call-ss3-manual-pdf-release.yml @@ -2,7 +2,7 @@ name: Build pdf for last release using texlive on: [workflow_dispatch] jobs: call-workflow: - uses: nmfs-stock-synthesis/doc/.github/workflows/build-ss3-manual-pdf.yml@main + uses: nmfs-ost/ss3-doc/.github/workflows/build-ss3-manual-pdf.yml@main with: # Note: upon new releases, will need to update this ref ref: 'v3.30.22' diff --git a/12runningSS3.tex b/12runningSS3.tex index 75cc9aa4..40cec0a6 100644 --- a/12runningSS3.tex +++ b/12runningSS3.tex @@ -253,7 +253,7 @@ \subsubsection{For Windows} To add the SS3 binary file to your path, follow these steps: \begin{enumerate} - \item Find the correct version of the SS3.exe binary on your computer (or download from the \href{https://github.com/nmfs-stock-synthesis/stock-synthesis/releases}{SS3 releases}). + \item Find the correct version of the SS3.exe binary on your computer (or download from the \href{https://github.com/nmfs-ost/ss3-source-code/releases}{SS3 releases}). \item Move to and note the folder location. E.g., \texttt{C:/SS3/} \item Click on the start menu and type \texttt{environment} \item Choose \texttt{Edit environment variables for your account} under Control Panel diff --git a/1_4sections.tex b/1_4sections.tex index 3ab3e21b..aa1d93a4 100644 --- a/1_4sections.tex +++ b/1_4sections.tex @@ -9,11 +9,11 @@ \section{Introduction}\label{sec:intro} Stock Synthesis is an age- and size-structured assessment model in the class of models termed integrated analysis models. Stock Synthesis has evolved since its initial inception in order to model a wide range of fish populations and dynamics. The most recent major revision to Stock Synthesis occurred in 2016, when v.3.30 was introduced. This new version of Stock Synthesis required major revisions to the input files relative to earlier versions (see the \hypertarget{ConvIssues}{Converting Files} section for more information). The acronym for Stock Synthesis has evolved over time with earlier versions being referred to as SS2 (Stock Synthesis v.2.xx) and older versions as SS3 (Stock Synthesis v.3.xx). -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-stock-synthesis}{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. +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-stock-synthesis}{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-stock-synthesis.github.io/doc/Getting_Started_SS.html}{Getting Started Tutorial} and on the \href{https://github.com/nmfs-stock-synthesis/stock-synthesis#how-can-i-learn-how-to-use-stock-synthesis}{Stock Synthesis GitHub} page. +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. \subsection{How To Cite} diff --git a/5converting.tex b/5converting.tex index 00d62a98..aec0711f 100644 --- a/5converting.tex +++ b/5converting.tex @@ -1,6 +1,6 @@ \hypertarget{ConvIssues}{} \section{Converting Files from Stock Synthesis v.3.24} -Converting files from version 3.24 to version 3.30 can be performed by using the program ss\_trans.exe. This executable takes v.3.24 files as input and will output v.3.30 input and output files. SS\_trans executables are available for v.3.30.01 - v.3.30.17. The transitional executable was phased out with v.3.30.18. If a model needs to be converted from v.3.24 to a recent version, one should use the v.3.30.17 ss\_trans.exe available from the \href{https://github.com/nmfs-stock-synthesis/stock-synthesis/releases/tag/v3.30.17}{v.3.30.17 release page on GitHub} to convert the files and then any additional adjustments needed between v.3.30.17 and newer versions should be done by hand. +Converting files from version 3.24 to version 3.30 can be performed by using the program ss\_trans.exe. This executable takes v.3.24 files as input and will output v.3.30 input and output files. SS\_trans executables are available for v.3.30.01 - v.3.30.17. The transitional executable was phased out with v.3.30.18. If a model needs to be converted from v.3.24 to a recent version, one should use the v.3.30.17 ss\_trans.exe available from the \href{https://github.com/nmfs-ost/ss3-source-code/releases/tag/v3.30.17}{v.3.30.17 release page on GitHub} to convert the files and then any additional adjustments needed between v.3.30.17 and newer versions should be done by hand. The following file structure and steps are recommended for converting model files: \begin{enumerate} diff --git a/6starter.tex b/6starter.tex index 99d0513d..1766fc17 100644 --- a/6starter.tex +++ b/6starter.tex @@ -98,6 +98,7 @@ \subsection{Starter File Options (starter.ss)} & & \\ & & \\ & & \\ + & & \\ \pagebreak % \hline @@ -207,8 +208,8 @@ \subsection{Starter File Options (starter.ss)} & 5 = unweighted average F for range of ages. & \\ & & \\ & & \\ - & & \Bstrut\\ - & & \Bstrut\\ + & & \Bstrut\Bstrut\\ + & & \Bstrut\Bstrut\\ & & \Bstrut\\ % & & \\ @@ -236,6 +237,7 @@ \subsection{Starter File Options (starter.ss)} & 3 = make output subdirectory for each MCMC vector. & \Bstrut\\ & & \Tstrut\Bstrut\\ & & \\ + & & \\ % & & \\ \hline diff --git a/8data.tex b/8data.tex index 4bddbf46..c6ac3b5f 100644 --- a/8data.tex +++ b/8data.tex @@ -863,7 +863,7 @@ \subsubsection{Ageing Error} The model is able to create one ageing error matrix from parameters, rather than from an input vector. The range of conditions in which this new feature will perform well has not been evaluated, so it should be considered as a preliminary implementation and subject to modification. To invoke this option, for the selected ageing error vector, set the standard deviation of ageing error to a negative value for age 0. This will cause creation of an ageing error matrix from parameters and any age or size-at-age data that specify use of this age error pattern will use this matrix. Then in the control file, add a full parameter line below the cohort growth deviation parameter (or the movement parameter lines if used) in the mortality growth parameter section. These parameters are described in the control file section of this manual. -Code for ageing error calculation can be found in \href{https://github.com/nmfs-stock-synthesis/stock-synthesis/blob/main/SS_miscfxn.tpl}{SS\_miscfxn.tpl}, search for function ``get\_age\_age'' or ``SS\_Label\_Function 45''. +Code for ageing error calculation can be found in \href{https://github.com/nmfs-ost/ss3-source-code/blob/main/SS_miscfxn.tpl}{SS\_miscfxn.tpl}, search for function ``get\_age\_age'' or ``SS\_Label\_Function 45''. \subsubsection{Age Composition Specification} If age data are included in the model, the following set-up is required, similar to the length data section. diff --git a/9control.tex b/9control.tex index 8e164c2f..10818d7f 100644 --- a/9control.tex +++ b/9control.tex @@ -745,7 +745,7 @@ \subsubsection{Ageing Error Parameters} \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-stock-synthesis/stock-synthesis/blob/main/SS_miscfxn.tpl}{SS\_miscfxn.tpl} file, search for function ``get\_age\_age'' or ``SS\_Label\_Function 45''. +\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''. \subsubsection{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. @@ -1089,7 +1089,7 @@ \subsubsection{Spawner-Recruitment Functions} 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-stock-synthesis/stock-synthesis/blob/main/SS_recruit.tpl}{SS\_recruit.tpl}, search for ``SS\_Label\_43.3.7 survival based''. +Code for the survival based recruitment can be found in \href{https://github.com/nmfs-ost/ss3-source-code/blob/main/SS_recruit.tpl}{SS\_recruit.tpl}, search for ``SS\_Label\_43.3.7 survival based''. \myparagraph{Shepherd} \hypertarget{Shepherd}{The} Shepherd stock recruit curve is calculated as: @@ -1882,7 +1882,7 @@ \subsubsection{Selectivity Pattern Details} \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-stock-synthesis/stock-synthesis/blob/main/SS_selex.tpl}{SS\_selex.tpl}, search for ``SS\_Label\_Info\_22.7.17''. +Code for implementing random walk selectivity can be found in \href{https://github.com/nmfs-ost/ss3-source-code/blob/main/SS_selex.tpl}{SS\_selex.tpl}, search for ``SS\_Label\_Info\_22.7.17''. \myparagraph{Pattern 22 (size) - Double Normal with Plateau} \begin{itemize} @@ -2013,7 +2013,7 @@ \subsubsection{Selectivity Pattern Details} \end{itemize} Code for implementing cubic spline selectivity can be found in -\href{https://github.com/nmfs-stock-synthesis/stock-synthesis/blob/main/SS_selex.tpl}{SS\_selex.tpl}, +\href{https://github.com/nmfs-ost/ss3-source-code/blob/main/SS_selex.tpl}{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 set-up 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 problem. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 35ce9dd0..69ff5490 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to doc +# Contributing to ss3-doc ## General information Thank you for your interest in contributing to doc! We strive to follow the [NMFS Fisheries Toolbox Contribution Guide](https://github.com/nmfs-fish-tools/Resources/blob/master/CONTRIBUTING.md). Note that these are guidelines, not rules, and we are open to collaborations in other ways that may work better for you. Please feel free to reach out to us by opening an issue in this repository or by emailing the developers at nmfs.stock.synthsis@noaa.gov. @@ -7,6 +7,6 @@ This project and everyone participating in it is governed by the [NMFS Fisheries ## Compiling the Stock Synthesis manual -The manual can be compiled locally using a [LaTeX compiler](https://www.overleaf.com/learn/latex/Choosing_a_LaTeX_Compiler), such as TexLive or MikTex. To compile the whole document, clone the repository and follow instructions for LaTeX compiling, applying them to [SS330_User_Manual.tex](https://github.com/nmfs-stock-synthesis/doc). +The manual can be compiled locally using a [LaTeX compiler](https://www.overleaf.com/learn/latex/Choosing_a_LaTeX_Compiler), such as TexLive or MikTex. To compile the whole document, clone the repository and follow instructions for LaTeX compiling, applying them to [SS330_User_Manual.tex](https://github.com/nmfs-ost/ss3-doc). -The manual is also compiled using github actions on every commit to the doc repository. The manual is saved as an artifact and is available for viewing. For those who don't want to compile locally, a pull request could be submitted with changes to the .tex files and github actions can be used to see the compiled products. The [call-ss3-manual-html job](https://github.com/nmfs-stock-synthesis/doc/blob/main/.github/workflows/call-ss3-manual-html.yml) compiles the html version of the manual (using pandoc and R code), while the [call-ss3-manual-pdf](https://github.com/nmfs-stock-synthesis/doc/blob/main/.github/workflows/call-ss3-manual-pdf.yml) job compiles the pdf version. call-ss3-manual-pdf-release.yml and call-ss3-manual-html-release.yml are only run manually (not with every commit). +The manual is also compiled using github actions on every commit to the ss3-doc repository. The manual is saved as an artifact and is available for viewing. For those who don't want to compile locally, a pull request could be submitted with changes to the .tex files and github actions can be used to see the compiled products. The [call-ss3-manual-html job](https://github.com/nmfs-ost/ss3-doc/blob/main/.github/workflows/call-ss3-manual-html.yml) compiles the html version of the manual (using pandoc and R code), while the [call-ss3-manual-pdf](https://github.com/nmfs-ost/ss3-doc/blob/main/.github/workflows/call-ss3-manual-pdf.yml) job compiles the pdf version. call-ss3-manual-pdf-release.yml and call-ss3-manual-html-release.yml are only run manually (not with every commit). diff --git a/README.md b/README.md index 2e6cf24d..c1ffeac5 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -# doc +# ss3-doc +# ss3-doc Source code for the stock synthesis manual and other supplementary documentation. @@ -6,27 +7,32 @@ Source code for the stock synthesis manual and other supplementary documentation The documentation includes: - The Stock Synthesis user manual source code, in .tex files -- Getting started guide and Introduction to building an ss3 model guide, available in the [User_Guides subdirectory](https://github.com/nmfs-stock-synthesis/doc/tree/main/User_Guides) +- Getting started guide and Introduction to building an ss3 model guide, available in the [User_Guides subdirectory](https://github.com/nmfs-ost/ss3-doc/tree/main/User_Guides) ## Where can I find compiled versions of the documentation? -See the [documentation index page](https://nmfs-stock-synthesis.github.io/doc/) for links to a PDF and HTML version of the compiled documentation from the latest Stock Synthesis release. +See the [ss3 documentation index page](https://nmfs-ost.github.io/ss3-doc/) for links to a PDF and HTML version of the compiled documentation from the latest Stock Synthesis release. +See the [ss3 documentation index page](https://nmfs-ost.github.io/ss3-doc/) for links to a PDF and HTML version of the compiled documentation from the latest Stock Synthesis release. PDF versions of the user manual are also available in the [ss3 manuals folder on the vlab website](https://vlab.noaa.gov/web/stock-synthesis/document-library/-/document_library/0LmuycloZeIt/view/4513132). -The [contributing guide](https://github.com/nmfs-stock-synthesis/doc/blob/main/CONTRIBUTING.md) contains information on [how to compile locally or with github actions](https://github.com/nmfs-stock-synthesis/doc/blob/main/CONTRIBUTING.md#compiling-the-stock-synthesis-manual). +The [contributing guide](https://github.com/nmfs-ost/ss3-doc/blob/main/CONTRIBUTING.md) contains information on [how to compile locally or with github actions](https://github.com/nmfs-ost/ss3-doc/blob/main/CONTRIBUTING.md#compiling-the-stock-synthesis-manual). +The [contributing guide](https://github.com/nmfs-ost/ss3-doc/blob/main/CONTRIBUTING.md) contains information on [how to compile locally or with github actions](https://github.com/nmfs-ost/ss3-doc/blob/main/CONTRIBUTING.md#compiling-the-stock-synthesis-manual). ## How can I report bugs or suggest changes to the ss3 documentation? -Please open an [issue](https://github.com/nmfs-stock-synthesis/doc/issues) or submit a [pull request](https://github.com/nmfs-stock-synthesis/doc/pulls). +Please open an [issue](https://github.com/nmfs-ost/ss3-doc/issues) or submit a [pull request](https://github.com/nmfs-ost/ss3-doc/pulls). +Please open an [issue](https://github.com/nmfs-ost/ss3-doc/issues) or submit a [pull request](https://github.com/nmfs-ost/ss3-doc/pulls). ## Where should I ask a question about Stock Synthesis? -If you have a question related to Stock Synthesis, please post an issue [in the Stock Synthesis GitHub repository for model questions](https://github.com/nmfs-stock-synthesis/stock-synthesis/issues) or ask it on the [Stock Synthesis forums](https://vlab.noaa.gov/web/stock-synthesis/public-forums). If you have a question about the manual, please post an issue in the [Stock Synthesis documentation GitHub repository](https://github.com/nmfs-stock-synthesis/doc/issues), or email it to the Stock Synthesis team at nmfs.stock.synthesis@noaa.gov. +If you have a question related to Stock Synthesis, please post an issue [in the Stock Synthesis GitHub repository for model questions](https://github.com/nmfs-ost/ss3-source-code/issues) or ask it on the [Stock Synthesis forums](https://vlab.noaa.gov/web/stock-synthesis/public-forums). If you have a question about the manual, please post an issue in the [Stock Synthesis documentation GitHub repository](https://github.com/nmfs-ost/ss3-doc/issues), or email it to the Stock Synthesis team at nmfs.stock.synthesis@noaa.gov. +If you have a question related to Stock Synthesis, please post an issue [in the Stock Synthesis GitHub repository for model questions](https://github.com/nmfs-ost/ss3-source-code/issues) or ask it on the [Stock Synthesis forums](https://vlab.noaa.gov/web/stock-synthesis/public-forums). If you have a question about the manual, please post an issue in the [Stock Synthesis documentation GitHub repository](https://github.com/nmfs-ost/ss3-doc/issues), or email it to the Stock Synthesis team at nmfs.stock.synthesis@noaa.gov. ## How can I contribute to the Stock Synthesis documentation? -Please feel free to suggest changes by opening an [issue](https://github.com/nmfs-stock-synthesis/doc/issues) or submitting a [pull request](https://github.com/nmfs-stock-synthesis/doc/pulls)! We also welcome your ideas for other helpful resources that could be created to help users learn Stock Synthesis. +Please feel free to suggest changes by opening an [issue](https://github.com/nmfs-ost/ss3-doc/issues) or submitting a [pull request](https://github.com/nmfs-ost/ss3-doc/pulls)! We also welcome your ideas for other helpful resources that could be created to help users learn Stock Synthesis. +Please feel free to suggest changes by opening an [issue](https://github.com/nmfs-ost/ss3-doc/issues) or submitting a [pull request](https://github.com/nmfs-ost/ss3-doc/pulls)! We also welcome your ideas for other helpful resources that could be created to help users learn Stock Synthesis. For complete details, please see [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/Rcode/timevarying_illustration.R b/Rcode/timevarying_illustration.R index ebeab8b0..4d679394 100644 --- a/Rcode/timevarying_illustration.R +++ b/Rcode/timevarying_illustration.R @@ -66,7 +66,7 @@ yrs <- 1980:YrMax parm_timevary <- NA * yrs # calculations below adapted from -# https://github.com/nmfs-stock-synthesis/stock-synthesis/blob/cf0ce2f2f6e0e5e3e6a11805f1a9668f3449e916/SS_timevaryparm.tpl#L166-L177 +# https://github.com/nmfs-ost/ss3-source-code/blob/cf0ce2f2f6e0e5e3e6a11805f1a9668f3449e916/SS_timevaryparm.tpl#L166-L177 norm_styr <- pnorm(styr -infl_year)/slope temp <- (endtrend - baseparm) / (pnorm((endyr - infl_year) / slope) - norm_styr) # delta in cum_norm between styr and endyr diff --git a/User_Guides/getting_started/Getting_Started_SS3.Rmd b/User_Guides/getting_started/Getting_Started_SS3.Rmd index 683181fb..af804000 100644 --- a/User_Guides/getting_started/Getting_Started_SS3.Rmd +++ b/User_Guides/getting_started/Getting_Started_SS3.Rmd @@ -21,7 +21,7 @@ Stock Synthesis (SS3) is a statistical fisheries population dynamics modeling fr If you have never used the command line, please see the resources in [Appendix 1](#app1). -To follow along, we recommend downloading the [simple example](https://github.com/nmfs-stock-synthesis/user-examples/tree/main/model_files/simple) ([Instructions for downloading](https://github.com/nmfs-stock-synthesis/user-examples#how-to-download)) and the [latest release of SS3](https://github.com/nmfs-stock-synthesis/stock-synthesis/releases/latest). Simple is a working SS3 model that runs in less than three minutes and should allow you to experiment with SS3 workflows without having to worry about the model’s contents. +To follow along, we recommend downloading the [simple example](https://github.com/nmfs-ost/ss3-user-examples/tree/main/model_files/simple) ([Instructions for downloading](https://github.com/nmfs-ost/ss3-user-examples#how-to-download)) and the [latest release of SS3](https://github.com/nmfs-ost3/ss3-source-code/releases/latest). Simple is a working SS3 model that runs in less than three minutes and should allow you to experiment with SS3 workflows without having to worry about the model’s contents. By the end of using this guide, you should: @@ -68,13 +68,13 @@ Many output text files are created during a model run. The most useful output fi + **r4ss**: An R package to plot SS3 model results and manipulate SS3 input and output files. Available at: https://github.com/r4ss/r4ss -+ **SSI**: Stock Synthesis Interface (i.e., the SS3 GUI). The [latest version of SSI](https://github.com/nmfs-stock-synthesis/ssi/releases/latest) can be downloaded from GitHub. SSI can be used to edit, save, run, and visualize model inputs and outputs. Note that SSI is not maintained for Stock Synthesis versions after v.3.30.21. ++ **SSI**: Stock Synthesis Interface (i.e., the SS3 GUI). The [latest version of SSI](https://github.com/nmfs-ost/ssi/releases/latest) can be downloaded from GitHub. SSI can be used to edit, save, run, and visualize model inputs and outputs. Note that SSI is not maintained for Stock Synthesis versions after v.3.30.21. + **Stock Assessment Continuum Tool**: Available through github at https://github.com/shcaba/SS-DL-tool, the Stock Assessment Continuum Tool (previously known as the Stock Synthesis Data-limited Tool) is a Shiny-based application that provides an interface to upload catch time-series, age composition, length composition, and abundance index data and define model options within the application, which then writes the Stock Synthesis input files. # Running SS3 -SS3 is typically run through the command line (although it can also be run indirctly via the commandline through an R console). We will introduce the one folder approach, where SS3 is in the same folder as the model files. Other possible approaches to running SS3 include, which are detailed in the ["Running Stock Synthesis" section of the user manual](https://nmfs-stock-synthesis.github.io/doc/SS330_User_Manual.html#sec:RunningSS3). +SS3 is typically run through the command line (although it can also be run indirctly via the commandline through an R console). We will introduce the one folder approach, where SS3 is in the same folder as the model files. Other possible approaches to running SS3 include, which are detailed in the ["Running Stock Synthesis" section of the user manual](https://nmfs-ost.github.io/ss3-doc/SS330_User_Manual.html#sec:RunningSS3). ## The one folder approach and demonstration of an SS3 model run @@ -115,7 +115,7 @@ SS3 always opens and reads files in the same order (starter.ss, data file, fore After reading, SS3 proceeds immediately to pre-processing the data and creating internal parameter labels. As SS3 executes, it continues to write debugging output to echoinput.sso and warnings to warnings.sso. -SS3 next goes to the procedure section where iterative parameter changes are made by ADMB to minimize the negative log likelihood. When ADMB achieves convergence, control passes to the sd_phase for calculation of parameter variance (unless `–nohess` option is specified; See [command line options](#options)). After the sd_phase, SS3 proceeds to the benchmark and forecast code section and then to final reporting. Output files containing results are typically written to the directory in which the model was run from (except when using [this special subfolder option](https://nmfs-stock-synthesis.github.io/doc/SS330_User_Manual.html#optional-output-subfolders)). +SS3 next goes to the procedure section where iterative parameter changes are made by ADMB to minimize the negative log likelihood. When ADMB achieves convergence, control passes to the sd_phase for calculation of parameter variance (unless `–nohess` option is specified; See [command line options](#options)). After the sd_phase, SS3 proceeds to the benchmark and forecast code section and then to final reporting. Output files containing results are typically written to the directory in which the model was run from (except when using [this special subfolder option](https://nmfs-ost.github.io/ss3-doc/SS330_User_Manual.html#optional-output-subfolders)). When the run completes, SS3 shows `!! Run has completed !!` and the number of warnings: @@ -126,7 +126,7 @@ Examine warnings.sso for issues and suggestions, regardless of if the run comple ### Examine the output -**.ss_new files** are generated if a model run completes. For more information on the .ss_new files, see the ["Output Files" section of the SS3 user manual](https://nmfs-stock-synthesis.github.io/doc/SS330_User_Manual.html#output-files). +**.ss_new files** are generated if a model run completes. For more information on the .ss_new files, see the ["Output Files" section of the SS3 user manual](https://nmfs-ost.github.io/ss3-doc/SS330_User_Manual.html#output-files). **ss_summary.sso** files are included with the examples on vlab so that you can compare it with the `ss_summary.sso` file generated by your model run. You should see similar if not exactly the same values for the likelihood and parameter values if using the same version of SS3. @@ -153,7 +153,7 @@ Using the ss.par file is helpful when you want to use different initial values w ## Using wtatage.ss -As stated in the manual, SS3 has the capability to read empirical body weight at age for the population and each fleet, in lieu of generating these weights internally from the growth parameters, weight-at-length, and size-selectivity. Please see the [Empirical Weight-at-Age (wtatage.ss) section of the SS3 user manual](https://nmfs-stock-synthesis.github.io/doc/SS330_User_Manual.html#WAA) for more information on using wtatage.ss with a model. There is also a [weight at age SS3 example model available](https://github.com/nmfs-stock-synthesis/user-examples/tree/main/model_files/empirical_wtatage_and_age_selex) if you would like to try using this feature without having to build your own model. +As stated in the manual, SS3 has the capability to read empirical body weight at age for the population and each fleet, in lieu of generating these weights internally from the growth parameters, weight-at-length, and size-selectivity. Please see the [Empirical Weight-at-Age (wtatage.ss) section of the SS3 user manual](https://nmfs-ost.github.io/ss3-doc/SS330_User_Manual.html#WAA) for more information on using wtatage.ss with a model. There is also a [weight at age SS3 example model available](https://github.com/nmfs-ost/ss3-user-examples/tree/main/model_files/empirical_wtatage_and_age_selex) if you would like to try using this feature without having to build your own model. # Plotting results and basic troubleshooting @@ -176,15 +176,15 @@ Here are some basic checks for when SS3 does not run: + Check that starter.ss references the correct names of the control and data files. + If SS3 starts to read files and then crashes, check warnings.sso and echoinput.sso. The warnings.sso will reveal potential issues with the model, while echoinput.sso will show how far SS3 was able to run. Work backwards from the bottom of echoinput.sso, looking for where SS3 stopped and if the inputs are being read corectly or not. -For further information on troubleshooting, please refer to the SS3 User Manual [“Running Stock Synthesis” subsections](https://nmfs-stock-synthesis.github.io/doc/SS330_User_Manual.html#sec:RunningSS3), especially [“Re-Starting a Run”](https://nmfs-stock-synthesis.github.io/doc/SS330_User_Manual.html#re-starting-a-run) and [“Debugging Tips”](https://nmfs-stock-synthesis.github.io/doc/SS330_User_Manual.html#debugging-tips). +For further information on troubleshooting, please refer to the SS3 User Manual [“Running Stock Synthesis” subsections](https://nmfs-ost.github.io/ss3-doc/SS330_User_Manual.html#sec:RunningSS3), especially [“Re-Starting a Run”](https://nmfs-ost.github.io/ss3-doc/SS330_User_Manual.html#re-starting-a-run) and [“Debugging Tips”](https://nmfs-ost.github.io/ss3-doc/SS330_User_Manual.html#debugging-tips). # Where to get additional help -+ Post to the Stock Synthesis [discussion boards on GitHub](https://github.com/nmfs-stock-synthesis/stock-synthesis/discussions) ++ Post to the Stock Synthesis [discussion boards on GitHub](https://github.com/nmfs-ost/ss3-source-code/discussions) + The [SS3 vlab website](https://vlab.noaa.gov/web/stock-synthesis) resources, including the SS3 user manual and the SSI user guide + Post questions to the [forums](https://vlab.noaa.gov/web/stock-synthesis/public-forums) + Email questions to nmfs.stock.synthesis@noaa.gov -+ Report bugs or request features using the [Stock Synthesis issue tracker](https://github.com/nmfs-stock-synthesis/stock-synthesis/issues) ++ Report bugs or request features using the [Stock Synthesis issue tracker](https://github.com/nmfs-ost/ss3-source-code/issues) + [Fisheries Research special issue (vol. 142) on Stock Synthesis](https://www.sciencedirect.com/journal/fisheries-research/vol/142/suppl/C) + [Center for the Advancement of Population Assessment Methodology (CAPAM)](http://www.capamresearch.org/) provides information about good practices in stock assessment diff --git a/User_Guides/ss3_model_tips/ss3_model_tips.Rmd b/User_Guides/ss3_model_tips/ss3_model_tips.Rmd index 2d2b98b6..31959b68 100644 --- a/User_Guides/ss3_model_tips/ss3_model_tips.Rmd +++ b/User_Guides/ss3_model_tips/ss3_model_tips.Rmd @@ -19,7 +19,7 @@ knitr::opts_chunk$set(echo = FALSE) The developing your first SS3 model guide teaches users how to develop a basic Stock Synthesis model. We assume that these users have had previous population dynamics modeling experience and already understand how to run an existing SS3 model. -If you are a new SS3 user who is not yet comfortable running an SS3 model, we suggest trying to run an example working model using advice in the [Getting Started guide](https://nmfs-stock-synthesis.github.io/doc/Getting_Started_SS3.html) before attempting to develop and run your own model as outlined here. +If you are a new SS3 user who is not yet comfortable running an SS3 model, we suggest trying to run an example working model using advice in the [Getting Started guide](https://nmfs-ost.github.io/ss3-doc/Getting_Started_SS3.html) before attempting to develop and run your own model as outlined here. By the end of using this guide, you should be able to: @@ -32,12 +32,12 @@ By the end of using this guide, you should be able to: There are many potential workflows for developing a new SS3 model, but a common technique is to start with an existing model and change it in a piece-wise fashion. The basic technique is: -1. Find an existing working model (perhaps one of the SS3 example models available in the [user-examples repository](https://github.com/nmfs-stock-synthesis/user-examples) or perhaps a model more similar in form to the model you plan to create). +1. Find an existing working model (perhaps one of the SS3 example models available in the [ss3-user-examples repository](https://github.com/nmfs-ost/ss3-user-examples) or perhaps a model more similar in form to the model you plan to create). 2. Edit portions of the model and try running as you go to check that your inputs can be read correctly by SS3 and make logical sense (tip: use options ```-stopph 0 -nohess``` to reduce run time with each iteration of checking inputs by not estimating anything and not inverting the hessian). Some commonly used tools for editing the SS3 input files are: -1. [**Stock Synthesis Interface (SSI; the SS3 GUI)**](https://github.com/nmfs-stock-synthesis/ssi). The SSI allows you to read in a model, performs some checks to ensure valid inputs, make modifications to the model, and offers visualizations of inputs. You can also run models from SSI. Note that SSI is not maintained for Stock Synthesis versions after v.3.30.21. +1. [**Stock Synthesis Interface (SSI; the SS3 GUI)**](https://github.com/nmfs-ost/ssi). The SSI allows you to read in a model, performs some checks to ensure valid inputs, make modifications to the model, and offers visualizations of inputs. You can also run models from SSI. Note that SSI is not maintained for Stock Synthesis versions after v.3.30.21. 2. **Your favorite text editor**. 3. **The ```SS_read*``` and ```SS_write*``` functions in the R package [r4ss](https://github.com/r4ss/r4ss)**. These functions allow you to read in SS3 input files to R, manipulate them from within R, then write them out to a file. The [r4ss vignette](https://r4ss.github.io/r4ss/vignettes/r4ss-intro-vignette.html#scripting-stock-synthesis-workflows-with-r4ss) demonstrates how to use these functions 4. **Stock Assessment Continuum Tool**. Available through github at https://github.com/shcaba/SS-DL-tool. @@ -46,11 +46,11 @@ Some commonly used tools for editing the SS3 input files are: SS3 has a rich set of features. Some required inputs are conditional on other inputs, so it is important to be mindful that changing an option might result in SS3 expecting a different number of values in the input files than it did previously. Most of the time, these conditional inputs are read right after the option. -The [SS3 user manual](https://github.com/nmfs-stock-synthesis/doc/releases) can be used as a guide to help you edit your model. Conditional inputs are noted in the manual. The SSI can also help guide you through changes in model inputs required as you select different SS3 model options. +The [SS3 user manual](https://github.com/nmfs-ost/ss3-doc/releases) can be used as a guide to help you edit your model. Conditional inputs are noted in the manual. The SSI can also help guide you through changes in model inputs required as you select different SS3 model options. If you are unsure if you got the setup right (e.g., adding the correct number of parameter lines for a chosen catchability setup), try running the model with ```maxphase = 0``` in the starter file and ADMB option ```-nohess``` (or for v.3.30.16 and greater, run the model with command line options ```-stopph 0 -nohess```, no need to change the starter file). If the model run completes, you can compare the **control.ss_new** file and the first data set in **data.ss_new** to your SS3 input files to make sure SS3 interpreted the values as intended. If the run exits before completion, you can look at **warning.sso** and **echoinput.sso** for clues as to what was wrong with your setup. -For additional help with model specification, please post your questions in the GitHub [discussions](https://github.com/nmfs-stock-synthesis/stock-synthesis/discussions) or on the vlab [forums](https://vlab.noaa.gov/web/stock-synthesis/public-forums) (for registered SS3 users) or send an email to the SS3 team at NMFS.Stock.Synthesis@noaa.gov. +For additional help with model specification, please post your questions in the GitHub [discussions](https://github.com/nmfs-ost/ss3-source-code/discussions) or on the vlab [forums](https://vlab.noaa.gov/web/stock-synthesis/public-forums) (for registered SS3 users) or send an email to the SS3 team at NMFS.Stock.Synthesis@noaa.gov. # Phases in SS3 and ADMB @@ -161,7 +161,7 @@ For a fixed value of sigmaR, a section of the output will provide diagnostics to # Where to get additional help -+ Post questions in the GitHub [discussions](https://github.com/nmfs-stock-synthesis/stock-synthesis/discussions) or to the [forums](https://vlab.noaa.gov/web/stock-synthesis/public-forums) or send an emails to the team at NMFS.Stock.Synthesis@noaa.gov for assistance. ++ Post questions in the GitHub [discussions](https://github.com/nmfs-ost/ss3-source-code/discussions) or to the [forums](https://vlab.noaa.gov/web/stock-synthesis/public-forums) or send an emails to the team at NMFS.Stock.Synthesis@noaa.gov for assistance. + [Carvalho et al. 2021](https://doi.org/10.1016/j.fishres.2021.105959) contains guidance on developing stock assessments. diff --git a/docs/SS330_User_Manual.html b/docs/SS330_User_Manual.html index 40c80453..508823ca 100644 --- a/docs/SS330_User_Manual.html +++ b/docs/SS330_User_Manual.html @@ -5,6 +5,6 @@ -

Redirecting to https://nmfs-stock-synthesis.github.io/doc/SS330_User_Manual_release.html

+

Redirecting to https://nmfs-ost.github.io/ss3-doc/SS330_User_Manual_release.html

\ No newline at end of file diff --git a/docs/SS330_User_Manual_release.html b/docs/SS330_User_Manual_release.html index 6c2622d8..5432f4ca 100644 --- a/docs/SS330_User_Manual_release.html +++ b/docs/SS330_User_Manual_release.html @@ -1,10 +1,10 @@
- Manual home page - nmfs-stock-synthesis/doc - Report an issue - Table of contents + Manual home page + nmfs-ost/ss3-doc + Report an issue + Table of contents
@@ -249,9 +249,9 @@

1

Assessment models typically assimilate annual catches, data on fish abundance from diverse surveys and fishery sources, and biological information regarding fish body size and proportions at age. A suite of models is available depending on the degree of data availability and unique characteristics of the fish population or its fishery. Where feasible, environmental time series are used as indicators of changes in population or observation processes, especially to improve the accuracy of the projections of abundance and sustainable catch into the future. Such linkages are based principally on correlations given the challenge of conducting field observations on an appropriate scale. The frontier of model development is in the rapid estimation of parameters to include random temporal effects, in the simultaneous modeling of a suite of interacting species, and in the explicit treatment of the spatial distribution of the population.

Assessment models are loosely coupled to other models. For example, an ocean-temperature or circulation model or benthic-habitat map may be directly included in the pre-processing of the fish abundance survey. A time series of a derived ocean factor, like the North Atlantic Oscillation, can be included as an indicator of a change in a population process. Output of a multi-decadal time series of derived fish abundance can be an input to ecosystem and economic models to better understand cumulative impacts and benefits.

Stock Synthesis is an age- and size-structured assessment model in the class of models termed integrated analysis models. Stock Synthesis has evolved since its initial inception in order to model a wide range of fish populations and dynamics. The most recent major revision to Stock Synthesis occurred in 2016, when v.3.30 was introduced. This new version of Stock Synthesis required major revisions to the input files relative to earlier versions (see the Converting Files section for more information). The acronym for Stock Synthesis has evolved over time with earlier versions being referred to as SS2 (Stock Synthesis v.2.xx) and older versions as SS3 (Stock Synthesis v.3.xx).

-

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 (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 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 Methot and Wetzel (2013). 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 GitHub with older archived versions also available online at 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 GitHub.

-

Additional guidance for new users can be found online in the Getting Started Tutorial and on the Stock Synthesis GitHub page.

+

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 (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 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 Methot and Wetzel (2013). 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 GitHub with older archived versions also available online at 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 GitHub.

+

Additional guidance for new users can be found online in the Getting Started Tutorial and on the Stock Synthesis GitHub page.

1.1 How To Cite

Please cite Stock Synthesis as:

Methot, R.D. and Wetzel, C.R. (2013). Stock Synthesis: A biological and statistical framework for fish stock assessment and fishery management. Fisheries Research, 142: 86-99. https://doi.org/10.1016/j.fishres.2012.10.012

@@ -301,7 +301,7 @@

4 Converting Files from Stock Synthesis v.3.24

-

Converting files from version 3.24 to version 3.30 can be performed by using the program ss_trans.exe. This executable takes v.3.24 files as input and will output v.3.30 input and output files. SS_trans executables are available for v.3.30.01 - v.3.30.17. The transitional executable was phased out with v.3.30.18. If a model needs to be converted from v.3.24 to a recent version, one should use the v.3.30.17 ss_trans.exe available from the v.3.30.17 release page on GitHub to convert the files and then any additional adjustments needed between v.3.30.17 and newer versions should be done by hand.

+

Converting files from version 3.24 to version 3.30 can be performed by using the program ss_trans.exe. This executable takes v.3.24 files as input and will output v.3.30 input and output files. SS_trans executables are available for v.3.30.01 - v.3.30.17. The transitional executable was phased out with v.3.30.18. If a model needs to be converted from v.3.24 to a recent version, one should use the v.3.30.17 ss_trans.exe available from the v.3.30.17 release page on GitHub to convert the files and then any additional adjustments needed between v.3.30.17 and newer versions should be done by hand.

The following file structure and steps are recommended for converting model files:

  1. Create “transition” folder. Place the 4 main model files (control, data, starter, and forecast) from version SS3 v.3.24 within the transition folder along with the SS3 transition executable (ss_trans.exe). One tip is to use the control.ss_new from the SS3 v.3.24 estimated model rather than the control.ss file which will set all parameter values at the previous estimated maximum likelihood estimated (MLE) parameters. Run the transition executable with phase = 0 within the starter file with the read par file turned off (option 0).

    2. @@ -3517,7 +3517,7 @@

    7

    In principle, one could have year or laboratory specific matrices for ageing error. For each matrix, enter a vector with mean age for each true age; if there is no ageing bias, then set age equal to true age + 0.5. Alternatively, -1 value for mean age means to set it equal to true age plus 0.5. The addition of +0.5 is needed so that fish will get assigned to the intended integer age. The length of the input vector is equal to the population maximum age plus one (0-max age), with the first entry being for age 0 fish and the last for fish of population maximum age even if the maximum age bin for the data is lower than the population maximum age. The following line is a a vector with the standard deviation of age for each true age with a normal distribution assumption.

    The model is able to create one ageing error matrix from parameters, rather than from an input vector. The range of conditions in which this new feature will perform well has not been evaluated, so it should be considered as a preliminary implementation and subject to modification. To invoke this option, for the selected ageing error vector, set the standard deviation of ageing error to a negative value for age 0. This will cause creation of an ageing error matrix from parameters and any age or size-at-age data that specify use of this age error pattern will use this matrix. Then in the control file, add a full parameter line below the cohort growth deviation parameter (or the movement parameter lines if used) in the mortality growth parameter section. These parameters are described in the control file section of this manual.

    -

    Code for ageing error calculation can be found in SS_miscfxn.tpl, search for function “get_age_age” or “SS_Label_Function 45.”

    +

    Code for ageing error calculation can be found in SS_miscfxn.tpl, search for function “get_age_age” or “SS_Label_Function 45.”

    7.16.3 Age Composition Specification

    If age data are included in the model, the following set-up is required, similar to the length data section.

    @@ -5801,7 +5801,7 @@

    SS_miscfxn.tpl file, search for function “get_age_age” or “SS_Label_Function 45.”

    +

    Code for implementing vectors of mean age and standard deviation of age can be located online within the SS_miscfxn.tpl file, search for function “get_age_age” or “SS_Label_Function 45.”

    8.5.8 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.

    @@ -6618,7 +6618,7 @@

    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 fastest closer to the unfished equilibrium (convex decreasing survival).

    The steepness (\(h\)) of the spawner-recruit curve (defined as recruitment relative to R0 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: \[h = 0.2e^{z_0z_{\text{frac}}(1-0.2^\beta)}<0.2e^{z_0}=\frac{1}{5S_0}=\frac{SB_0}{5R_0}\]

    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 SS_recruit.tpl, search for “SS_Label_43.3.7 survival based.”

    +

    Code for the survival based recruitment can be found in SS_recruit.tpl, search for “SS_Label_43.3.7 survival based.”

    8.6.1.5 Shepherd


    The Shepherd stock recruit curve is calculated as: \[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)\] where c is the shape parameter for the stock recruitment curve, and \(h_{adj}\) is the transformed steepness parameter defined as: \[h_{adj}=0.2+\bigg(\frac{h-0.2}{0.8}\bigg)\bigg(\frac{1}{5*0.2^c}-0.2\bigg)\]

    @@ -8185,7 +8185,7 @@

    SS_selex.tpl, search for “SS_Label_Info_22.7.17.”

    +

    Code for implementing random walk selectivity can be found in SS_selex.tpl, search for “SS_Label_Info_22.7.17.”

    8.9.3.9 Pattern 22 (size) - Double Normal with Plateau


    @@ -8287,7 +8287,7 @@

    The overall selectivity curve is scaled to have a peak equal to 1.0.

  2. Last node cannot be at the max population length bin.

    3. -

    Code for implementing cubic spline selectivity can be found in SS_selex.tpl, search for “SS_Label_Info_22.7.27.”

    +

    Code for implementing cubic spline selectivity can be found in 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 set-up 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 problem.

    Auto-Generation of Cubic Spline Control File Set-Up: 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:

      @@ -10145,7 +10145,7 @@

      11

      To check if SS3 is in your path for Windows, open a DOS prompt (either Command Prompt or Powershell should work) and type SS3 -? and hit enter. If the prompt returns a message like SS3 is not recognized..., then SS3 is not in your path (assuming the SS3 executable is called SS3.exe).

      To add the SS3 binary file to your path, follow these steps:

        -

      1. Find the correct version of the SS3.exe binary on your computer (or download from the SS3 releases).

        2. +

      2. Find the correct version of the SS3.exe binary on your computer (or download from the SS3 releases).

      3. Move to and note the folder location. E.g., C:/SS3/

      4. Click on the start menu and type environment

      5. Choose Edit environment variables for your account under Control Panel

        6. @@ -11071,7 +11071,7 @@

        \(P_{block,-1}\) = Final parameter value in the previous time block

    -

    Code for the deviation link can be found in SS_timevaryparm.tpl, search for “SS_Label_Info_14.3.”

    +

    Code for the deviation link can be found in SS_timevaryparm.tpl, search for “SS_Label_Info_14.3.”

    14.1.3 Specification of Time-Varying Parameters: Short Parameter Lines

    If a time-varying specification set up in the long parameter lines for a particular section requires additional parameters, short parameter lines need to be created following the long parameter lines for the section (unless autogeneration is used, which creates short parameter lines in control.ss_new upon running the model). The number of parameter lines required depends on the time-varying parameter specification.

    For example, if two parameters were specified to have environmental linkages in the MG parameter section, below the MG parameters would be two parameter lines (when not auto-generating these lines), which is an environmental linkage parameter for each time-varying base parameter:

    diff --git a/docs/index.md b/docs/index.md index df2b98ad..9eee4ae1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ * [Getting Started Tutorial](Getting_Started_SS3.html) * [Building Your First SS3 Model Tutorial](ss3_model_tips.html) * [Current User Manual (html)](SS330_User_Manual_release.html) -* [Current User Manual (pdf)](https://github.com/nmfs-stock-synthesis/stock-synthesis/releases/download/v3.30.22/SS330_User_Manual.pdf) +* [Current User Manual (pdf)](https://github.com/nmfs-ost/ss3-source-code/releases/download/v3.30.22/SS330_User_Manual.pdf) ## How to Cite the Stock Synthesis User Manual diff --git a/html_usermanual_snippets.html b/html_usermanual_snippets.html index 4d0b1b1f..78a62450 100644 --- a/html_usermanual_snippets.html +++ b/html_usermanual_snippets.html @@ -3,10 +3,10 @@
    - Manual home page - nmfs-stock-synthesis/doc - Report an issue - Table of contents + Manual home page + nmfs-ost/ss3-doc + Report an issue + Table of contents
    diff --git a/tv_parameter_description.tex b/tv_parameter_description.tex index df295b8b..e46d914f 100644 --- a/tv_parameter_description.tex +++ b/tv_parameter_description.tex @@ -118,7 +118,7 @@ \subsubsection{Specification of Time-Varying Parameters: Long Parameter Lines} \end{itemize} -Code for the deviation link can be found in \href{https://github.com/nmfs-stock-synthesis/stock-synthesis/blob/main/SS_timevaryparm.tpl}{SS\_timevaryparm.tpl}, search for ``SS\_Label\_Info\_14.3''. +Code for the deviation link can be found in \href{https://github.com/nmfs-ost/ss3-source-code/blob/main/SS_timevaryparm.tpl}{SS\_timevaryparm.tpl}, search for ``SS\_Label\_Info\_14.3''. \subsubsection{Specification of Time-Varying Parameters: Short Parameter Lines}