Introduction to MixME

Overview

MixME is an R package that allows users to simulate the performance of management strategies, also known as management procedures, in the presence of 'real-world' mixed fisheries technical interactions. Following the Management Strategy Evaluation (MSE) paradigm, the 'real-world' state of the system, where fleets catch multiple stocks and compete for a share of the available harvest, is kept strictly separate from the observed system.

MixME is geared towards flexibility, allowing you to tailor all aspects of the management strategy, from specifying how stocks are observed with error, to provide custom functions for stock estimation and advice generation. However, you may also use the provided built-in routines to rapidly assemble an off-the-shelf management strategy.

MixME input structure

MixME takes a standard input structure irrespective of whether we are setting up a single stock and fleet simulation or the most complex multi-stock and fleet mixed fisheries simulation. The objects required for MixME are:

• om: the Operating Model (OM) containing data and parameters governing stock and fleet dynamics.
• oem: the Observation Error Model (OEM) containing commercial catch and survey index deviances, timings of catch and index data availability, and survey catchabilities.
• ctrl_obj: the methods and arguments required to carry out each stage of the management procedure
• args: the arguments required to carry out the simulation

The FLQuant object is the basic data storage object used in MixME and is a six-dimensional array structured around spatial and temporal strata. The iteration dimension is used to store data and parameter uncertainty. Each iteration therefore represents a distinct trajectory resulting from existing uncertainties around stock status and plausible future variability in stock and fleet dynamics.

Operating model (om)

The operating model object (om) structure is as follows. For simplicity, only the data slots that are used in MixME simulations are listed:

• om: a list containing stock and fleet data and parameters
  • stks: an object of class FLBiols with named elements
    • 'stock name': an object of class FLBiol containing the data and parameters for a single stock
      • n: a slot of class FLQuant containing stock numbers at age
      • m: a slot of class FLQuant containing natural mortality at age
      • wt: a slot of class FLQuant containing individual mean weight at age
      • mat: a slot of class FLQuant containing proportion mature at age
      • rec: a slot of class predictModel containing the formula and parameters for a stock-recruit model
  • flts: an object of class FLFisheries with named elements
    • 'fleet name': an object of class FLFishery containing the data and parameters for a single fleet/fishery and associated stock catches
      • effort: a slot of class FLQuant containing annual effort
      • 'stock name': an object of class FLCatch containing that data and parameter for catches of a single stock
        • landings.n: a slot of class FLQuant containing the number of individuals landed at age
        • landings.wt: a slot of class FLQuant containing the individual mean weight at age of landed individuals
        • discards.n: a slot of class FLQuant containing the number of individuals discarded at age
        • discards.wt: a slot of class FLQuant containing the individual mean weight at age of discarded individuals
        • catch.sel: a slot of class FLQuant containing the catch selection at age
        • catch.q: a slot of class FLPar containing catchability alpha and beta parameters
        • quotashare: an attribute of class FLQuant containing the proportional share of stock quota

Observation error model (oem)

The observation error model object (oem) has the following structure:

• oem: an object of class FLoem with slots observations, deviances, and args
  • observations: a list containing two elements
    • stk: an object of class FLStocks with named elements corresponding to observed stocks
      • 'stock name': an object of class FLStock containing the observed data and parameters for a single stock
    • idx: a list with named elements
      • 'stock name': an object of class FLIndices with named elements corresponding to survey indices
  • deviances: a list containing two elements
    • stk: a list with named elements corresponding to observed stocks
      • 'stock name': a 7-d array containing the age-specific stock deviances for each fleet
    • idx: a list with named elements corresponding to observed stocks
      • 'stock name': an object of class FLQuants with named elements corresponding to survey indices
        • 'survey name': an object of class FLQuant containing the age-specific stock deviances
  • args: a list containing arguments for the observation of commercial catches and scientific survey
    • use_stk_oem: a logical vector with named elements. Should the structure and parameters of observed stocks be taken from inputted oem observation arguments?
    • use_catch_residuals: a logical vector with named elements corresponding to observed stocks. Should observation error be applied to commercial catch?
    • use_idx_residuals: a logical vector with named elements corresponding to observed stocks. Should observation error be applied survey indices?
    • use_om_weights: logical. Should annually updated stock weights be sourced from the operating model?
    • catch_timing: a list of named elements corresponding to observed stocks
      • 'stock name': integer. Index of final data year relative to assessment year.
    • idx_timing: a list of named elements corresponding to observed stocks
      • 'stock name': integer vector. Index of final data year for each survey index relative to assessment year.

Management procedure arguments (ctrl_obj)

The methods and arguments for the management procedure (ctrl_obj) take the following structure:

• ctrl_obj: an object of class mpCtrl with named elements corresponding to distinct management procedure modules
  • est: an object of class mseCtrl containing methods and arguments for the estimation of stock status
  • phcr: an object of class mseCtrl containing methods and arguments for the parameterisation of harvest control rules
  • hcr: an object of class mseCtrl containing methods and arguments for the implementation of harvest control rules
  • isys: an object of class mseCtrl containing methods and arguments for the implementation of advice
  • fwd: an object of class mseCtrl containing methods and arguments for the forward projection of stock and fleet dynamics

MixME simulation arguments (args)

These take the form of a list with the following named elements:

• fy: integer. The final simulation year
• y0: integer. The first data year for any stock
• iy: integer. The initial simulation year
• management_lag: integer. The lag between the development and implementation of management advice
• frq: integer. The duration of management advice
• popType: integer vector with named elements corresponding to stocks. Each element is an integer code for the type of population model for the stock. 0 = age-structured dynamics, 1 = biomass dynamics, 2 = fixed populations. Biomass dynamics are not yet implemented in MixME.
• parallel: logical. Should parallel processing be used?
• nworkers: integer. The number of clusters used in parallel processing
• frange: list with named elements corresponding to stocks. Each element is an integer vector containing the age ranges used to calculate mean fishing mortality
• adviceInit: list with named elements corresponding to stocks. Each element is a numeric vector containing the management advice for each iteration
• maxRetry: integer. The number of times the effort optimisation module should retry identification of choke-stocks
• seed: integer. The seed for random number generation
• verbose: logical. Should simulation progress be printed?

MixME output structure

The output of a MixME simulation is a list of:

• om: the updated OM object
• tracking: a tracking object
• ctrl_obj: the input management procedure arguments
• args: the input simulation arguments

The management procedure (ctrl_obj) and simulation (args) arguments are repeated from the input object. This ensures that the output object contains all the information needed to process, analyse and interpret simulation results without requiring the full input object.

Tracking

The tracking object is generated at the beginning of each MixME simulation and stores several useful diagnostics and summaries to quickly evaluate the quality of simulation performance and interpret the dynamics of the system. The tracking object is a list:

• 'stock name': a list with named elements
  • advice: 3-dimensional array (advice,year,iter) containing the management advice (catch target) for the stock in each year and iteration
  • sel_om: FLQuant containing the Operating Model selection-at-age. This is weighted by the proportional contribution of each fleet, and can therefore vary over time as fleet activity patterns change.
  • sel_est: FLQuant containing the estimated selection-at-age. This is catch selection from an estimation model that feeds into the management procedure.
  • stk: FLQuant tracking:
    • F.om: Operating model mean fishing mortality.
    • B.om: Operating model total biomass
    • SB.om: Operating model spawning biomass
    • C.om: Operating model total catch (by weight)
    • L.om: Operating model landings (by weight)
    • D.om: Operating model discards (by weight)
    • C.obs: Observed total catch (by weight)
    • L.obs: Observed landings (by weight)
    • D.obs: Observed discards (by weight)
    • conv.est: stock estimation model convergence. Note that this is NOT effort optimisation convergence.
    • F.est: estimated mean fishing mortality
    • B.est: estimated total biomass
    • SB.est: estimated spawning biomass
    • C.est: estimated total catch (by weight)
    • L.est: estimated landings (by weight)
    • D.est: estimated discards (by weight)
    • hcr.adv: harvest control rule output (mean fishing mortality or catch)
• quota: a 4-dimensional array (stk,flt,year,iter) containing the stock quota allocated to each fleet in each year and iteration.
• iterfail: matrix (year,iter) tracking cases of management advice generation failure.
• optim: a 3-dimensional array (metrics,year,iter) containing the objective value and convergence state for the effort optimisation routine in each year and iteration.
• message: a 3-dimensional array (metrics,year,iter) containing the convergence message and an (optional) re-scale effort multiplier.
• uptake: a 4-dimensional array (stk,flt,year,iter) containing the quota uptake by each fleet. The calculation is $quota - catch$, so quota underutilisation has a $+ve$ value whereas overshoot is $-ve$.
• overquota: a 4-dimensional array (stk,flt,year,iter) containing the quota over-shoot by each fleet.
• choke: a 3-dimensional array (flt,year,iter) containing a numeric code indicating the choke stock for each fleet in each year and iteration. The code refers to the position of the stock in ..., so if the second stock is the choke then the code is '2'.