---
title: "User guide to MSEtool"
subtitle: "Development, Testing and Implementation of Management Procedures for Data-Rich Fisheries"
author: "Quang Huynh (<q.huynh@oceans.ubc.ca>), Tom Carruthers (<t.carruthers@oceans.ubc.ca>), 
         Adrian Hordyk (<a.hordyk@oceans.ubc.ca>)"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    number_sections: true 
vignette: >
  %\VignetteIndexEntry{User guide to MSEtool}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<style type="text/css">

body{ /* Normal  */
   font-size: 12px;
}
td {  /* Table  */
   font-size: 8px;
}
h1 { /* Header 1 */
 font-size: 18px;
 color: DarkBlue;
}
h2 { /* Header 2 */
 font-size: 15px;
 color: DarkBlue;
}
h3 { /* Header 3 */
 font-size: 14px;
 color: DarkBlue;
}
code.r{ /* Code block */
  font-size: 10px;
}
pre { /* Code block */
  font-size: 10px
}
</style>


```{r set options, echo = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
knitr::opts_chunk$set(dpi=85)
options(width = 650)
library(MSEtool)
```

<br>


# Version Notes

The package is subject to ongoing testing. If you find a bug or a problem please send a report to <t.carruthers@oceans.ubc.ca> so that it can be fixed!  

## New additions to this version (1.0.0)

* Assessment models (__Assess__ class functions)
    * Statistical Catch at Age (`SCA` and `SCA2`)
    * Delay Difference (`DD_TMB`)
    * State-Space Delay Difference (`DD_SS`)
    * Surplus Production (`SP`)
    * State-Space Surplus Production (`SP_SS`)

* Visualization functions
    * Standardized assessment reports (`plot` and `summary`)
    * Diagnostics for assessment models (`profile_likelihood` and `retrospective`)
    * Diagnostics for assessment models within closed-loop simulation (AM, assessment in MSE) (`prelim_AM`, `diagnostic_AM`, and `retrospective_AM`)

* Other features 
    * Harvest control rules (__HCR__ class functions: `HCR_MSY`, `HCR40_10`, and `HCR60_20`)
    * `make_MP` function conveniently combines a __Assess__ and __HCR__ function to create a __MP__ function
    * `simmov` function creates movement matrices for parameterizing multiple area operating models (age-independent)
    * `iSCAM2OM` and `iSCAM2Data` functions import from iSCAM assessments. The MCMC outputs of iSCAM models are now used to characterise operating model uncertainty
    * `SS2OM` and `SS2Data` functions import Stock Synthesis assessments using the r4ss package version 1.24.0 (latest CRAN version)

## Coming soon 

* More data-rich assessment models
    * Virtual Population Analysis (VPA)
    * Kalman filter assessment approximation

* Stock projections for assessment models

* Age-varying movement matrices for `simmov` to condition operating models

* Multi-stock and multi-fleet operating models

# Introduction 
MSEtool is an extension of the DLMtool package for implementing closed-loop simulation testing of management procedures, a process often referred to as management strategy evaluation (MSE). The components of the operating model for conducting MSEs for data-rich stocks is wholly contained within DLMtool, but MSEtool provides the tools for implementing additional features to facilitate such MSEs. Whereas DLMtool is primarily designed for testing data-limited management procedures, MSEtool provides an object-oriented framework for creating data-rich management procedures (MPs), which typically involve combining an assessment model with a harvest control rule to provide a fishery management recommendation. Management procedures created by MSEtool are designed to be used with the operating model of DLMtool through the `runMSE` function. 

The user guide to the DLMtool package is accessible via

```{r, eval = FALSE}
DLMtool::userguide()
```

The overall structure of a closed-loop simulation for a MSE in DLMtool can be described through the classes deployed in the package. An operating model (class __OM__ object) parameterizes the stock (biology), fleet, observation, and implementation dynamics of the MSE. To begin the MSE, the __OM__ object generates the data to be used for a management procedure and stores them in an object of class __Data__. A function of class __MP__ uses the __Data__ object and returns an object of class __Rec__ containing the management recommendations, e.g., some combination of spatial closures and size, effort and catch limits. From the management recommendations, the __OM__ object is updated and the process is successively repeated as the operating model progresses over time. The output for the closed-loop simulation is returned in an object of class __MSE__, from which summary statistics can be calculated.

<img src="DLMtool_design.png" width=400>

_Figure 1: Design of DLMtool package for management strategy evaluations_

## Overview of MSEtool

To facilitate a standardized design for data-rich MPs, MSEtool creates new classes to build out the __MP__ class. MSEtool uses functions of class __Assess__ and __HCR__ for an assessment model and harvest control rule, respectively. An __MP__ class function can be made from these functions to be tested in a MSE within the DLMtool framework. 

Additionally, __Assess__ functions can be used in an assessment-only context (external to management strategy evaluations). Output of an __Assess__ function can be used to provide standardized stock assessment reporting and diagnostics, such as Kobe plots, likelihood profiles for parameter estimates, and retrospective analyses of time series estimates of biomass, fishing mortality, recruitment, etc.

<img src="MSEtool_design.png" width=690>

_Figure 2: Design of MSEtool package for building management procedures from assessment models and harvest control rules for management strategy evaluations with the DLMtool package. Assess and HCR functions and the Assessment object are unique to MSEtool, but work within the framework of DLMtool objects. Separate functions are also available for standardized reporting of output from assessment models in a stock assessment setting._


### Additional features
MSEtool provides functions for converting the results of assessment models into DLMtool __OM__ and __Data__ objects. The `SS2OM` and `SS2Data` functions convert SS (Stock Synthesis) assessments, while `iSCAM2OM` and `iSCAM2Data` functions are provided for iSCAM assessments. 

To support multiple-area operating models, the `simmov` function estimates the movement matrix based on the prescribed number of areas, biomass distribution among areas in unfished conditions, and the probability of staying in each area in the next time step.


# Assessment models

Assessment models in MSEtool are functions of class __Assess__. 
Currently, six assessment functions are available: `DD_TMB` (Delay-Difference model and its state-space counterpart, `DD_SS`), `SP` (Surplus Production model and its state-space counterpart, `SP_SS`), and `SCA` (Statistical Catch at age model and another variant `SCA2`). These functions take a __Data__ object as an argument and return an object of class __Assessment__, for example,

```{r, eval = FALSE}
DD_result <- DD_TMB(Data = Red_snapper, ...)
```
where `...` are model configuration arguments.

The __Assessment__ object contains the raw output from TMB estimation model, optimization output from `nlminb`, and parameter estimates with covariance matrix. If applicable, time series estimates of total biomass, vulnerable biomass, spawning stock biomass, fishing mortality and/or exploitation rate, as well as their corresponding MSY and virgin reference points. The __Assessment__ object also reports likelihood values and predicted values for the data used in the assessment model. The object documentation for the __Assessment__ object can be obtained through:

```{r, eval = FALSE}
class?Assessment
```

Descriptions of the __Assess__ functions are provided in a separate Appendix vignette:

```{r, eval = FALSE}
vignette("Assessment", package = "MSEtool")
```

## Reporting and diagnostic functions

Assessment results and summary, along with diagnostic procedures are available for each assessment model. Generic functions `summary` and `plot` are available for __Assessment__ objects. The `summary` function returns a list of estimated current stock status ($F/F_{MSY}$ , $B/B_{MSY}$ in the terminal year), input parameters to the model, derived quantities, and parameter estimates. The `plot` function generates time series figures of data, fitted data, and estimated quantities (e.g., biomass and recruitment). By default, these figures are save to disk and can be viewed with a HTML webpage generated by the function.

```{r, eval = FALSE}
summary(DD_result)
plot(DD_result, save_figure = TRUE, save_dir = tempdir()) # By default, also saves figures in a temporary directory for viewing through a HTML browser. The directory can be changed to a user's filespace of choice.
```

Two diagnostic functions are available: `retrospective` for retrospective analyses (re-running the model by sequentially removing terminal years of data) and `profile_likelihood` for profiling the likelihood function over a grid of parameters.

```{r, eval = FALSE}
retrospective(DD_result, nyr = 5) # Retrospective analysis going back 5 years from current year
profile_likelihood(DD_result, R0 = seq(0.75, 1.25, 0.025), h = seq(0.95, 1, 2.5e-3)) # Joint profile over grid of R0 and steepness
```
<img src="DD_profile.png" width=400>

_Figure 3: Joint profile of R0 and steepness from Delay-Difference assessment model (DD_TMB function). Contours indicate change in likelihood values from minimum (red point)._

# Harvest control rules (HCRs)

Harvest control rules in MSEtool are functions of class __HCR__, and are designed to provide different for a given assessment model. __HCR__ functions take an object of class __Assessment__ and return an object of class __Rec__. Currently, three __HCR__ functions are available as output controls (catch limits): HCR_MSY, HCR40_10, and HCR60_20. HCR_MSY prescribes the TAC to be the catch predicted with fishing at the estimated $F_{MSY}$, i.e., the product of $F_{MSY}$ and estimated vulnerable biomass, while HCR40_10 and HCR60_20 are ramped control rules which reduce the $F_{MSY}$ catch limit based on spawning depletion $SSB/SSB_0$.

```{r, echo = FALSE, fig.width = 5, fig.height = 4}
par(mar = c(5,5,3,1))
Brel <- seq(0, 1, length.out = 200)
plot(Brel, MSEtool::HCRlin(Brel, 0.1, 0.4), xlab = expression(Estimated~~SSB/SSB[0]), ylab = "TAC adjustment factor \n(proportion of FMSY catch)", main = "40-10 harvest control rule", type = "l", col = "blue")
abline(v = c(0.1, 0.4), col = "red", lty = 2)
```

_Figure 4: The 40-10 harvest control rule prescribes an additional reduction in the TAC based on estimated spawning depletion._

# Data-rich management procedures (MPs)

## Creating MPs from assessment models and HCRs

MSEtool comes with a set of pre-built data-rich MPs:
```{r}
avail("MP", all_avail = FALSE)
```
These MPs use an assessment model and a harvest control rule to come up with a management recommendation (TAC).

Additionally, the `make_MP` function is a convenient way to stitch together additional MPs from an assessment model and HCR. This is handy if an assessment model with a different configuration than the default is needed (for example, specify dome vulnerability instead of logistic vulnerability in `SCA`) or a different harvest control rule is desired. The resulting function can then be passed to `DLMtool::runMSE()` as a management procedure.

```{r, eval = FALSE}
DD_MSY <- make_MP(DD_TMB, HCR_MSY, ...)
DD_4010 <- make_MP(DD_TMB, HCR40_10)
myMSE <- DLMtool::runMSE(OM = DLMtool::testOM, MPs = c("FMSYref", "DD_MSY", "DD_4010"))
Tplot2(myMSE)
```

<img src="DD_Tplot2.png">

_Figure 5. Trade-off plot of the MSE for the MPs that use the Delay-Difference model with two harvest control rules and the FMSY reference MP._

Model configuration arguments can be passed through `...` in `make_MP` when the MP is made. For example, the Ricker stock-recruitment relationship can be used in the Delay-Difference model instead of the default Beverton-Holt relationship and steepness can be fixed instead of esimated by passing argument `SR = "Ricker"` and `fix_h = TRUE`, respectively:

```{r, eval = FALSE}
DD_MSY_Ricker_fixsteep <- make_MP(DD_TMB, HCR_MSY, SR = "Ricker", fix_h = TRUE)
```

This MP will call `DD_TMB(..., SR = "Ricker", fix_h = TRUE)`.

## Diagnostic of assessment models in MSE

Three functions are designed to evaluate the performance of __Assess__ models in MSE: `prelim_AM`, `diagnostic_AM`, and `retrospective_AM` (where _AM_ stands for "assessment in MSE").

`prelim_AM` is designed to evaluate the configuration of the assessment model before running the closed-loop simulation. Given an operating model, this function generates data from the historical period of the MSE, applies the assessment model to those data, then returns the convergence rate of the model. A list of __Assessment__ objects are returned and can be used for troubleshooting. Additional arguments are passed to the __Assess__ function via `...`:

```{r, eval = FALSE}
prelim_AM(DLMtool::testOM, DD_TMB, ...)
#> Generating Hist object from OM object via runMSE:
#> Loading operating model
#> Optimizing for user-specified movement
#> Optimizing for user-specified depletion
#> Calculating historical stock and fishing dynamics
#> Calculating MSY reference points
#> Calculating B-low reference points
#> Calculating reference yield - best fixed F strategy
#> Returning historical simulations
#> Running DD_TMB with 48 simulations for DLMtool::testOM.
#> Assessments complete.
#> Total time to run 48 assessments: 1.2 seconds
#> 2 of 48 simulations (4.2%) did not converge.
#> See simulation number: 11 21
```

By default, assessment model results are not saved during the MSE. However, this feature can be turned on in two steps, as shown in the following example:

```{r, eval = FALSE}
DD_MSY <- make_MP(DD_TMB, HCR_MSY, diagnostic = "full")
myMSE <- runMSE(..., MPs = "DD_MSY", PPD = TRUE)
```

First, the MP should be made with `make_MP` by setting `diagnostic = "min"` or `diagnostic = "full"`. Second, the call to `runMSE` should be accompanied with argument `PPD = TRUE`. 

With this combination, two diagnostic objects can be saved and reported in the `Misc` slot of the MSE object returned by `runMSE`: convergence diagnostics and the __Assessment__ objects from each assessment call. The first can be obtained with `diagnostic = "min"`, while both are returned with `diagnostic = "full"`.

The `diagnosic_AM` function plots the convergence information, and `retrospective_AM` plots the assessment model's retrospective patterns (for a single simulation in the MSE).

```{r, eval = FALSE}
diagnostic_AM(myMSE)
retrospective_AM(myMSE, sim = 1, MP = "DD_MSY")
```
<img src="DD_diagnostic_AM.png">

_Figure 6. Convergence diagnostics (return by TMB objects and nlminb function) for the DD_MSY MP during the MSE. Here, the assessment model was applied beginning in year 50 of the MSE and repeated every 4th year. In MSEtool, convergence is defined by a positive-definite Hessian matrix (top left figure). In the case of non-convergence, the previous management recommendation is used._

<img src="DD_retrospective_AM.png">

_Figure 7. Retrospective analysis of the Delay-Difference model in the DD_MSY MP during the MSE for simulation #1. Operating model (true) values of spawning biomass (SSB), relative spawning biomass (SSB_SSBMSY), spawning biomass depletion (SSB_SSB0), fishing mortality (F), relative F (F_FMSY), and vulnerable bimoass (VB) are in dark black. Colored lines indicate model estimates sequentially over the projection years. Note that this assessment model assumes the vulnerable biomass to be the spawning biomass._

Once it is determined that the MSEtool assessment models are performing adequately (no major convergence issues), then the performance of the MPs that use these models can be evaluated within the DLMtool package.

## Obtaining management recommendations

Like all other output MPs, `DLMtool::TAC()` can be used to obtain a catch limit:
```{r, eval = FALSE}
DD_MSY <- make_MP(DD_TMB, HCR_MSY)
DD_4010 <- make_MP(DD_TMB, HCR40_10)
snapper_TAC <- TAC(Red_snapper, MPs = c("DD_MSY", "DD_4010"))
plot(snapper_TAC)
```
<img src="DD_TAC.png">

_Figure 8. Stochastic TAC recommendations from the Delay-Difference model with two harvest control rules. When the 40-10 harvest control rule is applied, the prescribed TAC is close to zero because the assessment model estimated the terminal year biomass depletion to be 0.13 (close to the limit reference point)._


# Acknowledgements

MSEtool development is funded by the Canadian Department of Fisheries and Oceans and benefits from ongoing collaborations with the Natural Resources Defense Council and number of Canadian government scientists including Robyn Forrest, Sean Anderson and Daniel Duplisea. 

The [DLMtool](http://www.datalimitedtoolkit.org) package was developed at the University of British Columbia in collaboration with the Natural Resources Defense Council. DLMtool development has been funded by the Gordon and Betty Moore Foundation, the Packard Foundation, U.S. National Oceanic and Atmospheric Administration, Fisheries and Oceans Canada, the Walton Foundation, Resources Legacy Fund, the Natural Resources Defense Council, the United Nations Food and Agricultural Organization and the California Department of Fish and Wildlife. 

<a href="http://www.datalimitedtoolkit.org"><img src="DLMtool_logo.png" width=250></a>
