2  Overview of openMSE

This chapter introduces the terminology and primary objects and functions used in openMSE. Later chapters provide technical details and worked examples for each component.

2.1 Primary Objects and Functions

openMSE organises its inputs, outputs, and intermediate results into objects: structured containers that hold all the data and parameters relevant to a particular component of the model. Each object type has a defined set of slots and is automatically validated whenever it is created or modified, so objects are always internally consistent.

In practice, users rarely need to interact with the underlying object structure directly. Accessor and assignment functions (described in Section 2.2) provide a consistent interface for reading and modifying objects, and constructor functions handle the details of creating them correctly. The technical machinery behind this is R’s S4 object-oriented programming system; see the S4 chapter in Advanced R for more details, though familiarity with S4 is not required to use openMSE.

The primary objects and how they fit together are shown in Figure 2.1, with colors indicating the primary objects and the functions.

Figure 2.1: An overview of the primary objects and functions used in the MSE process. Solid arrows indicate the main workflow; dashed arrows indicate optional inputs. Note that Data appears twice: as an optional input to the OM (containing observed historical data) and as a dynamically updated object within the closed-loop projection (containing data generated by the Obs model for use by MP functions).

2.1.1 Historical and Projection Periods

The MSE process is divided into two periods.

The Historical period spans from the start of the fishery to the present day (or the most recent year of available data). Simulate reconstructs the population and fishery dynamics over this period, conditioning the model on any observed data and producing the Hist object that serves as the starting point for forward projections.

The Projection period begins from the terminal historical year and extends forward over a user-specified number of projection years. Project runs the closed-loop simulation over this period, applying each MP in turn and recording the resulting population and fishery dynamics in the MSE object. MP performance is evaluated over the projection period, making its length an important design choice: it should be long enough to capture the stock’s response to management under the range of uncertainty represented in the OM, and should encompass any time horizons specified in the management objectives (e.g., “probability recovered above \(B_{MSY}\) within 10 years”).

2.1.2 The OM Object

An Operating Model (OM) represents one hypothesis of the stock and fishery system. It is the central object in openMSE and is constructed from three required subcomponents and two optional ones:

  1. Stock: biological and demographic characteristics of the stock(s).
  2. Fleet: exploitation characteristics of the fishing fleet(s).
  3. Obs: the observation error model, describing how fishery data are collected and how much error and bias they contain.
  4. Imp (optional): the implementation error model, describing how management advice is imperfectly applied. When omitted, 100% compliance is assumed.
  5. Data (optional): real observed historical data from the fishery. When provided, it is used as the historical fishery data and to condition the Obs model so that simulated observations in the projection period match the statistical properties of the historical data.

See Chapter 3 for full details on the OM object and its subcomponents.

2.1.3 Simulate and the Hist Object

Simulate takes an OM object, runs the historical fishery simulation, and returns a Hist object. Beyond simulating population and fleet dynamics, Simulate also:

  • calculates unfished and MSY-based biological reference points;
  • optimises catchability (or initial depletion) to match depletion levels specified in the OM (if applicable);
  • conditions the Obs model on any historical Data provided in the OM, estimating observation error variance and bias from the residuals between simulated and observed data;
  • generates simulated fishery data for the historical period using the (conditioned) Obs model.

The resulting Hist object contains the complete historical simulation output, including population dynamics, fishery dynamics, reference points, and the historical Data object ready to be passed to MP functions.

2.1.4 The Data Object

Data objects serve two distinct roles in openMSE.

As an input to the OM: an optional Data object containing real observed historical data can be attached to the OM. This data is used directly as the historical fishery data and to condition the observation model (see above).

As the argument to MP functions: during the projection period, a Data object is updated at each management interval with the latest simulated observations generated by the OM and the Obs model. This is the object that MP functions receive and use to generate advice. It contains both the historical observations (either real or simulated) and the model-generated observations accumulated over the projection period to date.

2.1.5 Management Procedures and the Advice Object

A Management Procedure (MP) is a set of rules that takes fishery data as input and returns management advice.

In openMSE, MPs are R functions of class "mp" that accept a Data object and return an Advice object. The Advice object can specify any combination of:

  • catch limits (TAC), expressed as total removals or landings only in either biomass or numbers;
  • effort controls, as absolute or relative effort by fleet;
  • age- or size-based selectivity and retention adjustments;
  • discard mortality rates;
  • spatial closures.

Regulations can be specified at the stock or stock-complex level, and either applied uniformly across all fleets or set individually by fleet.

At each management interval in the projection period, the Data object is updated with new simulated observations, passed to the MP function, and the returned Advice is applied to the population. This cycle — simulate observations, generate advice, implement regulations, advance the population and fishery dynamics — repeats at every management interval for every MP being evaluated.

2.1.6 Project and the MSE Object

Project runs the closed-loop simulation across the projection period for all specified MPs, returning an MSE object. At its core, Project is the engine of the MSE: it repeatedly generates simulated observations, applies each MP to those observations, implements the resulting advice in the operating model, and advances the population forward, for every management interval and every simulation replicate.

The MSE object contains the full fishery dynamics from both the historical period (carried over from Hist) and the projection period, indexed by MP.

Quantities extracted from the MSE object can be used to calculate performance metrics, and results can be compared across MPs, simulations, stocks, fleets, and time.

2.2 Constructors, Accessors, and Assignment Functions

openMSE provides three families of functions for working with S4 objects.

2.2.1 Constructors

Constructor functions create new objects of a given class. Each primary class has a matching constructor of the same name:

myOM    <- OM(Name = 'My Operating Model')
myStock <- Stock(Name = 'My Stock')
myFleet <- Fleet(Name = 'My Fleet')
myObs   <- Obs(Name = 'My Observation Model')
myImp   <- Imp(Name = 'My Implementation Model')
myData  <- Data(Name = 'My Data')

The openMSE S4 class names are lowercase (om, stock, fleet, etc.), while the constructor functions that create them are uppercase (OM(), Stock(), Fleet(), etc.). The legacy uppercase classes (OM, Hist, MSE) still exist for backwards compatibility but are not covered in this manual. See Appendix B for details.

2.2.2 Accessors

Accessor functions retrieve a slot from an object and share their name with that slot:

Name(myOM)
[1] "My Operating Model"
nSim(myOM)
[1] 48

Accessors also work on nested objects. For example, SRR() retrieves the stock-recruitment relationship from a Stock object, but it also accepts an OM object directly, automatically extracting the Stock first:

# SRR object for `Example Albacore Stock`
stocks <- Stock(SingleStockOM)     
SRR(stocks$`Example Albacore Stock`) 

# list of SRR objects by stock (only one in this case)
SRR(Stock(SingleStockOM))         
SingleStockOM |> Stock() |> SRR() 

# shorthand approach
SRR(SingleStockOM)               
SingleStockOM |> SRR()

2.2.3 Assignment Functions

Assignment functions update a slot using R’s standard replacement-function syntax:

Name(myOM)  <- 'Updated Operating Model'
nSim(myOM)  <- 100
Stock(myOM) <- myStock
Fleet(myOM) <- myFleet
Important

Always use assignment functions rather than writing directly to slots with @. Many slots in openMSE objects depend on or are derived from other slots, and assignment functions trigger the necessary validation and recalculation to keep the object internally consistent. Direct @ assignment updates only the targeted slot and can leave the object in an incomplete or inconsistent state.