03-stock-synthesis.qmd

# Running Stock Synthesis

Note that there's lots more information on the SS3 website: <https://nmfs-ost.github.io/ss3-website> including the User Manual.

## Model setup

1.  **Run the model without estimating anything at first.** The best way to do this is to run as `ss -stopph 0 -nohess` where `stopph` (short for "stop phase" is equivalent to setting the maximum phase in the starter file).

2.  **Make sure you pay attention to any notes or warnings in "warning.sso".** If you don't understand the warnings, find out, but don't just ignore it.

3.  **Debugging models that don't run**. The first place to look is "echoinput.sso". Start at the bottom and scan upwards until things start to look right or start at the top and scan downwards until things start to look wrong. It's often obvious when you have an extra input and things model starts to go awry. Use this information to fix your input files and try again. There are some additional debugging tips in the [Stock Synthesis User Manual](https://nmfs-ost.github.io/ss3-doc/SS330_User_Manual_release.html#debugging-tips). Consider also reading the input files into R using `r4ss::SS_read()` which may help you find mismatched columns or bad values in the inputs.

4.  **Once the model runs, look at the ".ss_new" files.** These files contain rich comments and often better formatting than your own input files. They are also good for debugging, because sometimes a model will run, but the parameter lines are associated with different fleets, or have different roles than you expected. Check the parameter names on the right hand side of "control.ss_new" to make sure everything looks right. You can then either replace your input files with the ".ss_new" files or just copy and paste elements that you want to keep. Note that if you've estimated any parameters, then the initial values in "control.ss_new" have been updated to these estimates.

5.  **Pull in parameter bounds that are way too wide** -- if you aren't anywhere near them during minimization, extremely wide bounds (like -15 to 15 on recruit deviations, or 3 to 31 for log-R0) just slow minimization and may result in poorer convergence properties.

## Model tuning

6.  **Indices are typically tuned via the extra standard deviation parameter.** There are many reasons to expect that the input uncertainty values on indices of abundance are underestimates of the true uncertainty. Estimating an extra uncertainty parameter has worked well in a number of west coast groundfish assessments. However, the 2021 best practices document \[BUT REVISIONS TO THIS IN PREP FOR 2025\] says, "STATs should be cautious to avoid adding variability to an index as a means of resolving model structure issues such as conflicts among data sources. Rather, variability should be added to account for sampling variance underestimating index uncertainty. *STATs should provide a priori reasons for why the index variability input to the model has been underestimated (or underspecified).*" Note that the extra SD parameter should reflect the observed variability in survey indices rather than poor fit to the observed trend in survey indices. Resist adding SD to surveys where there are trends in residuals without evidence of hyperdepletion or hyperstability, in which case a non-linear relationship between indices and stock size is more appropriate.

7.  **Composition data is typically tuned by either iterative Francis weighting or estimating Dirichlet-multinomial parameters.** The McAllister-Ianelli method has not performed as well in simulation testing. See the [data weighting section of the Stock Synthesis Manual](https://nmfs-stock-synthesis.github.io/doc/SS330_User_Manual.html#DataWeight) for more info (Dirichlet-multinomial guidance was updated by Jim Thorson in September 2022). The choice between these two methods often depends on qualitative evaluation of fits to the comp data and index data and how it differs among tuning approaches.

8.  **Discard ratios and mean body weight** These data SHOULD be tuned if they are used in the model, but haven't often done so. In August 2023 the `r4ss::SS_output()` function was augmented to return `$discard_tuning_info` and `$mnwgt_tuning_info` based on code written by Kelli Johnson for the 2019 sablefish assessment. The following description for tuning was provided in the 2019 assessment of sablefish:

    > Added variances for discard rates and mean body weights were set using values calculated iteratively using the RMSE of differences between input and estimated values derived from SS3. Variances were parameterized in terms of standard deviation and coefficient of variation, respectively. 
    

9.  **Think about sigmaR.** This could be an arbitrarily chosen value, freely estimated, or iteratively tuned. [Methot and Taylor (2011)](https://cdnsciencepub.com/doi/10.1139/f2011-092) suggest a way that the tuning could be done. Whatever you choose, put a little thought into it. SigmaR should be greater than the SD of the estimated recruitment deviations. The table `$sigma_R_info` output by `r4ss::SS_output()` provides information on tuning sigmaR.