# Modifying the model setups included with ss3sim

#### 2017-04-18

# Modifying the OM and EM models included with ss3sim

ss3sim comes with three built-in SS3 operating and estimation model setups: a cod-like (slow-growing and long-lived), flatfish-like (fast-growing and long-lived), and sardine-like (fast-growing and short-lived). These model setups are based on North Sea cod (Gadus morhua, R. Methot, pers. comm.), yellowtail flounder (Limanda ferruginea, R. Methot, pers. comm.), and Pacific sardine (Sardinops sagax caeruleus; Hill et al. 2012). Further details on these models are available in Johnson et al. (2015) and Ono et al. (2015). These models were stripped down and simplified to make them more generic for simulation testing. In doing this, we removed many of the subtle features of the model setups. While these model setups are generic and cover a wide range of life history types, they may not be suitable for all users. Therefore, in this section, we outline strategies for modifying the existing SS3 models.

Before proceeding it is worth considering the scope and place of ss3sim as a simulation package. The package was designed as a tool for examining structural differences in alternative model setups. These differences could be between an OM and EM (e.g. Johnson et al. 2015) or between multiple EMs (e.g. Ono et al. 2015). Therefore, the specific details (e.g. many fleets, tagging data, seasons, etc.) of the original model setups were not important and removed to produce a set of generic life-history-type models. ss3sim is not designed for testing arbitrary SS3 models, but rather properties of assessment models in general. Thus ss3sim is not ideal for quickly exploring properties of a particular assessment model and other software packages should be explored if that is your goal (see accompanying for alternatives).

Here is a list of SS3 features that are not currently implemented in ss3sim:

- Seasons, sexes, hermaphrodism, multiple areas, movement, growth morphs, and platoons
- Data other than scientific surveys, commercial indices of abundance and age/length compositions: age-at-length, discards, mean weights, etc.

Some of the features may work within the ss3sim framework, but are untested.

It is possible to create new models that will work within the ss3sim framework, but this task will be complicated and likely require extensive knowledge of SS3 and R, as well as modification of the ss3sim functions. This process is described in more detail in Sections and .

Instead of creating entirely new models, we recommend adapting the current built-in models to match the desired model setups for a new simulation study. Since these models have been thoroughly tested and used with ss3sim already (see Johnson et al. 2015; Ono et al. 2015), they make an ideal starting place. Before proceeding it would be wise to examine the built-in models to determine how closely they match your desired model setups and whether simple changes can get you reasonably close for simulation purposes.

Say for example you want to modify the cod model to have different maturity, and then explore different sampling schemes using the `sample_index`, `sample_lcomp`, and `sample_agecomp` functions. The following steps provide a basic guideline for how to accomplish this:

- Using the original cod model create the case argument files you desire for your simulation and verify they run with the original cod model using the function `run_ss3sim`. It is probably best to do a shorter deterministic run (see the section on deterministic runs). After running, read in the data and do visual checks for proper functionality.
- Find the original cod model. This can be found in the `inst/extdata/models` folder inside the package, located by `system.file("extdata/models", package = "ss3sim")` Make a copy of the cod models (OM and EM) and rename them as desired.
- Make a single change to either the `.dat` or `.ctl` files for the new model and run them manually with SS3 if there is any question if they might break the model.
- Rerun the model through `run_ss3sim` and verify it is still working. If errors occur in the R function you will need to examine the function to determine why the error is occurring and fix by changing the R function and reloading it.
- Repeat previous steps with all small changes until the models are satisfactory.
- Turn off deterministic runs and run the simulation stochastically.
- If your new model works well with the package and is significantly different than what is built-in, please contact the ss3sim package managers for inclusion in future versions.

Hill, K. T., P. R. Crone, N. C. H. Lo, D. A. Demer, J. P. Zwolinski, and B. J. Macewicz. 2012. “Assessment of the Pacific Sardine Resource in 2012 for U.S. Management in 2013.” 7700 NE Ambassador Place, Portland, OR 97220, USA: Pacific Fishery Management Council.

Johnson, Kelli F., Cole C. Monnahan, Carey R. McGilliard, Katyana A. Vert-pre, Sean C. Anderson, Curry J. Cunningham, Felipe Hurtado-Ferro, et al. 2015. “Time-Varying Natural Mortality in Fisheries Stock Assessment Models: Identifying a Default Approach.” ICES Journal of Marine Science: Journal Du Conseil 72 (1): 137–50. doi:10.1093/icesjms/fsu055.

Ono, Kotaro, Roberto Licandeo, Melissa L. Muradian, Curry J. Cunningham, Sean C. Anderson, Felipe Hurtado-Ferro, Kelli F. Johnson, et al. 2015. “The Importance of Length and Age Composition Data in Statistical Age-Structured Models for Marine Species.” ICES Journal of Marine Science: Journal Du Conseil 72 (1): 31–43. doi:10.1093/icesjms/fsu007.