Creating new ss3sim model setups

In some cases you may wish to adapt your own Stock Synthesis model to work with ss3sim. This is possible but may be difficult. The functions in {ss3sim} were developed to work with the existing model setups, and a model with a different structure may lead to incomprehensible error messages because it is extremely difficult to write auxiliary functions that will interact reliably with all the available options in Stock Synthesis. For this reason, we recommend that users strongly consider trying to modify an existing model rather than creating a new one.

For those users who choose to create a new {ss3sim} model setup, we outline below the steps needed to take an existing Stock Synthesis model and modify it to work with {ss3sim}.

Overall file structure

OM folders should have the following files:

yourOMmodel.ctl
yourOMmodel.dat
starter.ss
forecast.ss

EM folders should have the following files:

yourEMmodel.ctl
starter.ss
forecast.ss

The names of the .ctl and .dat files are not important. The wrapper functions within ss3sim will rename the files when copying them to appropriate folders. These files should be derived from .ss_new files but have the file extensions as shown above. It is important to use .ss_new files so the files have consistent formatting. Many of the functions in this package and {r4ss} depend on that formatting.

Setting up a new operating model

The main purpose of the operating model (OM) is to generate data files that can used for the estimation model (EM). The initial data file stored in the OM folder does not have to contain actual data but it does need to contain enough information for the executable to run. For example, if age-composition data are turned on, then at least one row of age-composition data must be in the file. The actual composition information in this row of data can be any numeric value and does not have to make sense biologically because the compositions will be replaced with expected values and then sampled values. If dynamic binning is desired, the OM data file should have all desired combinations of bins that will be used in the sampled scenarios (see the section in the Introduction vignette on dynamic binning for more details). Specifically, OM bins for the data must be at least as small as the smallest bins desired but not smaller than the population bins so that they can easily be re-binned.

The first step to setting up an OM is to run Stock Synthesis using your original files to make sure the model runs and estimates parameters as desired. Thus, open a command window inside the folder with your original files and run Stock Synthesis. If Stock Synthesis is not in your path (see the Introduction vignette), you will need to have the executable available in this folder. Note that there may be an error message in the command window indicating that ADMB cannot find the data file. ADMB expects a certain name and Stock Synthesis uses a name stored in the starter file. You can safely ignore this error. Once the model is finished running, it will generate a number of files, including .ss_new files. Copy the needed .ss_new files to the OM folder and remove the .ss_new file extension and add the appropriate file extensions. Do the same for the files needed for the EM. Use the .ss_new files produced as a starting point to ensure that your Stock Synthesis input files are properly formatted.

We recommend opening a command window inside your OM and EM folders to test if the model still runs at many points along the process. First, turn parameter estimation off in the OM starter file (see below) and run ss -nohess to make sure the input files are read in properly and the model writes the new input files.

Forecast file modifications

  1. Set # Do West Coast gfish rebuilder output (0/1) to 0.

  2. Optionally, comment out the lines below specifying the years of the rebuilding plan.

Starter file modifications

  1. Turn off parameter estimation by changing # Turn off estimation for parameters entering after this phase to 0.

  2. Use the INIT values in the .ctl file to initialize model parameters for your population. To do so, change # use init values in Starter file to 0. The .par file will be ignored.

  3. Generate detailed report files, containing age-structure information, by setting # detailed age-structured reports in REPORT.SSO to 1.

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

  5. Turn off parameter jittering by setting # jitter initial parm value by this fraction to 0. The OM is used as the truth so jittering is not needed.

  6. Turn off retrospective analyses by setting # retrospective year relative to end year to 0.

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

  8. Implement catches using instantaneous fishing mortality by changing # F_report_basis to 0. Instantaneous fishing mortality is used rather than catches in numbers or biomass to run the OM, which ensures that the resulting catches will be less than the available biomass for every given year. Where, if we allowed users to specify catch in numbers or biomass they might crash the population.

Control file modifications

  1. 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. The logistic transformation ensures 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.

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

  3. Turn on additional advanced options for the recruitment deviations by specifying # (0/1) to read 13 advanced options to 1.

  4. Set #_recdev_early_start to 0 so that the model will use the # first year of main recr_devs.

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

  6. Recruitment is log-normally distributed in Stock Synthesis. If inputting a normally distributed recruitment deviations specify #_max_bias_adj_in_MPD to -1 so that Stock Synthesis performs the bias correction for you. {ss3sim} internally uses bias corrected normal recruitment deviations, unless users specify user_recdevs, which do not need bias correction and users should specify #_max_bias_adj_in_MPD to 0.

  7. Use any negative value in line # F ballpark year, to disable the use of a ballpark year to determine fishing mortality levels.

  8. 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 values 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 change_f will be used to input a vector of fishing mortality levels. 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 1 1 0 0.01 -1.

  9. Remove non-terminator lines in # Input variance adjustments factors or set all elements in the Value column to 0. For example, your file could look like the following:

    # Input variance adjustments factors: 
     #_1=add_to_survey_CV
     #_2=add_to_discard_stddev
     #_3=add_to_bodywt_CV
     #_4=mult_by_lencomp_N
     #_5=mult_by_agecomp_N
     #_6=mult_by_size-at-age_N
     #_7=mult_by_generalized_sizecomp
    #_Factor  Fleet  Value
     -9999   1    0  # terminator
  10. Remove non-terminator lines in #_maxlambdaphase or set all elements in the value column to 0. For example, your file could look like the following:

    1 #_maxlambdaphase
    1 #_sd_offset; must be 1 if any growthCV, sigmaR, or survey extraSD is an estimated parameter
    # read 0 changes to default Lambdas (default value is 1.0)
    # Like_comp codes:  1=surv; 2=disc; 3=mnwt; 4=length; 5=age; 6=SizeFreq; 7=sizeage; 8=catch; 9=init_equ_catch; 
    # 10=recrdev; 11=parm_prior; 12=parm_dev; 13=CrashPen; 14=Morphcomp; 15=Tag-comp; 16=Tag-negbin; 17=F_ballpark; 18=initEQregime
    #like_comp fleet  phase  value  sizefreq_method
    -9999  1  1  1  1  #  terminator
  11. If desired, change the initial, i.e., INIT, values of the growth, selectivity, etc. parameters to specify the dynamics of the OM. In theory, these will not need to be altered because they will be based on what was estimated in your production stock assessment model.

Data file modifications

  1. Specify the start and end year for the simulation by modifying #_StartYr and #_EndYr. Years can be specified as a number line (i.e., 1 and 5) or as actual years (i.e., 2001 and 2005).

  2. Specify the fleet_type, sample_timing, fleet_area (1), units, catch_mult, and fleet name with one row per fleet after #_Nfleets and before #Bycatch_fleet_input_goes_next.

  3. Turn off mean body weight observations by setting #_use meanbodysize_data to 0 because {ss3sim} currently does not have the capability to sample these data.

  4. Set # length bin method to 1 or 2. Using a value of 1, the bins refer to the data bins (specified later). Using a value of 2 instructs Stock Synthesis 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 bins but the boundaries do not have to align.

  5. Turn off #_mintailcomp using any negative value for each fleet.

  6. Specify addtocomp to a very small number for each fleet, e.g., 1e-005. addtocomp represents the amount that is added to each composition (age and length) data bin such that the likelihood is always computable.

  7. Set #_Lbin_method_for_Age_Data for ages (used when the conditional-age-at-length data exists) to 1, 2, or 3 depending on the data you have or the purpose of the study.

Setting up a new estimation model

Unlike the OM, the EM needs to be a valid Stock Synthesis model and be able to successfully estimate parameters and their standard errors using maximum likelihood estimates. Thus, the OM needs to be adapted to create a new EM. The preferred method here is to run create_em() using the newly created OM files.

Testing the new estimation model

After completing the above steps run the models manually one last time. 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 simulations 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 Stock Synthesis 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.