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}.
OM folders should have the following files:
yourOMmodel.ctl
yourOMmodel.dat
starter.ss
forecast.ssEM folders should have the following files:
yourEMmodel.ctl
starter.ss
forecast.ssThe 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.
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.
Set # Do West Coast gfish rebuilder output (0/1) to
0.
Optionally, comment out the lines below specifying the years of the rebuilding plan.
Turn off parameter estimation by changing
# Turn off estimation for parameters entering after this phase
to 0.
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.
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. The OM is used as the truth so jittering is not
needed.
Turn off retrospective analyses by setting
# retrospective year relative to end year to
0.
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. 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.
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.
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 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.
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 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.
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 # terminatorRemove 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 # terminatorIf 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.
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).
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.
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.
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.
Turn off #_mintailcomp using any negative value for
each fleet.
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.
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.
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.
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.