User Manual for the SWOMSE Package

North Atlantic Swordfish MSE

1 Introduction

This document is a quick start user guide to using the SWOMSE package to conduct management strategy evaluation (MSE) for the North Atlantic swordfish fishery (hereafter swordfish).

A description of the specifications for the MSE is available in MSE Trial Specifications Document. Other material relating to the operating models (OMs) and MSE is available on the Swordfish MSE homepage.

2 Required Software

2.1 R Software Environment

The SWOMSE framework requires the latest version of the R software installed on your system. The R software can be downloaded for Linux, Mac OS X, and Windows from here.

This manual assumes readers are familiar with the R programming language.

We also recommend the latest version of RStudio.

2.2 SWOMSE R Package

The MSE code is packaged into an R package called SWOMSE, stored in the ICCAT/nswo-mse GitHub Repository.

2.2.1 About the openMSE R Package

The SWOMSE package uses the openMSE package as a key dependency. openMSE will be automatically installed when the SWOMSE package is installed.

openMSE is an umbrella R package for:

  • MSEtool: an R package developed for conducting fast, flexible, and transparent, MSE for a wide range of fisheries;
  • DLMtool: an R package containing 100+ data-limited management procedures;
  • SAMtool: an R package containing data-moderate and data-rich stock assessments and operating model conditioning functions.

All functions related to importing operating models, simulating the historical fishery dynamics, and projecting the fishery forward in time with different modes of management are located in the MSEtool package, and are available to the user when the SWOMSE package is loaded.

A non-technical description of openMSE and its key features is available on the openMSE website. The operating model in MSEtool, including assumptions and equations, is described in detail in Carruthers & Hordyk (2018).

2.2.2 Installing SWOMSE

The SWOMSE package requires the latest version of the openMSE packages. These can be installed directly from CRAN.

It’s usually best to remove existing packages before installing new versions (don’t worry about the error message if these packages aren’t already installed on your machine):

remove.packages('openMSE')
remove.packages('DLMtool')
remove.packages('MSEtool')
remove.packages('SAMtool')

Then install the latest version of openMSE (this will also install the latest version of the other packages):

install.packages('openMSE')

The remotes package is required to install the SWOMSE package from GitHub. Install the remotes package with:

install.packages('remotes')

Then the SWOMSE package can be installed directly from the GitHub repository using the remotes package:

remotes::install_github("ICCAT/nswo-mse")

This will install the SWOMSE package and all the dependency packages on your machine.

Alternatively, you can clone the repository on your machine and build and install the package locally with RStudio.

Once installed, the package can be loaded into the current R session:

library(SWOMSE)

3 Operating Models

The SWOMSE package contains all the operating models (OMs) that have been generated for the swordfish MSE. The operating models are objects of class MOM (multi-stock operating models), and are structured to include 2-sexes (female and male) and one overall fishing fleet (aggregated exploitation pattern of the individual fleets).

Currently, the 36 MOMs from the uncertainty grid are available in the SWOMSE package. See the Trial Specifications Document for more information on the OM uncertainty grid. These operating models were developed from the 2022 base case assessment model. See the Trial Specs Doc for more information on the OM conditioning.

The 2022 base case stock assessment is also available in the package (MOM_000).

Each OM has 48 individual simulations (used to generate stochastic recruitment deviations and observation parameters for the projection period), specified in the nsim slot:

MOM_000@nsim
## [1] 48

The Name slot in the MOM object provides a summary of the individual levels of the axes of uncertainty for a particular OM, e.g.,:

MOM_000@Name
## [1] "M:0.2 sigmaR:0.2 steepness:0.88 Include CAL:TRUE llq:1 env:1 Class:Base Case"

4 Fishery Data

The Fishery Data object SWOData is an object of class Data and contains the three sources of historical data:

  1. Reported total catch (Figure 4.1)
  2. Combined Index (Figure 4.2), and
  3. Additional indices of abundances (Figure 4.3).

These data are provided to the CMPs in the closed-loop simulation testing, and are updated with simulated data in the closed-loop projections.

See here for more information on the Data object and how it is used in the MSE framework.

4.1 Catch Data

The catch data is provided in the Cat slot of the SWOData object:

df <- data.frame(Year=SWOData@Year, Catch=SWOData@Cat[1,])
head(df)
##   Year Catch
## 1 1950  3646
## 2 1951  2581
## 3 1952  2993
## 4 1953  3303
## 5 1954  3034
## 6 1955  3502

Figure 4.1: The historical total catch and total allowable catch (TAC) for the North Atlantic swordfish.

4.2 Combined Index

The Combined Index is available in the Ind slot:

df <- data.frame(Year=SWOData@Year, Catch=SWOData@Ind[1,])
tail(df)
##    Year    Catch
## 66 2015 0.582232
## 67 2016 0.514055
## 68 2017 0.537849
## 69 2018 0.717871
## 70 2019 0.629866
## 71 2020 0.819726

Figure 4.2: The Combined Index for the North Atlantic swordfish fishery.

4.3 Additional Indices

The 14 additional fishery-dependent and survey indices are available in the AddInd slot. SWOData@AddInd is a 3-dimensional array:

dim(SWOData@AddInd)
## [1]  1 14 71

The first dimension is the simulation number, and is length 1 year because this is real fishery data (i.e., not simulated). The other dimensions are the individual fleets and the historical years.

The names of each element in each dimension are accessible using the dimnames function, i.e.,:

dimnames(SWOData@AddInd)
## [[1]]
## [1] "1"
## 
## [[2]]
##  [1] "SPN_1"          "CAN_3"          "JPN_ERLY_4"     "JPN_LATE_5"    
##  [5] "CHT_EARLY_7"    "CHT_LATE_8"     "MOR_9"          "US_Survey_12"  
##  [9] "PORT_Survey_13" "Age-1"          "Age-2"          "Age-3"         
## [13] "Age-4"          "Age-5+"        
## 
## [[3]]
##  [1] "1950" "1951" "1952" "1953" "1954" "1955" "1956" "1957" "1958" "1959"
## [11] "1960" "1961" "1962" "1963" "1964" "1965" "1966" "1967" "1968" "1969"
## [21] "1970" "1971" "1972" "1973" "1974" "1975" "1976" "1977" "1978" "1979"
## [31] "1980" "1981" "1982" "1983" "1984" "1985" "1986" "1987" "1988" "1989"
## [41] "1990" "1991" "1992" "1993" "1994" "1995" "1996" "1997" "1998" "1999"
## [51] "2000" "2001" "2002" "2003" "2004" "2005" "2006" "2007" "2008" "2009"
## [61] "2010" "2011" "2012" "2013" "2014" "2015" "2016" "2017" "2018" "2019"
## [71] "2020"

For example, to access the ‘CAN_3’ index you need to access the second element in the second dimension:

dimnames(SWOData@AddInd)[[2]][2]
## [1] "CAN_3"
# SWOData@AddInd[1,2,]

Figure 4.3: The additional individual fishery-dependent and survey indices for the North Atlantic swordfish fishery.

5 Running the MSE

In this example, we will run a closed-loop simulation for a single operating model from the OM uncertainty grid.

5.1 Selecting the OM

First, we select an operating model. Here we will use MOM_000:

OM_DF %>% dplyr::filter(OM.num=='000')
##   OM.object   M sigmaR steepness Include CAL llq env     Class OM.num
## 1   MOM_000 0.2    0.2      0.88        TRUE   1   1 Base Case    000
##              dir
## 1 /000_base_case
OM <- MOM_000

You can see the details for all the OMs by examining the OM_DF object.

5.2 Selecting the MPs

Next, we select the management procedures we wish to evaluate. We’ll select from some of the example MPs included in the SWOMSE package:

MPs <- avail('MP', 'SWOMSE')
## ✔ Searching for objects of class MP in package: SWOMSE
MPs
##  [1] "ITarget_1" "ITarget_2" "JABBA_1"   "SP_1"      "SP_2"      "SP_3"     
##  [7] "SP_Fox_1"  "SP_Fox_2"  "SP_Fox_3"  "SP_SS_1"   "SP_SS_2"   "SP_SS_3"  
## [13] "SPICT_1"

Here we’ll use two model-free MPs (ITarget_1 and ITarget_2) and two MPs that use a surplus production assessment model together with a harvest control rule (SP_2 and SP_Fox_2). You see the details of these MPs by accessing the help documentation (e.g., ?SP_2) or printing out the function and examining the code (e.g., SP_2).

A detailed guide for developing custom management procedures is available here.

ourMPs <- c("ITarget_1", "ITarget_2", "SP_2", "SP_Fox_2")

5.3 Running the MSE

Now we are ready to run the MSE. It’s often useful to split the simulation process into two phases (historical spool-up and forward projections) and save the objects to disk.

That way, if you revise your MPs or develop more, you can just re-do the projections without having to re-do the historical spool-up as well.

5.3.1 Simulate Historical Spool-Up

Hist <- SimulateMOM(OM, silent=TRUE, parallel=FALSE)

# optional: save historical simulation object to disk
saveRDS(Hist, 'MOM_000.hist')

5.3.2 Forward Projections

Now we can run the forward projections:

MMSE <- ProjectMOM(Hist, MPs=ourMPs, silent=TRUE)

# optional: save projection object to disk
saveRDS(MMSE, 'MOM_000.mmse')

5.4 Examining the Results

The results of the MSE can be examined in various ways.

5.4.1 Summary of Performance Metrics

Here we print out a summary of the North Atlantic Swordfish performance metrics (see here for a description of the performance metrics).

PMs <- avail('PM', 'SWOMSE')
## ✔ Searching for objects of class PM in package: SWOMSE
summary(MMSE, PMs)
## ✔ Calculating Performance Metrics
##                                            Performance.Metrics 
## 1                           Spawning Biomass relative to SBMSY 
## 2                           Spawning Biomass relative to SBMSY 
## 3 Prob. Average Annual Variability in Yield < 25% (Years 1-30) 
## 4                                     Green Zone of Kobe Space 
## 5                                     Green Zone of Kobe Space 
## 6                                    Mean Yield  (Years 11-30) 
## 7                                     Mean Yield  (Years 1-10) 
##                                                         
## 1                   Prob. SB > 0.4 SBMSY (Years 11 - 30)
## 2                    Prob. SB > 0.4 SBMSY (Years 1 - 10)
## 3 Average Annual Variability in Yield < 25% (Years 1-30)
## 4         Prob. Green Zone of Kobe Space (Years 11 - 30)
## 5          Prob. Green Zone of Kobe Space (Years 1 - 10)
## 6                               Mean Yield (Years 11-30)
## 7                                Mean Yield (Years 1-10)
## 
## 
## Performance Statistics:
##          MP Safety_M Safety_S Stability Status_M Status_S Yield_M Yield_S
## 1 ITarget_1     1.00        1      1.00     0.96     0.40    6800   10000
## 2 ITarget_2     1.00        1      1.00     0.92     0.60   10000    8900
## 3      SP_2     1.00        1      1.00     0.88     0.55   11000    9900
## 4  SP_Fox_2     0.98        1      0.98     0.60     0.28   11000   11000

5.4.2 Projection Plots

The Proj_plot function can be used to generate projection plots of the spawning biomass relative to SB_MSY, F/FMSY, and the catches in the projection period. These plots show the median and 5th and 95th percentiles:

Proj_plot(MMSE)

Proj_plot(MMSE, 'Catch')

Proj_plot(MMSE, 'F_FMSY')

5.4.3 Trade-Off Plots

The TradePlot function can be used to generate plots showing trade-offs between the various performance metrics:

TradePlot(MMSE,
          'Safety_M', 'Yield_M',
          'Status_M', 'Yield_M',
          'Stability', 'Yield_M',
          'Yield_S', 'Yield_M',
          Lims=c(0.95,0,
                 0.95, 0,
                 0,0,
                 0,0))

References

Carruthers, T., & Hordyk, A. R. (2018). The Data-Limited Methods Toolkit (DLMtool): An R package for informing management of data-limited populations. Methods in Ecology and Evolution, 9(12), 2388–2395. https://doi.org/10.1111/2041-210X.13081