In some cases you may wish to adapt your own SS3 model to work with the ss3sim package. This is possible but may be difficult because the functions in ss3sim were developed to work with the existing model setups and a model with a different structure may cause errors in these functions. This stems from the high flexibility of SS3, allowing for more complex model setups than those used while developing ss3sim.
For instance, sample_index() does not currently have the capability to handle more than one season. Given the many options available in SS3, it is extremely difficult to write auxiliary functions that will interact reliably with all combinations of these options. For this reason, we recommend that users strongly consider trying to modify an existing model rather than creating a new one. It is likely that the ss3sim functions will need to be modified in some way in the process, so the user should be familiar with both SS3 and R.
The main purpose of the OM (operating model) is to generate data files that can be read into the EM (estimation model). Thus the user needs to setup the .dat files in the OM such that they conform to the structure needed by the EM. Two key examples are with survey and age/length composition data. For the indices of abundance (CPUE and scientific survey) the OM .dat file will determine which years are available to the sampling function sample_index(), so if a year is desired in the EM it needs to be in the OM. In practice it may be easiest to just include all years in the OM if surveys will be dynamic (i.e. changing years between scenarios), or if it will be fixed for all scenarios to set it to match the EM exactly.
Similarly, with age/length compositions, the OM .dat file will determine which years and bins are available to the sampling functions sample_agecomp() and sample_lcomp(). If dynamic binning is to be used, the user should setup the .dat file so that all desired combinations of bins are possible (see the section in the Introduction vignette on dynamic binning for more details). Specifically, the user must specify small enough OM .ctl bins (no smaller than the population bin specified in the appropriate section in the OM .dat file) so that they can easily be re-binned. Alternatively, if composition data is not to be explored in the simulation then the user can just set the OM .dat file to match the desired input for the EM .dat.
For those users who choose to create a new ss3sim model setup, we outline the steps to take an existing SS3 model and modify it to work with the ss3sim package. First, we cover setting up an operating model and then we cover setting up an estimation model.
The first step is to run the assessment model to make sure the model runs and estimates parameters as desired. The .par file generated will be used in the OM. We recommend opening a command window inside your OM and EM folder to help test whether the model still runs at many points along the process. After turning parameter estimation off in the starter file (see below), the model can be checked by running ss3_24o_safe -nohess to make sure the input files are read in properly and the model writes the files. Use the .ss_new files produced as a starting point so that the comments match the instructions below.
You will see an error by ADMB that it cannot find the data file because we have specified a different file in the starter file. You can safely ignore this error.
# Do West Coast gfish rebuilder output (0/1) is set to 1, set it to 0. Comment out lines below specifying the years of the rebuilder.Delete the starter.ss file and rename starter.ss_new to starter.ss. Modify this new file.
Turn off parameter estimation by changing # Turn off estimation for parameters entering after this phase to 0.
Use the .par file to initialize model parameters. To do so change # 0=use init values in Starter file to 1. Parameter values specified in the .ctl file will now be ignored.
Generate detailed report files (containing age-structure information) by setting # detailed age-structured reports in REPORT.SSO to 1.
Generate data by setting # Number of datafiles to produce to 3. If X=1 it only generates the original data If X=2 it generates the original data and the expected value data (based on model specification) If X>=3 it generates all the above and X-2 bootstrapped data sets
Turn off parameter jittering by setting # jitter initial parm value by this fraction to 0. Jitter is used, among other things, to test for convergence to the same solution when starting from alternative initial values; however, the OM is used here as the truth, so jittering is not needed.
Turn off retrospective analyses by setting # retrospective year relative to end year to 0. To analyze the data for retrospective patterns, use the R case file.
Specify how catch is reported by setting # F_report_units to 1 if catch is reported in biomass or 2 if catch is reported in numbers. Additionally, comment out the next line, #_min and max age over which average F will be calculated, by removing all characters prior to the hash symbol.
Implement catches using instantaneous fishing mortality by changing # F_report_basis to 0.
Delete the <modelname>.ctl file and rename control.ss_new to om.ctl. Modify this new file.
Specify all environmental deviates on biological parameters to be unconstrained by bounds by setting #_env/block/dev_adjust_method to 1. If the method is set to 2, parameters adjusted using environmental covariate inputs will be adjusted using a logistic transformation to ensure that the adjusted parameter will stay within the bounds of the base parameter. If it exists and is not already commented out, comment out the second line entitled #_env/block/dev_adjust_method underneath the section which specifies selectivity parameters. If time-varying selectivity parameters are added using the change_tv() function, this line will be modified by the same function.
Turn on recruitment deviations by specifying #do_recdev to 1. Using the next two lines, specify the use of recruitment deviations to begin and end with the start and end years of the model.
Turn on additional advanced options for the recruitment deviations by specifying # (0/1) to read 13 advanced options to 1.
Set #_recdev_early_start to 0 so that the model will use the # first year of main recr_devs.
Set #_lambda for Fcast_rec_like occurring before endyr+1 to 1. This lambda is for the log likelihood of the forecast recruitment deviations that occur before the first year of forecasting. Values larger than one accommodate noisy data at the end of the time series.
Recruitment is log-normally distributed in SS. If inputting a normally distributed recruitment deviations specify #_max_bias_adj_in_MPD to -1 so that SS performs the bias correction for you. If inputting bias corrected normal recruitment deviation, specify it at 0. Either method will lead to the same end result.
Use any negative value in line # F ballpark year, to disable the use of a ballpark year to determine fishing mortality levels.
Specify # F_Method to 2, which facilitates the use of a vector of instantaneous fishing mortality levels. The max harvest rate in the subsequent line will depend upon the fishing mortality levels in your simulation. Following the max harvest rate, specify a line with three value separated by spaces. The first value is the overall start F value, followed by the phase. The last value is the number of inputs. Set the number of inputs to 1, because the actual fishing mortality trajectory will be specified in the .dat file. Next, specify a single line with six values, separated by spaces, where the values correspond to fleet number, start year, season, fishing mortality level, the standard error of the fishing mortality level, and a negative phase value. E.g 1 2000 1 0 0.01 -1
Set #_Variance_adjustments_to_input_values to 0. Comment out any lines underneath referring to variance adjustments.
Set # number of changes to make to default Lambdas to 0. Comment out any lines with default lambda changes below.
If needed, change the specification of the .ctl using the functions available in the ss3sim package. E.g change_growth, change_sel.
Delete the <modelname>.dat file and rename data.ss_new to om.dat. Modify this new file.
Specify the start and end year for the simulation by modifying #_styr and #_endyr. Years can be specified as a number line (i.e. 1, 2, 3, …) or as actual years (i.e. 1999, 2000, 2001, …).
Specify the names for each fleet in an uncommented line after the line #_N_areas. Names must be separated by a % with no spaces. It is these names which you will use in the plain text case files to specify and change characteristics of each fleet throughout the simulation. E.g. Fishery%Survey1%Survey2
Specify the number of mean body weight observations across all selected sizes and ages to be specific to measured fish by setting #_N_meanbodywt to 0. Subsequently, specify 1 under #_DF_for_meanbodywt_T-distribution_like - this is the degree of freedom for the Student’s T distribution used to evaluated the mean body weight deviations in the following line. The degrees of freedom must be specified even if there are zero mean body weight observations.
Set the length bin method to 1 or 2 in the line labelled # length bin method. Using a value of 1, the bins refer to the data bins (specified later). Using a value of 2 instructs SS to generate the bin widths from a user specified minimum and maximum value. In the following three lines, specify the bin width for population size composition data; the minimum size, or the lower edge of the first bin and size at age zero; and the maximum size, or lower edge of the last bin. The length data bins MUST be wider than the population bin, but the boundaries do not have to align.
Specify #_comp_tail_compression to any negative value to turn off tail compression.
Specify #_add_to_comp to a very small number E.g 1e-005. This specifies the value that will be added to each composition (age and length) data bins.
Set the length bin range method for the age composition data (used when the conditional age at length data exists) to 1, 2 or 3 in the line #_Lbin_method depending on the data you have or the purpose of the study.
Unlike the OM, the EM needs to be a valid SS3 model setup and run to achieve maximum likelihood estimates (and possibly standard errors). Thus the OM needs to be adapted to create a new EM.
Change the names of the .dat and .ctl files to your chosen naming scheme.
Specify the model to use parameter values found in the .ctl file, by changing # 0=use init values in control file; 1=use ss3.par to 0.
Turn on parameter estimation by changing # Turn off estimation for parameters entering after this phase to a value larger than the max phase specified in the .ctl file.
Set the phases of the parameters to positive or negative value to inform SS to estimate or fix the parameters, respectively. (TODO can we give a few words of guidance about which parameters may want to be estimated by default? -SA)
Set the #_recdev phase to a positive value to estimate yearly recruitment deviations.
If using bias adjustment set #_recdev_early_phase to a positive value. Estimates for the years and maximum bias adjustment can initially be inputted with approximations or use the bias adjustment function within ss3sim to find appropriate values for the base case EM and input them in the appropriate lines. (TODO can we provide guidance on how this phase should relate to recdev phase?)
Specify # F_Method to 3, which allows the model to use catches to estimate appropriate fishing mortality levels. The max harvest rate in the subsequent line will depend upon the fishing mortality levels in your simulation. An additional line must be inserted after the maximum harvest rate to specify the number of iterations used in the hybrid method from 3 to 7.
If it exists and is not already commented out, comment out the second line entitled #_env/block/dev_adjust_method underneath the section which specifies selectivity parameters. If time-varying selectivity parameters are added using the change_tv() function, this line will be modified by the same function.
Use the functions in the ss3sim package to change the estimation specification in the EM. E.g. change_e
You can delete the .dat file from the EM model setup. The data.ss_new files produced when executing the OM contain the expected values of the OM population dynamics. The data the EM model is fit to needs to be sampled with observation error from these expected values in order to mimic the random sampling process done with real fisheries data. The ss3sim package provides three functions which carry out the random sampling process and generate .dat files to be used in the EM. See the Introduction vignette section for more details.
After completing the above steps run the model manually for a single iteration. Verify that the data are read in correctly and expected values of the population dynamics are written to the .dat files (and sensical). Verify that the EM loads the data properly and the objective function value (negative log-likelihood) is sensible. If it works correctly, try running deterministic cases on the model (see the Introduction vignette) and further verify that ss3sim functions that modify the EM (e.g., change_e) act correctly on the model setup. The help files for the functions demonstrate how to use the functions to test models. Note that the OM will not be a valid SS3 model in the sense that ADMB cannot run and produce maximum likelihood estimates of parameters; it is intended to only be run for one iteration to generate the population dynamics using values specified in the input files. It is possible that some of the functions will not work perfectly with the new model setups. In this case, it may be necessary to modify the ss3sim functions to be compatible with the new OM and EM.