README.Rmd

---
output:
  md_document:
    variant: markdown_github
---

<!-- README.md is generated from README.Rmd. Please edit that file and run
     `rmarkdown::render()` on this file. -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  cache = TRUE,
  autodep = TRUE
)
options("width" = 90)
library("magrittr")
```

# ss3sim models

[![Travis-CI Build Status](https://travis-ci.org/ss3sim/ss3models.png?branch=master)](https://travis-ci.org/ss3sim/ss3models)

This R package contains operating model (OM) and estimating model (EM) files and case files for use within the [ss3sim][ss3sim] package. [ss3sim][ss3sim] is an R package that facilitates flexible, rapid, and reproducible fisheries stock assessment simulation testing with the widely-used [Stock Synthesis 3][SS3] (SS3) statistical age-structured stock assessment framework.

```{r, echo = FALSE, message = FALSE}
devtools::load_all()
```

Install the ss3models package with:

```{r, eval = FALSE}
# install.packages("devtools")
devtools::install_github("ss3sim/ss3models")
library("ss3models")
```

The model setups are stored in the package in the [`inst/models`](inst/models) folder. The local file path to the operating models (`om` folders) and estimating models (`em` folders) can be accessed using the `ss3model` function:

```{r, eval = FALSE}
ss3model("hake", "em")
#> "/Library/Frameworks/R.framework/Versions/3.1/Resources/library/ss3models/models/hake/em"
ss3model("flatfish", "om")
#> "/Library/Frameworks/R.framework/Versions/3.1/Resources/library/ss3models/models/flatfish/om"
```

You can get a list of all available models in R with:

```{r}
list_models()
```

The SS3 model setup files in the operating model folders are:

```{r}
ss3model("hake", "om") %>%
  dir
```

SS3 files in the estimating model folders are:

```{r}
ss3model("hake", "em") %>%
  dir
```

The ss3models package also contains a couple helper functions for working with and checking model setups. For example:

```{r}
system.file("models", package = "ss3models") %>%
  get_parvalues(write_csv = FALSE) %>%
  head
```

You can test all the operating model setups (run them through SS3 with `-noest`) and run all the \code{.dat} files through `ss3sim::check_data()` by running `devtools::test()` in the base `ss3models` folder.

If you also want to test the estimation model setups (run them through SS3 with `-nohess`) then uncomment the relevant code in [`tests/testthat/test-models.R`](tests/testthat/test-models.R). For now the code is commented out while we develop the models. They take a while to run. 

## Included models

### Base models (length-based selectivity)

1. `cod`: length-based double normal selectivity (mimicking logistic) in OM, length-based double normal selectivity (mimicking logistic) in EM, narrow bounds

2. `flatfish`: length-based double normal selectivity (mimicking logistic) in OM, length-based double normal selectivity (mimicking logistic) in EM, narrow bounds

3. `yellow`: (yellowtail flounder) length-based double normal selectivity (mimicking logistic) in OM, length-based double normal selectivity (mimicking logistic) in EM, length-based maturity

4. `hake`: length-based double normal selectivity (mimicking logistic) in OM, length-based double normal selectivity (mimicking logistic) in EM, length-based maturity (slightly changed compared t o the original assessment to match the purpose of this simulation study)

### Base models (age-based selectivity)

1. `cod-age`: TODO

2. `flatfish`: TODO

3. `yellow-age`: (yellowtail flounder) age-based double normal selectivity (mimicking logistic) in OM, age-based double normal selectivity (mimicking logistic) in EM, age-based maturity

4. `hake-age`: age-based double normal selectivity (mimicking logistic) in OM, age-based double normal selectivity (mimicking logistic) in EM, age-based maturity (converted from the 'hake' model)

### Model summaries

Specific information for each model can be found in the [information document][info.csv]. Columns with todo in the name should be filled out with your initials once completed. All other columns pertain to information specific the parameterization of each model.

Eventually more summary data and descriptive plots will be available on the `README.md` files within each species folder.

### Paramerization

- Selectivity: parameterized using a double normal to mimic logistic selectivity
  * age-based
  * length-based

- Maturity:
  * age-based logistic maturity
  * length-based logistic maturity

### TODO

- [ ] lbin type = 2
- [ ] population bin width must be divisible by the data bin width
- [ ] years = 1:100
- [ ] Standardize parameter bounds using [standardize_bounds](https://github.com/ss3sim/ss3sim/blob/master/R/standardize_bounds.R): approach used in [Johnson *et al*. (2015)][johnsonetal] of lower bounds = 0.5% of init values and upper bounds = [ ] 500% of init values
- [ ] Fishing case files: "F" case files for each model are based on Fmsy, which can be found with [profile_fmsy](https://github.com/ss3sim/ss3sim/blob/master/R/profile_fmsy.r). Casefiles are automatically generated from the script [create_f.R][fscript]. Please rerun this script any time a new model is added.
  * F0 = Constant fishing at Fmsy (constant): years 25 - 100 at Fmsy;
  * F1 = Two way trip (contrast): years 25 - 65 ramp up to 0.9 x Fmsy (right limb), years 66 - 100 ramp down from 0.9 x Fmsy (right limb) to 0.9 x Fmsy (left limb;
  * F2 = One way trip (increase): years 25 - 100 ramp up to 0.9 x Fmsy (left limb).

[vignette]: https://dl.dropboxusercontent.com/u/254940/ss3sim-vignette.pdf
[paper]: http://www.plosone.org/article/info%3Adoi%2F10.1371%2Fjournal.pone.0092725
[SS3]: http://nft.nefsc.noaa.gov/Stock_Synthesis_3.htm
[r-project]: http://www.r-project.org/
[SAFS]: http://fish.washington.edu/
[ss3sim]: https://github.com/ss3sim/ss3sim
[johnsonetal]: http://icesjms.oxfordjournals.org/content/early/2014/04/09/icesjms.fsu055.full.pdf?keytype=ref&ijkey=NEXmZIkz3289u3z)
[info.csv]: https://github.com/ss3sim/growth_models/blob/master/extra/modelinfo.csv
[fscript]: https://github.com/ss3sim/growth_models/blob/master/create_f.R