---
title: "Creating new ss3sim model setups"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    toc: true
    number_sections: true
    fig_caption: true
bibliography: refs.bib
vignette: >
  %\VignetteIndexEntry{Creating new ss3sim model setups}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

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](modifying-models.html).

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](#om-setup) folders should have the following files:

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

[EM](#em-setup) 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 {#om-setup}

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](introduction.html#change-data) 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](introduction.html)),
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.

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

1. 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`).

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

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

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

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

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

1.  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 {#em-setup}

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](introduction.html#deterministic)) 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. 
