3  The Operating Model: Classes and Components

openMSE organises all inputs in an OM object, the top-level container that holds all the components needed to run a simulation. The OM object is itself built from a hierarchy of S4 subcomponent objects, each responsible for a distinct aspect of the model.

Understanding this hierarchy is important for building, modifying, and interpreting operating models: what each subcomponent represents, what it contains, and how the pieces fit together.

The primary subcomponents of an OM object are Stock, Fleet, Obs, and Imp. Each of these is in turn a container for a set of lower-level subcomponent objects that carry the actual parameter values, described in detail in the sections below (Figure 3.1).

Tip

This chapter describes all of these classes and their contents and contains a lot of detail.

Readers may find it useful to skim through once to get a sense of the overall structure, then return here as a reference when they need details about a specific object or slot.

Figure 3.1: The primary components of an OM object. Solid arrows indicate required components; dashed arrows indicate optional components.

3.1 OM

An OM object is the top-level operating model. It holds one or more Stock objects and, for each stock, a corresponding set of Fleet, Obs, and Imp objects.

Key slots:

  • Stock: a stock-class object or named list of stock-class objects, one per stock in the operating model.
  • Fleet: a hierarchical named list of fleet-class objects, indexed first by stock then by fleet. Each stock must have the same number of fleets.
  • Obs: a hierarchical named list of obs-class objects, indexed first by stock complex then by fleet. Each element is itself a named list of obs-class objects, one per fleet, with optional additional elements for fishery-independent survey indices.
  • Imp: a hierarchical named list of imp-class objects, one per stock-fleet combination.
  • nSim: number of stochastic simulations. Determines the Sim dimension of all populated arrays.
  • nYear: number of historical years in the simulation.
  • pYear: number of projection years in the simulation.
  • CurrentYear: final calendar year of the historical period, used to label the Year dimension of all arrays.
  • Seasons: number of seasons per year. Default 1 (annual time steps).
  • Complexes: a named list defining stock complexes. Groups of stocks whose catch data are reported and managed jointly. Each element is an integer vector of stock indices belonging to that complex. If not specified, each stock is treated as its own complex.
  • Interval: management update interval in projection years. How frequently the management procedure is called to update advice. Default 1 (annual).
  • Data: a data-class object or named list of data-class objects, one per stock complex, containing the observed fishery data used to condition the operating model or inform management procedures. See Section 3.6 below for a summary of its structure, Chapter 6 for full details, and Chapter 7 for how it interacts with Obs objects.

3.2 Stock

A Stock object defines the biological and demographic characteristics of a fish population. It is composed of the following subcomponents:

3.2.1 Ages

Defines the discrete age structure of the population.

Key slots:

  • MaxAge: maximum age (required).
  • MinAge: youngest age class (default 0).
  • Units: the units of MaxAge and MinAge. One of: year, half-year, quarter, month, week. Determines temporal timestep of model. (default year).
  • PlusGroup: logical; if TRUE, all fish at or beyond MaxAge are aggregated into a plus-group. (default TRUE).
  • Classes: vector of age classes, derived automatically from the above. Always in units of year.

3.2.2 Length (technically optional)

Defines the mean length-at-age schedule.

Key slots:

  • Pars: named list of growth model parameters (e.g., Linf, K, t0 for von Bertalanffy).
  • Model: growth model function, inferred automatically from Pars if not specified; see ?LengthModels.
  • MeanAtAge: Sim × Age × Year array of mean length at age. Derived from Pars and Model if Pars is populated. Otherwise can be input by users directly.
  • CVatAge: coefficient of variation of length at age, used to generate the within-age length distribution.
  • ALK: age-length key, derived internally from MeanAtAge and CVatAge.
  • Classes: numeric vector of lower bounds of the length bins. If not supplied, bin boundaries are derived automatically from MeanAtAge and CVatAge to span the plausible range of lengths in the population.

See Chapter 16 for more details on populating Pars, MeanAt*, and CVatAge arrays.

TipTechnically Optional

Length is required in most operating models, but is technically optional: if Weight and other at-age schedules are populated directly via MeanAtAge (rather than derived from MeanAtLength), no ALK is needed for internal conversions, and neither OM@Data nor Obs specify any catch-at-length data, the model can run without a Length object.

3.2.3 Weight

Defines the mean weight-at-age and weight-at-length schedules.

Key slots:

  • Pars: named list of parameters (e.g., alpha, beta for an allometric relationship).
  • Model: weight model function; see ?WeightModels.
  • MeanAtAge: Sim × Age × Year array of mean weight at age.
  • MeanAtLength: Sim × Class × Year array of mean weight at length, where the Class dimension is length length(Classes).
  • Classes: numeric vector of lower bounds of the length bins corresponding with MeanAtLength. If not supplied, Classes from the Length component are used.
TipPars/Model/MeanAt*: a common pattern

The AtAge and AtLength schedules are specified either by supplying Pars and Model, or by providing MeanAtAge and/or MeanAtLength directly when Pars is an empty list.

When model-based, the model function populates either MeanAtAge or MeanAtLength depending on whether the model is age- or length-based. The other array is then back-calculated automatically using the age-length key (ALK) from the Length subcomponent.

When supplying arrays directly, either or both may be provided; if only one is given, the other is derived from the ALK in the same way.

This same pattern, supply Pars/Model or supply the array(s) directly, applies to all subcomponent objects that have MeanAtAge and/or MeanAtLength slots (e.g., NaturalMortality, Maturity, Fecundity, Selectivity, Retention). See Chapter 16 for full details on input formats and array dimension conventions.

3.2.4 NaturalMortality

Defines the natural mortality schedule, which may vary by age, length, simulation, and year.

Key slots:

  • Pars: named list of mortality model parameters (e.g., M for a constant rate).
  • Model: mortality model function; see ?NaturalMortalityModels
  • MeanAtAge: Sim × Age × Year array of instantaneous natural mortality at age.
  • MeanAtLength: Sim × Class × Year array of instantaneous natural mortality at length, where the Class dimension is length length(Classes).
  • Classes: numeric vector of lower bounds of the length bins corresponding with MeanAtLength. If not supplied, Classes from the Length component are used.

3.2.5 Maturity

Defines the maturity ogive, which may be expressed as a function of age or length.

Key slots:

  • Pars: named list of maturity model parameters (e.g., L50, L50_95 for a logistic curve)
  • Model: maturity model function; see ?MaturityModels
  • MeanAtAge: Sim × Age × Year array of maturity-at-age (0–1)
  • MeanAtLength: Sim × Class × Year array of maturity-at-length (0–1)
  • Semelparous: controls post-spawning mortality. See tip below.
  • Classes: numeric vector of lower bounds of the length bins corresponding with MeanAtLength. If not supplied, Classes from the Length component are used.
TipSemelparity

Setting Semelparous to TRUE sets post-spawning mortality equal to the maturity ogive; fully mature fish die after spawning with probability 1, fish on the ascending limb of the ogive die proportionally, and immature fish are unaffected.

A numeric array may also be supplied directly, allowing post-spawning mortality to be specified independently of the maturity schedule (e.g., to represent a species where only the oldest mature fish are semelparous or there is a lag between spawning and post-spawning mortality).

3.2.6 Fecundity (optional)

Defines egg production per individual as a function of age or length, and used to calculate the spawning production that is used by the stock-recruit relationship. When omitted, spawning production is set equal to spawning biomass.

Key slots:

  • Pars: named list of fecundity model parameters.
  • Model: fecundity model function; see ?FecundityModels.
  • MeanAtAge: Sim × Age × Year array of fecundity at age.
  • MeanAtLength: Sim × Class × Year array of fecundity at length.
  • Classes: numeric vector of lower bounds of the length bins corresponding with MeanAtLength. If not supplied, Classes from the Length component are used.

3.2.7 SRR

Defines the stock-recruitment relationship and recruitment process error.

Key slots:

  • Pars: named list containing the steepness parameter (e.g., list(h = ...) for Beverton-Holt).
  • Model: SRR function; defaults to "BevertonHolt"; see ?SRRModels.
  • R0: unfished equilibrium recruitment, used to set the scale of population numbers.
  • SD: log-space standard deviation of recruitment deviations.
  • AC: lag-1 autocorrelation of recruitment deviations.
  • TruncSD: number of standard deviations at which the recruitment deviation distribution is truncated. Default 2.
  • RecDevInit, RecDevHist, RecDevProj: recruitment deviations for the age-structure initialisation, historical, and projection periods, respectively. Generated automatically from SD and AC if not supplied; may be set directly to condition the model on known or estimated recruitment.
  • SpawnTimeFrac: fraction of the time step elapsed before spawning (0 = start, 1 = end).

3.2.8 Spatial (optional)

Defines spatial structure and movement dynamics. When omitted, a single well-mixed area is assumed.

Key slots:

  • UnfishedDist: equilibrium distribution of unfished biomass across areas. For two-area models, accepts a scalar or length-2 bounds vector (sampled from Uniform(lower, upper)). For models with more than two areas, a full Sim × Area × Age × Year array must be supplied.
  • ProbStaying: annual probability that an individual remains in its current area. Accepts the same input forms as UnfishedDist.
  • RelativeSize: relative habitat size of each area, used for spatial effort allocation. The special value "EqualDensity" sets sizes so that unfished biomass density is equal across areas.
  • Movement: Sim × FromArea × ToArea × Age × Year movement probability matrix, with rows summing to 1. Normally derived automatically during Populate() from UnfishedDist and ProbStaying. Can be supplied directly.

See Chapter 21 for more details on spatial structure.

3.2.9 Depletion (optional)

Defines the stock depletion at the start and/or end of the historical period. When omitted, the stock starts unfished and terminal depletion is determined by the fleet effort and catchability.

Key slots:

  • Initial: depletion at the first historical time step, relative to Reference. When specified, the model initialises the population at unfished equilibrium and then rescales numbers-at-age by a single multiplicative scalar, found by numerical optimisation, such that the resulting biomass matches the target depletion level.
  • Final: target depletion at the terminal historical time step, relative to Reference. When specified, fleet catchability is optimised to achieve this level. Typically only used for data-limited cases where terminal depletion is unknown and set to custom ranges.
  • Reference: reference biomass used to scale depletion (e.g., "B0", "SB0").

3.3 Fleet

A Fleet object defines the exploitation characteristics of a fishing fleet. A stock may be fished by one or more fleets, each with its own Fleet object. It is composed of the following subcomponents:

3.3.1 Effort

Defines the historical fishing effort trajectory and its spatial allocation.

Key slots:

  • Effort: historical effort as a Sim × Year array or a control-point data frame from which stochastic trajectories are generated; see ?GenHistEffort.
  • Units: units of fishing effort (e.g., "hours", "trips", or unitless).
  • Distribution: Sim × Year × Area array of the fraction of total effort allocated to each area, with values summing to 1 across the Area dimension within each simulation and year. Typically calculated internally by the spatial effort allocation algorithm each year based on relative exploitable biomass density and the Targeting parameter. Individual cells can be fixed to specific values by supplying a non-NA numeric, which overrides the internal algorithm for those simulation-year-area combinations while leaving the remainder to be calculated normally.
  • Targeting: Sim × Year targeting concentration parameter controlling how strongly effort is attracted to high-density areas.

3.3.2 Catchability

Defines gear efficiency and optional projected-year trends or stochasticity.

Key slots:

  • Efficiency: gear efficiency \(q\), which converts effort to instantaneous fishing mortality via \(F = q \cdot E\). May be left empty when Depletion@Final is specified, in which case it is back-calculated internally to match the specified depletion level.

3.3.3 Selectivity

Defines the probability of capture as a function of age or length.

Key slots:

  • Pars: named list of selectivity model parameters (e.g., L5, LFS, Vmaxlen for a double-normal curve)
  • Model: selectivity model function, inferred automatically from Pars; see ?SelectivityModels
  • MeanAtAge: Sim × Age × Year array of selectivity at age (0–1).
  • MeanAtLength: Sim × Class × Year array of selectivity at length (0–1).
  • Classes: numeric vector of lower bounds of the length bins corresponding with MeanAtLength. If not supplied, Classes from the corresponding stock’s Length component are used.

See Chapter 16 for more details on populating Pars and MeanAt* arrays.

3.3.4 Retention (optional)

Defines the probability of retention given capture, as a function of age or length. When omitted, all fish are assumed fully retained. Fish that are selected but not retained are treated as discards, and their fate is determined by DiscardMortality.

Has the same slot structure as Selectivity (Pars, Model, MeanAtAge, MeanAtLength, Classes).

3.3.5 DiscardMortality (optional)

Defines the proportion of discarded catch that dies, at age or at length. When omitted, all discarded fish are assumed to survive.

Key slots:

  • MeanAtAge: Sim × Age × Year array of discard mortality at age (0 = all survive, 1 = all die).
  • MeanAtLength: Sim × Class × Year array of discard mortality at length.
  • Classes: numeric vector of lower bounds of the length bins corresponding with MeanAtLength. If not supplied, Classes from the corresponding stock’s Length component are used.

3.3.6 WeightFleetRetained and WeightFleetSelected (optional)

Sim × Age × Year arrays of fleet-specific weight-at-age, used in fleet-level biomass calculations:

  • WeightFleetRetained for landed fish;
  • WeightFleetSelected for all fish encountered by the gear (retained and discarded).

These are relevant when the fleet’s catch has a different weight-at-age schedule from the overall stock.

When omitted (the default), both are computed automatically from the fleet’s Selectivity, Retention, and the stock’s weight-at-length schedule.

3.3.7 Closure (optional)

A Sim × Year × Area array of spatio-temporal area closures, with 1 indicating an open area and 0 a closed area for that simulation and year. When omitted, all areas are open in all years.

3.4 Obs (technically optional)

An Obs object defines the observation model for a single fleet: how each type of fishery data is collected, and the magnitude of sampling error and systematic bias applied to it. Each fleet has its own Obs object, itself a container of subcomponent objects: CatchObs, EffortObs, IndicesObs, and CompObs, each defining the error structure for one data type.

All sub-components are optional: if one (e.g., CatchObs) is left unpopulated, no data of that type is generated. Obs itself is optional at the OM level, but without it, and without a conditioning Data object, no data will be available to MPs (see the note in Chapter 2).

Obs interacts closely with Data objects: see Section 3.6 and Chapter 6 for the Data structure, and Chapter 7 for how Obs is conditioned from real data.

3.4.1 LifeHistory (not yet implemented)

Intended to define observation error for life-history parameters (growth, maturity, natural mortality, etc.), mirroring Data@LifeHistory. Not yet implemented.

3.4.2 Exploitation (not yet implemented)

Intended to define observation error for exploitation processes (selectivity, retention, discard mortality), mirroring Data@Exploitation. Not yet implemented.

3.4.3 CatchObs

Used for Obs@Landings and Obs@Discards. Defines lognormal observation error and multiplicative bias applied to simulated catch.

Key slots:

  • CV: coefficient of variation of lognormal observation error. Accepts:

    • NULL: no observation error unless Error is supplied directly.
    • Scalar: a single CV applied uniformly to all simulations.
    • Length-2 vector c(lower, upper): a unique CV per simulation drawn from Uniform(lower, upper).
    • Length-nSim vector: used directly.

    After population, @CV becomes a named [nSim] vector (one value per simulation) and @Error becomes a named [nSim × nYear] lognormal array drawn from those CVs.

  • Bias: multiplicative observation bias on the natural scale. Accepts:

    • NULL or empty: defaults to 1 (unbiased) for all simulations.
    • Scalar: treated as the CV of a lognormal distribution from which nSim unique bias values are drawn, centred at 1.
    • Length-nSim vector or named array: used directly, one bias value per simulation.

    After population, @Bias is a named [nSim] array of positive multipliers. The error applied to simulated catch in each simulation and year is Bias[sim] × Error[sim, year].

  • Error: optional pre-specified [nSim × nYear] lognormal multiplier array. When supplied, Error is used directly and CV is ignored.

  • Units: "Biomass" or "Number". Determines the units of the simulated catch data. Default NULL (treated as "Biomass"). Biomass uses WeightFleetRetained (see above). Number is catch in numbers (same units as the stock’s R0).

  • Years: calendar years of observed catch used when conditioning CV, Bias, and Error from real data. NULL (default) uses all available historical years. See Chapter 7.

3.4.4 EffortObs

Used for Obs@Effort. Has the same CV, Bias, Error, and Years slots as CatchObs, applied to simulated fishing effort. See ?EffortObs.

3.4.5 IndicesObs

Used for Obs@CPUE and Obs@Survey. Defines lognormal observation error on abundance indices, with optional autocorrelation.

Key slots:

  • CV: coefficient of variation of lognormal index error. Accepts the same forms as CatchObs@CV (scalar, length-2 bounds, or length-nSim array). After population, @CV is a named [nSim] vector and @Error is a named [nSim × nYear] lognormal array.

  • AC: lag-1 autocorrelation of index residuals, reflecting persistent deviations in survey catchability or other sources of correlated index error. Accepts:

    • NULL or empty: defaults to 0 (independent errors).
    • Scalar: constant autocorrelation applied to all simulations.
    • Length-2 vector c(lower, upper): a unique AC per simulation drawn from Uniform(lower, upper).
    • Length-nSim array: used directly.

  • Selectivity: controls how the simulated population is aggregated to produce the index:

    • NULL (default for CPUE): uses the fleet’s selectivity-at-age schedule.
    • "Biomass": flat selectivity across all ages (total biomass index).
    • "SBiomass": weights by maturity-at-age (spawning biomass index).
    • A custom Sim × Age × Year array may also be supplied for other selectivity schemes (e.g., surveys).

  • Units: "Biomass", "Number", or "Recruitment". Determines the units of the simulated index.

  • TruncSD: number of standard deviations at which the lognormal residual distribution is truncated when generating projection errors. Default 2.

  • Years: calendar years of observed index data used when conditioning CV, AC, and Error from real data. NULL (default) uses all available historical years. See Chapter 7.

  • Ref: reference index value, one per simulation. Used (together with Efficiency) when generating the reference index value in the corresponding Data object. Optional.

3.4.6 CompObs

Used for Obs@LandingsAtAge, Obs@DiscardsAtAge, Obs@LandingsAtSize, and Obs@DiscardsAtSize. Defines the sampling structure for age or length composition data via a Dirichlet-Multinomial model.

Key slots:

  • SampleSize: nominal number of fish aged or measured per year. Accepts:

    • NULL: suppresses generation of that composition data type entirely.
    • Scalar: constant across all simulations and years.
    • Length-2 vector c(lower, upper): a unique value per simulation drawn from Uniform(lower, upper), held constant across years.
    • Change-point matrix: see Chapter 16.

  • ESS: effective sample size. Controls the stochastic variability of the composition draw independently of the nominal SampleSize. Accepts the same input forms as SampleSize. Defaults to SampleSize when not specified. Values of ESS < SampleSize produce overdispersion relative to a pure multinomial.

  • Theta: Dirichlet-Multinomial dispersion parameter, in \((0, 1]\). Accepts the same input forms as SampleSize. Theta = 1 (default) recovers a standard multinomial draw. Values approaching 0 produce maximum overdispersion.

  • Shift: optional per-bin log-concentration offset, capturing systematic directional bias between observed and predicted compositions. NULL (default) applies no shift. See ?CompObs for details.

  • Years: calendar years of observed composition data used when conditioning SampleSize, ESS, Theta, and Shift from real data. NULL (default) uses all available historical years. See Chapter 7.

3.5 Imp (optional)

An Imp object defines the implementation error model, controlling how management recommendations are imperfectly applied in the operating model. When omitted, 100% compliance with management advice is assumed. Each of its subcomponents is an impslot object.

3.5.1 TAC

Implementation error for total allowable catch recommendations.

Key slots:

  • Mean: mean implemented fraction of the advised TAC.
  • SD: standard deviation of implementation error around Mean.
  • Error: realised implementation error, typically derived from Mean and SD during simulation.
  • Compliance: for multi-stock models, governs reconciliation of implementation error across stocks. Not otherwise used for single-stock models.

3.5.2 Effort

Implementation error for effort-based controls. Same slot structure as TAC (Mean, SD, Error, Compliance), applied to advised effort instead of TAC.

3.5.3 Size

Implementation error for size-based regulations (e.g., a minimum legal size).

Key slots:

  • Compliance: the fraction of the fleet that adopts a newly-advised size-based regulation (a change to Advice@Retention and/or Advice@Selectivity) in the year it changes, with the remainder of the fleet continuing under the prior (status-quo) schedule.
  • Mean, SD, Error: present in the impslot structure but not used for Size.

3.6 Data

A Data object stores observed or simulated fishery data: the real historical data optionally supplied to the OM (Chapter 2), and the data generated and accumulated by the Obs model over the course of a simulation. It is also the object passed to MP functions during the projection period. It is composed of the following subcomponents:

Key slots:

  • Name, CommonName, Species, Agency, Author, Email, Region, Latitude, Longitude: optional metadata identifying the stock and data source.
  • Years, YearLH, Seasons, nArea: the calendar years covered by the data, the last historical year (separating the historical from the projection period), the number of seasons per year, and the number of spatial areas.
  • Misc, Log: a named list for user-defined data, and an internal list used for diagnostic and audit logging.

Each of the data sub-object classes below (catchdata, effortdata, indicesdata, compdata) shares a similar Value/CV/Units pattern. See Chapter 6 for full slot-level documentation and Chapter 7 for how Data and Obs interact.

3.6.1 LifeHistory (not yet implemented)

A lifehistorydata object intended to hold observed/assumed biological parameters for the stock, generated via Obs@LifeHistory in the same way as the other Data slots are generated via their corresponding Obs sub-components.

Not yet implemented.

3.6.2 Exploitation (not yet implemented)

An exploitationdata object intended to hold observed/assumed exploitation processes for the fleet, generated via Obs@Exploitation in the same way as the other Data slots are generated via their corresponding Obs sub-components.

Not yet implemented.

3.6.3 Reference

A referencedata object holding MSY-based biological reference points, extending refpointsMSY.

Key slots:

  • FMSY, BMSY, SBMSY: fishing mortality, total biomass, and spawning biomass at MSY (Sim × Stock × Year).
  • SPMSY, SPRMSY: spawning production and spawning potential ratio at MSY (Sim × Stock × Year).
  • MSYLandings, MSYDiscards: landed catch and dead discards at MSY (Sim × Stock × Year).

3.6.4 Effort

An effortdata object with the observed fishing effort time series.

Key slots:

  • Name: fleet names, length nFleet.
  • Value: observed effort values, [nYear × nFleet].
  • CV: coefficients of variation matching the dimensions of Value.
  • Units: units of effort measurement per fleet (e.g., "hours", "trips").

3.6.5 Landings and Discards

catchdata objects with landed and discarded catch time series, respectively.

Key slots:

  • Name: fleet names, length nFleet.
  • Value: observed catch values, [nYear × nFleet].
  • CV: coefficients of variation matching the dimensions of Value.
  • Units: "Biomass" or "Number" per fleet, matching CatchObs@Units (see above).
  • Ref, RefCV: a reference catch value (e.g., a historical baseline) and its CV, matching the dimensions of Value.

3.6.6 CPUE and Survey

indicesdata objects with fishery-dependent and fishery-independent abundance indices, respectively.

Key slots:

  • Name: name of the index.
  • Value: observed index values, [nYear × nIndex].
  • CV: coefficients of variation for the index observations, matching the dimensions of Value.
  • Units: "Biomass", "Number", or "Recruitment" per index, matching IndicesObs@Units (see above).
  • Ref, RefCV: a reference value for each index (e.g., a historical mean or target level) and its CV.
  • Timing: within-year timing of each observation, as a fraction of the year (0-1).
  • Selectivity: an array or character specification mapping each index to a fleet selectivity, or defining an independent selectivity curve.

3.6.7 Composition data

compdata objects with age or size composition data, used for LandingsAtAge, DiscardsAtAge, LandingsAtSize, and DiscardsAtSize.

Key slots:

  • Name: fleet names, length nFleet.
  • Value: composition counts, [nYear × nFleet × nClass].
  • Classes: for age compositions, a numeric vector of class values (ages in years) shared by every fleet. For size compositions, a list of numeric vectors, one per fleet, giving that fleet’s own lower bounds of size bins.
  • Units: units of the class variable (e.g., "years", "cm", "mm"), shared by every fleet.