Package 'MSEtool'

Description

Generic accessor and replacement functions to retrieve and assign named slots from compatible S4 objects across the openMSE package ecosystem. Functions work on any S4 object that contains the corresponding slot.

Usage

AC(x)

AC(x) <- value

Beta(x)

Beta(x) <- value

Bias(x)

Bias(x) <- value

Classes(x)

Classes(x) <- value

Compliance(x)

Compliance(x) <- value

CPUE(x)

CPUE(x) <- value

CV(x)

CV(x) <- value

CVatAge(x)

CVatAge(x) <- value

Dist(x)

Dist(x) <- value

DiscardsAtAge(x)

DiscardsAtAge(x) <- value

DiscardsAtSize(x)

DiscardsAtSize(x) <- value

Error(x)

Error(x) <- value

Exploitation(x)

Exploitation(x) <- value

LandingsAtAge(x)

LandingsAtAge(x) <- value

LandingsAtSize(x)

LandingsAtSize(x) <- value

LifeHistory(x)

LifeHistory(x) <- value

Mean(x)

Mean(x) <- value

MeanAtAge(x)

MeanAtAge(x) <- value

MeanAtLength(x)

MeanAtLength(x) <- value

MeanAtWeight(x)

MeanAtWeight(x) <- value

Misc(x)

Misc(x) <- value

Model(x)

Model(x) <- value

Name(x)

Name(x) <- value

nSim(x)

nSim(x) <- value

nArea(x, st = 1)

nAge(x, st = NULL)

nComplex(x)

nStock(x)

nFleet(x)

Pars(x)

Pars(x) <- value

Period(x)

Period(x) <- value

Random(x)

Ref(x)

Ref(x) <- value

RefCV(x)

RefCV(x) <- value

Reference(x)

Reference(x) <- value

Size(x)

Size(x) <- value

SD(x)

SD(x) <- value

Survey(x)

Survey(x) <- value

Timing(x)

TruncSD(x)

TruncSD(x) <- value

Units(x)

Units(x) <- value

Value(x)

Value(x) <- value

YearLH(x)

YearLH(x) <- value

Arguments

Value

• Accessor functions return the value stored in the named slot of x.

• Replacement functions return x with the named slot updated to value.

Examples

MyLength <- Length()
MeanAtAge(MyLength)

Description

Applies an AR(1) auto-correlation structure to a vector of independent values, conditioning on a provided last observed value. The transformation scales each value to preserve the marginal variance under the AR(1) process.

Usage

AddAutoCorrelation(values, ac, last_value)

Arguments

Value

A numeric vector of the same length as values with AR(1) auto-correlation applied.

See Also

GenMultiStockRecDevs()

Description

Adds a new fleet to an om object, appending a fleet, an obs, and an imp object for every stock in the OM.

Usage

AddFleet(OM, FleetName, Fleet = NULL, Obs = NULL, Imp = NULL)

Arguments

Value

The om object with the new fleet appended to OM@Fleet and OM@Obs for every stock.

Examples

OM <- SingleStockOM
FleetNames(OM)
OM2 <- AddFleet(OM, 'DummyFleet')
FleetNames(OM2)

Description

addMMPs() adds additional management procedures to a MMSE object by combining multiple MMSE objects that have identical historical OM values, and population/ fleet structures.

Usage

addMMPs(MMSEobjs)

Arguments

Value

An object of class MMSE

Author(s)

Q. Huynh

See Also

addMPs()

Description

Construct an advice object defining management advice returned by a management procedure.

Usage

Advice(
  TAC = NULL,
  TACType = "Removals",
  TACUnit = "Biomass",
  Effort = NULL,
  EffType = "Rel",
  Closure = NULL,
  Selectivity = NULL,
  Retention = NULL,
  DiscardMortality = NULL,
  ApicalF = NULL,
  BagLimit = NULL,
  SpeciesLimit = NULL,
  LimitType = "angler",
  ClosureMode = "discard",
  Misc = list()
)

Arguments

Details

Advice() constructs a container for management regulations returned by a management procedure. All slots are optional; any regulation not supplied will remain unchanged from the previous time step.

The management regulations in an Advice object will be applied in the year/time-step that the Advice object is produced (i.e., when the MP is run) and will apply to all future time-steps until a new Advice object is returned by an MP.

The Closure, Selectivity, Retention, and DiscardMortality regulations (if any) are applied first before calculating the fishing mortality corresponding with TAC.

If both TAC and Effort regulations are returned, the expected fishing effort will be calculated to achieve a catch equal to the TAC. If the expected effort is greater than that set in Effort, the catch will be constrained to that corresponding with Effort. Otherwise, the actual fishing effort will be lower than Effort.

Valid Configurations for Management Regulations

There are several options for populating the slots in an Advice object:

TAC

Total allowable catch in units of "Biomass" (default) or "Number" (see TACUnit). TACType and TACUnit are each either length 1 (applied uniformly across all fleets) or a character vector of length nFleet specifying per-fleet values.

• single numeric value: global TAC distributed across the stocks and fleets in the Data() object according to Allocation(OM).

• numeric vector length nFleet: fleet-specific TAC.

Effort

Either in absolute units corresponding with fleet-specific effort (EffType = "Abs"), or relative to the effort in the last historical year (EffType = "Rel"; default). EffType is either length 1 (applied uniformly across all fleets) or a character vector of length nFleet specifying per-fleet values.

Note that when Effort is supplied as a matrix (fleet x area), it is always treated as absolute regardless of EffType.

• single numeric value:

  • If EffType="Rel": Effort relative to last historical year, applied to all fleets. E.g., if Effort=0.5, effort for all fleets will be set to half the effort in the last historical year.

  • If EffType="Abs": the total effort (summed over fleets unless provide as a length nFleet vector); Note that in this case all fleets in the OM must have the same units for Effort).

• numeric vector length nFleet: Fleet-specific relative or absolute Effort.

• numeric matrix: Fleet- and Area-specific relative or absolute Effort. Must have nFleet rows and nArea columns.

Closure

Can only be 0 (closed) or 1 (open). Otherwise will be converted to 0 (Closure<0.5) or 1

• vector length nArea

• matrix with nFleet rows and nArea columns: fleet-specific closures.

Selectivity

Either a Selectivity() object, or a list length nFleet of Selectivity objects.

If a single Selectivity object, the prescribed selectivity schedule is applied to all fleets.

See section below for more details.

Retention

Same as described for Selectivity, but for Retention() objects.

Discard Mortality

Same as described for Selectivity, but for DiscardMortality() objects.

Bag Limit

BagLimit, SpeciesLimit, LimitType, and ClosureMode together define a bag-limit regulation. The bag limit caps the number of fish an angler (or vessel) may retain per trip for either a single species or across all species within a complex.

BagLimit sets an aggregate limit across all species in the complex.

SpeciesLimit sets species-specific limits within the complex. Both may be active simultaneously, a trip is constrained whenever either limit is reached first. NA in a fleet position of BagLimit, or in a fleet-stock position of SpeciesLimit, means no limit applies for that fleet or fleet-stock combination respectively.

When ClosureMode = "discard", catch exceeding the retention cap is converted to discards and discard mortality is applied via the fleet's DiscardMortality() object. When ClosureMode = "stop", effort is reduced to prevent exceeding the bag limit and no additional discards are generated.

ApicalF

Not currently used.

Misc

A list of miscellaneous information that needs to be stored and accessed by the MP in future timesteps. Contents of Advice@Misc will be available in the Data@Misc slot in subsequent time steps.

Populating Selectivity, Retention, and Discard Mortality Objects

The Selectivity, Retention, and DiscardMortality objects are used to set the selectivity-, retention-, and discard mortality- at-age or -at-size schedules.

If values are provided for these slots in the Advice object, the new regulations/specifications will apply to all future time steps until modified again by the MP.

Values can be set for these objects in the following ways:

• MeanAtAge:

  • A numeric vector length nAge, where nAge is the number of age classes for the stock (or stocks) that are being managed by the MP.

  • For area-specific schedules, a numeric matrix with nAge rows and nArea columns.

• MeanAtLength:

  • A numeric vector length nClass, where nClass is the number of length classes for the stock (or stocks) that are being managed by the MP. The Classes slot can be used to set the size classes corresponding with MeanAtLength. Otherwise, the classes will be taken from the corresponding Length object in the OM(if they exist, otherwise an error).

  • For area-specific schedules, a numeric matrix with nClass rows and nArea columns.

• MeanAtWeight:

  • A numeric vector length nClass, where nClass is the number of weight classes for the stock (or stocks) that are being managed by the MP. The Classes slot can be used to set the size classes corresponding with MeanAtWeight. Otherwise, the classes will be taken from the corresponding Weight object in the OM (if they exist, otherwise an error).

  • For area-specific schedules, a numeric matrix with nClass rows and nArea columns.

• Pars and Model: for Selectivity and Retention only.

These slots can be used to set the age- or size-schedules using parameters and a model. See SelectivityModels() and RetentionModels() for a details of built-in models.

Pars should be a named list of parameters, where each parameter can be either a single numeric value, or a numeric vector length nArea for area-specific schedules.

Value

An advice object.

See Also

• advice for the class definition and slot-level documentation.

• Selectivity(), Retention(), DiscardMortality() for gear regulation sub-objects.

• TripsScalar(), AnglerPerTrip() for the effort-to-trips and angler-scaling parameters consumed by the bag limit model.

• Theta() for the within-trip catch overdispersion parameter.

Examples

Advice(TAC = 1000)

Advice(
  Effort  = c(1, 0.8),
  EffType = "Rel"
)

# Aggregate bag limit: 10 fish per angler per trip, discard excess
Advice(
  BagLimit    = 10,
  LimitType   = "angler",
  ClosureMode = "discard"
)

# Aggregate limit with a species-specific sub-limit 
# (2-fish sub-limit for stock 1)
Advice(
  BagLimit     = 10,
  SpeciesLimit = matrix(c(2, NA, NA, NA), nrow = 1, ncol = 4),
  LimitType    = "angler",
  ClosureMode  = "discard"
)

# Fleet-specific TAC & aggregate bag limits; no TAC for fleet 1, 
# no bag limit for fleet 2
Advice(
  TAC         = c(NA, 1000)
  BagLimit    = c(10, NA),
  LimitType   = "angler",
  ClosureMode = "discard"
)

Description

The advice class defines management advice produced by a management procedure. Advice may include output controls (e.g. total allowable catch), input controls (e.g. effort), spatial controls (closures), gear effects, direct fishing mortality rates, or bag-limit regulations. See Advice() for details on valid entries and options for each slot.

Slots

TAC

Numeric vector length 1 or numeric length nFleet specifying total allowable catch in units of TACUnit.

TACType

Character. Does the TAC refer to "Removals" (default) or "Landings". Either length 1 (applied to all fleets) or a character vector of length nFleet.

TACUnit

Character. Units of the TAC: "Biomass" (default) or "Number". Either length 1 (applied to all fleets) or a character vector of length nFleet.

Effort

Numeric vector length 1 or numeric length nFleet specifying relative or absolute fishing effort (in units of Fleet@Effort@Effort). Can also be a matrix with dimensions nFleet x nArea to set area-specific effort limits.

EffType

Character. Are effort regulations relative to last historical year ("Rel") or absolute ("Abs"; in units of Effort()). Either length 1 (applied to all fleets) or a character vector of length nFleet. Default is "Rel".

Closure

Numeric vector length nArea or array with dimensions nFleet x nArea specifyin an area open (1; default) or closed (0) to fishing.

Selectivity

A Selectivity() object or an nFleet long list of Selectivity() objects defining gear selectivity prescribed by the MP

Retention

A Retention() object or an nFleet long list of Retention() objects defining retention prescribed by the MP

DiscardMortality

A DiscardMortality() object or an nFleet long list of DiscardMortality() objects defining discard mortality set in the MP

ApicalF

Numeric array specifying target apical fishing mortality. Not currently used

BagLimit

Numeric vector or NULL. Aggregate bag limit in fish per angler per trip (when LimitType = "angler") or fish per vessel per trip (when LimitType = "boat"). Either length 1 (applied to all fleets) or a numeric vector of length nFleet for fleet-specific limits. NULL (default) means no bag limit regulation is active. NA for a given fleet position means no aggregate limit applies to that fleet. See Advice().

SpeciesLimit

Numeric matrix or NULL. Species-specific bag limits (fish per angler or vessel per trip) within a complex, with dimensions ⁠nFleet x nStock⁠. See Advice().

LimitType

Character or NULL. Specifies whether BagLimit and SpeciesLimit are per-angler ("angler"; default) or per-vessel ("boat") regulations. Either length 1 (applied to all fleets) or a character vector of length nFleet. See Advice().

ClosureMode

Character or NULL. Determines how the OM handles catch that exceeds the bag limit: "discard" (default) converts excess catch to discards, with discard mortality applied via the fleet's DiscardMortality() object; "stop" reduces effort to prevent the limit from being exceeded. Either length 1 (applied to all fleets) or a character vector of length nFleet. See Advice().

Misc

Miscellaneous list. Will be passed to Data@Misc in following time steps.

Log

List used internally to store diagnostics

See Also

Advice(), Selectivity(), Retention(), DiscardMortality()

Description

Stores management advice outputs generated during a model run or provided as input. Used in the Advice slot of a data object and accessed by LastTAC() when retrieving the most recent catch limit.

Usage

AdviceData()

Value

AdviceData() returns a advicedata object.

Slots

TAC

A numeric vector, array, or list of Total Allowable Catch (TAC) values. When a vector, elements correspond to successive advice years.

Effort

A numeric vector, array, or list of advised fishing effort values. Structured analogously to TAC.

Misc

A named list for any additional advice-level metadata (e.g., harvest control rule outputs, reference point comparisons).

AdviceData() creates a new advicedata object.

See Also

data, Data(), LastTAC()

Description

Construct an ages object defining the discrete age structure of a stock, or access and replace the Ages slot of a stock object and its individual slots.

Usage

Ages(MaxAge, MinAge = 0, Units = "year", PlusGroup = TRUE)

Ages(x) <- value

MaxAge(x)

MaxAge(x) <- value

MinAge(x)

MinAge(x) <- value

PlusGroup(x)

PlusGroup(x) <- value

Arguments

Details

Age Class Calculation

The Classes slot — a numeric vector of age classes expressed in years — is derived automatically from MinAge, MaxAge, and Units via CalcAgeClasses() and cannot be set directly. For seasonal models (Units != "year"), fractional year values are produced (e.g., 0, 0.25, 0.5, … for quarterly seasons with MinAge = 0). Retrieve the computed vector with Classes(x).

Plus Group

When PlusGroup = TRUE, the final age class absorbs all individuals at or beyond MaxAge. Mortality, growth, and selectivity at the plus-group age represent the average for that pooled cohort. Setting PlusGroup = FALSE treats MaxAge as an exact terminal age with no accumulation.

Uninitialised Objects

Calling Ages() without MaxAge returns an object with empty MaxAge and MinAge slots (numeric(0)). Validity checks are skipped for uninitialised objects, so they can be stored as placeholders inside a stock before parameters are specified. The model will not run until MaxAge is supplied.

Pass-Through Access from a Stock

When MaxAge is a stock object, Ages() acts as an accessor:

Ages(my_stock)          # returns my_stock@Ages
Ages(my_stock) <- a     # replaces my_stock@Ages with ages-class object `a`

Slot Accessors

Individual slots can be read or replaced using functions that match the slot names. All replacement functions re-validate the object after assignment:

MaxAge(a)        <- 20
MinAge(a)        <- 1
PlusGroup(a)     <- FALSE

Value

Ages() returns an ages object. If MaxAge is a stock, returns x@Ages.

⁠Ages<-⁠ returns the stock x with the Ages slot replaced by value and the object re-validated.

MaxAge(), MinAge(), PlusGroup() return the value of the corresponding slot from x.

⁠MaxAge<-⁠, ⁠MinAge<-⁠, ⁠PlusGroup<-⁠ return x with the named slot updated and the object re-validated.

See Also

ages for the class definition and slot-level documentation. Stock() for the enclosing stock constructor. ValidUnits() for accepted unit strings. Classes() to retrieve the derived age-class vector.

Other ages: ages-class

Examples

# Basic construction
a <- Ages(MaxAge = 20)
a

# Seasonal model: quarterly age classes
a_qtr <- Ages(MaxAge = 20, Units = "quarter")
Classes(a_qtr)

# No plus group
a_exact <- Ages(MaxAge = 20, PlusGroup = FALSE)

# Slot accessors
MaxAge(a)
MaxAge(a) <- 25

MinAge(a)
MinAge(a) <- 1

PlusGroup(a)
PlusGroup(a) <- FALSE

# Pass-through access from a stock
s <- Stock(Name = "Cod", Ages = Ages(MaxAge = 15))
Ages(s)
Ages(s) <- Ages(MaxAge = 20)

Description

Defines the discrete age structure of a stock object. Objects are typically created via Ages(), which documents all parameters and validates inputs.

Details

An object is considered uninitialised when MaxAge or MinAge is numeric(0).

Validity is enforced on non-empty objects: MaxAge and MinAge must be finite scalars, MinAge must be non-negative, MaxAge >= MinAge, and Units must be a scalar string accepted by ValidUnits().

Direct construction via methods::new() is not recommended; use Ages() instead, which populates Classes automatically.

Slots

MaxAge

numeric(1). Maximum age in units of Units. When PlusGroup = TRUE, fish older than this age are pooled into the plus group.

MinAge

numeric(1). Minimum (youngest) age class in units of Units. Must be non-negative and less than or equal to MaxAge.

Units

character(1). Time unit for MinAge and MaxAge. Must be one of the values returned by ValidUnits() (e.g., "year").

PlusGroup

logical(1). If TRUE, MaxAge is treated as an open-ended plus group that accumulates all fish at or beyond that age.

Classes

numeric. Vector of age classes in years, derived automatically from MinAge, MaxAge, and Units by CalcAgeClasses(). Not intended to be set directly; use Ages() to trigger recalculation.

See Also

• Ages() for the constructor and slot-accessor functions.

• stock for the enclosing object.

• ValidUnits() for accepted unit strings.

• Classes() to retrieve the computed age-class vector.

Other ages: Ages()

Description

An obs object representing a data-moderate scenario suitable for age-structured stock assessment. Landings, dicards, a fishery-independent survey, and annual age-composition samples from both landed and discarded fish are simulated.

Usage

AgeStructuredObs

Format

An obs object. Populated slots:

• Landings (catchobs): precisely reported landings with CV in ⁠[0.05, 0.10]⁠ and near-unbiased reporting ⁠[0.95, 1.05]⁠.

• Discards (catchobs): less precisely reported discards with CV in ⁠[0.15, 0.25]⁠ and near-unbiased reporting ⁠[0.95, 1.05]⁠.

• Survey (indicesobs): annual survey targeting spawning biomass with CV in ⁠[0.10, 0.20]⁠ and negligible autocorrelation ⁠[0.0, 0.1]⁠.

• LandingsAtAge (compobs): age-composition samples of landed fish from a port-sampling programme. Nominal sample size ⁠[200, 400]⁠ fish per year; ESS ⁠[50, 100]⁠ reflecting within-trip clustering; Dirichlet-Multinomial dispersion Theta in ⁠[0.5, 1.0]⁠.

• DiscardsAtAge (compobs): age-composition samples of discarded fish from at-sea observers. Nominal sample size ⁠[100, 200]⁠; ESS ⁠[30, 80]⁠; Theta in ⁠[0.4, 0.8]⁠, reflecting higher uncertainty relative to port sampling.

Empty slots (no data simulated): Effort, CPUE, LandingsAtSize, DiscardsAtSize.

See Also

obs, Obs(), CatchObs(), IndicesObs(), CompObs(), CatchAndSurveyObs, CommercialFleetObs, LengthStructuredObs, DataRichObs

Other obs-examples: CatchAndSurveyObs, CommercialFleetObs, DataRichObs, LengthStructuredObs

Examples

AgeStructuredObs
LandingsAtAge(AgeStructuredObs)
DiscardsAtAge(AgeStructuredObs)

Description

Example objects of class Stock

Usage

Albacore

Blue_shark

Bluefin_tuna

Bluefin_tuna_WAtl

Butterfish

Herring

Mackerel

Porgy

Rockfish

Snapper

Sole

Toothfish

Format

An object of class Stock of length 1.

An object of class Stock of length 1.

An object of class Stock of length 1.

An object of class Stock of length 1.

An object of class Stock of length 1.

An object of class Stock of length 1.

An object of class Stock of length 1.

An object of class Stock of length 1.

An object of class Stock of length 1.

An object of class Stock of length 1.

An object of class Stock of length 1.

An object of class Stock of length 1.

Examples

avail("Stock")

Description

Example objects of class MOM

Usage

Albacore_TwoFleet

Format

An object of class MOM of length 1.

Examples

avail("MOM")

Description

An example stock object representing an Albacore tuna (Thunnus alalunga) stock. This is a long-lived, slow-growing, large pelagic species with low natural mortality. See also ButterfishExStock for a contrasting short-lived, fast-growing example.

Usage

AlbacoreExStock

Format

A stock object with the following slots populated:

• Name: "AlbacoreExStock".

• CommonName: "Albacore".

• Species: "Thunnus alalunga".

• Ages: An Ages() object with MaxAge = 20 years.

• Length: A Length() object with von Bertalanffy parameters — Linf (121–135 cm), K (0.16–0.22 yr^-1^), t0 (-1.86 to -1.41 yr) — and CVatAge (0.1–0.15).

• Weight: A Weight() object with allometric parameters alpha = 1.34e-05 and beta = 3.106.

• NaturalMortality: A NaturalMortality() object with M = 0.35–0.45 yr^-1^.

• Maturity: A Maturity() object with logistic maturity-at-length parameters L50 (81–91 cm) and L50_95 (10–12 cm).

• Fecundity: An empty Fecundity() object; fecundity-at-age is computed internally during population (see Details).

• SRR: A SRR() object with Beverton-Holt steepness h (0.65–0.85), unfished recruitment R0 = 1000, recruitment variability SD (0.15–0.3), and autocorrelation AC (0.1–0.9).

• Spatial: A Spatial() object with UnfishedDist (0.095–0.105), ProbStaying (0.8–0.9), and RelativeSize (0.095–0.105).

• Depletion: A Depletion() object with current biomass sampled from 5–60% of B0.

• nYear, pYear, nSim, CurrentYear, Years, Seasons: Set by PopulateStock().

• Misc: Empty list for user-defined information.

• Log: Internal list for tracking object state.

Two-element numeric vectors in the slot descriptions above are uniform bounds. PopulateStock() samples from these bounds across simulations and expands the results into ⁠[nSim x nAge x nYear]⁠ arrays. The sections below describe what each component-level ⁠Populate*()⁠ function produces.

Ages

CalcAgeClasses() generates the integer age vector Ages@Classes (0:20), which is used as the age dimension in all subsequent arrays.

Length

PopulateLength() samples Linf, K, and t0 independently for each simulation from uniform distributions defined by the bounds, then computes mean length-at-age using the von Bertalanffy growth equation. CVatAge is expanded across simulations and, when ALK = TRUE, an age–length key is constructed.

See also LengthModels().

Weight

PopulateWeight() applies the allometric relationship W = alpha × L^beta^ to the mean length-at-age array to produce mean weight-at-age. An age–weight key is optionally constructed when AWK = TRUE.

See also WeightModels().

Natural Mortality

PopulateNaturalMortality() samples M for each simulation from the uniform bounds and expands the result into a natural mortality-at-age array. Stochastic annual deviates are added via PopulateRandom().

See also NaturalMortalityModels().

Maturity

PopulateMaturity() applies the logistic maturity-at-length curve, parameterised by L50 and L50_95, to the populated length-at-age array to produce a maturity-at-age array.

See also MaturityModels().

Fecundity

Because the Fecundity slot is empty, PopulateFecundity() computes fecundity-at-age as the element-wise product of weight-at-age and maturity-at-age, representing spawning output per individual.

See also FecundityModels().

Stock–Recruitment

PopulateSRR() samples h for each simulation from the uniform prior and generates a time series of log-normal recruitment deviates with standard deviation SD and autocorrelation AC.

Spatial

PopulateSpatial() samples UnfishedDist, ProbStaying, and RelativeSize for each simulation and uses them to construct a full inter-area movement matrix, then expands all spatial arrays across simulations and years. The relatively high ProbStaying (0.8–0.9) reflects low connectivity between the two areas.

See also SRRModels().

Depletion

PopulateDepletion() samples current biomass depletion relative to B0 for each simulation from the uniform prior, setting the initial conditions of the operating model.

See Also

ButterfishExStock, Stock(), PopulateStock(), Populate(), stock

Examples

AlbacoreExStock

## Not run: 
PopulatedStock <- PopulateStock(
  AlbacoreExStock,
  nYear = 50,
  pYear = 30,
  nSim = 48,
  seed = 42
)

## End(Not run)

Description

Applies AR(1) propagation to a numeric matrix of residuals (⁠sim x year⁠), respecting missing values (NAs). Autocorrelation is applied only across non-NA values within each simulation.

Usage

ApplyAC(LogResid, AC, LastError)

Arguments

Value

Numeric matrix of same dimensions as LogResid with autocorrelated residuals.

See Also

GenResiduals(), CalcResidualStats()

Description

Apply multi Management Procedures (class MMP) to a hierarchical list of Data class objects

Usage

applyMMP(
  DataList,
  MP = NA,
  reps = 1,
  nsims = NA,
  silent = FALSE,
  parallel = snowfall::sfIsRunning()
)

Arguments

Value

A hierarchical list of management recommendations (object class Rec), Fleets nested in Stocks

Description

Apply Management Procedures to an object of class Data

Usage

applyMP(
  Data,
  MPs = NA,
  reps = 100,
  nsims = NA,
  silent = FALSE,
  parallel = snowfall::sfIsRunning()
)

Arguments

Value

A list with the first element a list of management recommendations, and the second the updated Data object

Description

Array2DF() converts a matrix or array to a tidy data frame, with dimension names mapped to columns (Sim, Stock, Age, Year, Fleet, Area) and values in a Value column. Numeric columns are coerced with as.numeric(); Stock and Fleet are returned as ordered factors.

Usage

Array2DF(array)

DF2Array(DF)

Arguments

Details

DF2Array() is the inverse: it reshapes a tidy data frame back into a named array, using any columns whose names match Sim, Stock, Age, Year, Fleet, or Area as array dimensions.

Value

• Array2DF() returns a data.frame with one row per array element and one column per dimension plus a Value column.

• DF2Array() returns a named array whose dimensions and dimnames are derived from the unique values of the dimension columns in DF.

Examples

# Round-trip: array -> data frame -> array
a <- array(1:24, dim = c(2, 3, 4),
           dimnames = list(Sim = 1:2, Year = 1:3, Age = 1:4))
df <- Array2DF(a)
df
DF2Array(df)

Description

Multiply, divide, subtract, or add two arrays together.

Usage

ArraySum(array1, array2)

ArrayDivide(array1, array2)

ArrayMultiply(array1, array2)

ArraySubtract(array1, array2)

ArrayExtend(array1, array2)

ArrayFill(object) <- value

Arguments

Details

The arrays must have the same named dimensions, but do not need to have the same length for each dimension.

• ArraySum: Sum array1 and array2

• ArrayDivide: Divide array1 by array2

• ArrayMultiply: Multiply array1 and array2

• ArraySubtract: Subtract array2 from array1

• ArrayExtend: extends the arrays to have matching dimensions (see Extend())

• ArrayFill: Update array object with the values in value

Value

The resulting array

Examples

# Array with Sim, Year 
array1 <- array(1:20, 
                dim=c(2,5),
                dimnames = list(
                  Sim=1:2,
                  Year=2021:2025
                ))

array2 <- array(1:20, 
                dim=c(1,3),
                dimnames = list(
                  Sim=1,
                  Year=2024:2026
                ))

ArrayExtend(array1, array2)

ArraySum(array1, array2)
ArrayDivide(array1, array2)
ArrayMultiply(array1, array2)
ArraySubtract(array1, array2)



# Array with Age, Year 
array1 <- array(1:20, 
                dim=c(5,2),
                dimnames = list(
                  Age=1:5,
                  Year=2021:2022
                ))

array2 <- array(1:20, 
                dim=c(1,3),
                dimnames = list(
                  Age=1,
                  Year=2024:2026
                ))

ArrayExtend(array1, array2)

ArraySum(array1, array2)
ArrayDivide(array1, array2)
ArrayMultiply(array1, array2)
ArraySubtract(array1, array2)


# ArrayFill

## Same dimensions
object <- array(NA, 
               dim=c(3,5),
               dimnames=list(Sim=1:3,
                             Year=2021:2025)
)

value <- array(1:2, 
               dim=c(1,2),
               dimnames=list(Sim=2,
                             Year=2022:2023)
)

ArrayFill(object) <- value
object


## Extend Dimensions
object <- array(NA, 
                dim=c(3,5),
                dimnames=list(Sim=1:3,
                              Year=2021:2025)
)

value <- array(1:12, 
               dim=c(3,4),
               dimnames=list(Sim=1:3,
                             Year=c(2019, 2025:2027))
)

ArrayFill(object) <- value
object

Description

Reads a fitted ASAP model and uses the MLE estimates with identical reconstruction among simulations. Future recruitment is sampled from a lognormal distribution with autocorrelation. ASAP2Data imports a Data object.

Usage

ASAP2OM(
  asap,
  nsim = 48,
  proyears = 50,
  mcmc = FALSE,
  spawn_time_frac = 0,
  Name = "ASAP Model",
  Source = "No source provided",
  nyr_par_mu = 3,
  Author = "No author provided",
  report = FALSE,
  silent = FALSE
)

ASAP2Data(asap, Name = "ASAP assessment")

Arguments

Details

Length at age is not used in ASAP so arbitrary placeholder values are used for length-based parameters. Update these parameters to model length in the operating model.

Value

An operating model OM class.

Author(s)

Q. Huynh

See Also

Assess2OM

Description

A function that develops a multiple fleet operating model (MOM) and either models a unisex or 2-sex stock from arrays of abundance, fishing mortality, and biological parameters. The user still needs to parameterize most of the observation and implementation portions of the operating model.

Usage

Assess2MOM(
  Name = "MOM created by Assess2MOM",
  proyears = 50,
  interval = 2,
  CurrentYr = as.numeric(format(Sys.Date(), "%Y")),
  h = 0.999,
  Obs = MSEtool::Imprecise_Unbiased,
  Imp = MSEtool::Perfect_Imp,
  naa,
  faa,
  waa,
  Mataa,
  Maa,
  laa,
  fecaa,
  nyr_par_mu = 3,
  LowerTri = 1,
  recind = 0,
  plusgroup = TRUE,
  altinit = 0,
  fixq1 = TRUE,
  report = FALSE,
  silent = FALSE,
  ...
)

Arguments

Details

Use a seed for the random number generator to sample future recruitment.

Value

An object of class MOM

Author(s)

Q. Huynh

See Also

SS2MOM multiMSE Assess2OM

Description

A function that uses a set of bootstrap estimates of numbers-at-age, fishing mortality rate-at-age, M-at-age, weight-at-age, length-at-age and Maturity-at-age to define a fully described MSEtool operating model. The user still needs to parameterize most of the observation and implementation portions of the operating model.

Usage

Assess2OM(
  Name = "A fishery made by VPA2OM",
  proyears = 50,
  interval = 2,
  CurrentYr = as.numeric(format(Sys.Date(), "%Y")),
  h = 0.999,
  Obs = MSEtool::Imprecise_Unbiased,
  Imp = MSEtool::Perfect_Imp,
  naa,
  faa,
  waa,
  Mataa,
  Maa,
  laa,
  nyr_par_mu = 3,
  LowerTri = 1,
  recind = 0,
  plusgroup = TRUE,
  altinit = 0,
  fixq1 = TRUE,
  report = FALSE,
  silent = FALSE,
  ...
)

VPA2OM(
  Name = "A fishery made by VPA2OM",
  proyears = 50,
  interval = 2,
  CurrentYr = as.numeric(format(Sys.Date(), "%Y")),
  h = 0.999,
  Obs = MSEtool::Imprecise_Unbiased,
  Imp = MSEtool::Perfect_Imp,
  naa,
  faa,
  waa,
  Mataa,
  Maa,
  laa,
  nyr_par_mu = 3,
  LowerTri = 1,
  recind = 0,
  plusgroup = TRUE,
  altinit = 0,
  fixq1 = TRUE,
  report = FALSE,
  silent = FALSE,
  ...
)

Arguments

Details

Use a seed for the random number generator to sample future recruitment.

Value

An object of class OM.

Author(s)

T. Carruthers

See Also

SS2OM iSCAM2OM WHAM2OM ASAP2OM

Description

An example fleet object demonstrating a fleet with effort that stabilises early in the historical period and asymptotic length-based selectivity. Intended for use with AlbacoreExStock or ButterfishExStock to illustrate fleet parameterization in MSEtool. See also DomeExFleet for a contrasting dome-shaped selectivity example.

Usage

AsympExFleet

Format

A fleet object with the following slots populated:

• Name: "AsympExFleet". Unique fleet identifier.

• Effort: An Effort() object with a piecewise-linear historical effort trajectory defined at four relative time points (0, 0.3, 0.6, 1.0), with lower and upper bounds of (0, 0.4, 1, 1) and (0, 0.6, 1, 1) respectively, and CV = 0.1 controlling stochastic variation around the trend.

• Selectivity: A Selectivity() object with asymptotic length-based selectivity parameters — L5 (0.4–0.5), LFS (0.7–0.8), and Vmaxlen = 1 (fixed) — with isRel = TRUE indicating that L5 and LFS are expressed relative to maturity L50.

• Catchability: An empty Catchability() object; efficiency defaults to 1 across all years during population (see Details).

• Retention: An empty Retention() object; full retention is assumed during population (see Details).

• DiscardMortality: An empty DiscardMortality() object.

• Closure: NULL. No spatial or temporal closures defined.

• WeightFleet: NA. Fleet-specific weight-at-age is set to the stock weight-at-age during population (see Details).

• Bioeconomic: An empty Bioeconomic() object.

• nYear, pYear, nSim, CurrentYear, Years, Seasons: Inherited from the paired Stock() object by PopulateFleet().

• Misc: Empty list for user-defined information.

Details

PopulateFleet() expands the input parameters into ⁠[nSim x nAge x nYear]⁠ arrays using the age, length, and spatial structure of the paired populated stock. The sections below describe what each component-level ⁠Populate*()⁠ function produces.

Effort

PopulateEffort() interpolates the piecewise-linear effort trajectory across all historical years for each simulation, then applies log-normal stochastic deviates scaled by CV = 0.1. The trajectory rises from 0 to 40–60% of maximum effort by 30% of the historical period, then reaches full effort by 60% of the period and remains stable thereafter. This contrasts with DomeExFleet, where effort continues to rise through to the final historical year.

Catchability

Because the Catchability slot is empty, PopulateCatchability() sets catchability efficiency to 1 across all simulations and years. No trend (qInc) or inter-annual variability (qCV) is applied.

Selectivity

PopulateSelectivity() samples L5 and LFS for each simulation from uniform distributions defined by the prior bounds. Because isRel = TRUE, both are scaled by the maturity L50 of the paired stock before computing the selectivity curve. Vmaxlen = 1 is fixed, so selectivity reaches 1.0 at maximum length in all simulations, producing a strictly asymptotic curve. The resulting selectivity-at-length is converted to selectivity-at-age using the stock age–length key, and an area dimension is added.

Retention

Because the Retention slot is empty, PopulateRetention() sets full retention (1.0) across all ages, lengths, simulations, and years.

Discard Mortality

Because the DiscardMortality slot is empty, PopulateDiscardMortality() applies default discard mortality values. All discarded fish are assumed to survive (discard mortality = 0) unless overridden.

Spatial Closures

Because Closure is NULL, PopulateClosure() applies no spatial or temporal closures; all areas are open to fishing in all years.

Fleet Weight-at-Age

Because WeightFleet is NA, PopulateFleet() sets it equal to the stock mean weight-at-age array, so fleet-level biomass calculations use the same weight schedule as the stock.

See Also

DomeExFleet, AlbacoreExStock, ButterfishExStock, Fleet(), PopulateFleet(), Populate(), fleet

Examples

AsympExFleet

## Not run: 
PopulatedStock <- PopulateStock(AlbacoreExStock, nYear = 50, pYear = 30, nSim = 48)
PopulatedFleet <- PopulateFleet(AsympExFleet, Stock = PopulatedStock, seed = 42)

## End(Not run)

Description

Example objects of class Data

Usage

Atlantic_mackerel

China_rockfish

Cobia

Example_datafile

Gulf_blue_tilefish

ourReefFish

Red_snapper

Simulation_1

Format

An object of class Data of length 1.

An object of class Data of length 1.

An object of class Data of length 1.

An object of class Data of length 1.

An object of class Data of length 1.

An object of class Data of length 1.

An object of class Data of length 1.

An object of class Data of length 1.

Examples

avail("Data")

Description

Generic class finder

Usage

avail(classy, package = NULL, msg = TRUE, abc = FALSE)

Arguments

Details

Finds objects of the specified class in the global environment or the openMSE packages.

Author(s)

T. Carruthers

See Also

Can Cant avail

Examples

avail("OM", msg=FALSE)
Stocks <- avail("Stock")
Fleets <- avail("Fleet")
MPs <- avail("MP")

Description

A function that generates an operating model from the MCMC samples of an Awatea model. Code optimized for the BC Pacific ocean perch assessment (Haigh et al. 2018).

Usage

Awatea2OM(
  AwateaDir,
  nsim = 48,
  proyears = 50,
  Name = "OM made by Awatea2OM",
  Source = "No source provided",
  Author = "No author provided",
  verbose = TRUE
)

Arguments

Details

This function averages biological parameters across sex and then sends arrays to VPA2OM, assumes unfished status (B/B0 = 1) in the first year, and assumes a single fishing fleet.

Author(s)

Q. Huynh and T. Carruthers

References

Haigh, R., et al. 2018. Stock assessment for Pacific Ocean Perch (Sebastes alutus) in Queen Charlotte Sound, British Columbia in 2017. Canadian Science Advisory Secretariat (CSAS) Research Document 2018/038. 232 pp. https://www.dfo-mpo.gc.ca/csas-sccs/Publications/ResDocs-DocRech/2018/2018_038-eng.html

Description

Import a multi-stock, multi-fleet OM from a BAM object

Usage

BAM2MOM(
  rdat,
  nsim = 48,
  proyears = 50,
  interval = 1,
  stock_name = NULL,
  fleet_name = NULL,
  LowerTri = 0,
  report = FALSE,
  ...
)

BAM2OM(rdat, nsim = 48, proyears = 50, interval = 2, report = FALSE, ...)

Arguments

Value

An object of class MOM

Functions

• BAM2OM(): Create a single stock/fleet OM from a BAM object

Description

GetBAMFleetNames() extracts and classifies fleet names from a BAM stock assessment, separating retained (landings) fleets from discard fleets. FixFleetNames() is a helper that standardises raw BAM fleet name strings by stripping leading "L." prefixes and converting leading "D." prefixes to trailing ".D" suffixes.

Usage

GetBAMFleetNames(Stock)

FixFleetNames(FleetNames)

Arguments

Value

GetBAMFleetNames() returns a named list with four elements:

• ⁠$FleetNames⁠: character vector of all fleet names, cleaned via FixFleetNames().

• ⁠$RetainFleets⁠: character vector of landings (retained catch) fleets, i.e. all fleets not classified as discard fleets.

• ⁠$DiscardFleets⁠: character vector of discard fleets, identified as those ending in ".D" or, if none found, starting with "D.".

• ⁠$FleetNamesOrig⁠: character vector of original fleet names as they appear in BAMdata$parms, before cleaning.

FixFleetNames() returns a character vector the same length as FleetNames with standardised names.

See Also

GetBAMOutput()

Examples

## Not run: 
GetBAMFleetNames('Red Snapper')

## End(Not run)

FixFleetNames(c('L.cHL', 'D.rHB', 'cPT'))

Description

Biomass(), SBiomass(), and SProduction() extract total biomass, spawning biomass, and spawning production, respectively, from a hist or mse object.

Usage

Biomass(
  object,
  df = TRUE,
  byAge = FALSE,
  byArea = FALSE,
  Reduce = TRUE,
  IncYear = FALSE
)

SBiomass(
  object,
  df = TRUE,
  byAge = FALSE,
  byArea = FALSE,
  Reduce = TRUE,
  IncYear = FALSE
)

SProduction(
  object,
  df = TRUE,
  byAge = FALSE,
  byArea = FALSE,
  Reduce = TRUE,
  IncYear = FALSE
)

Arguments

Details

When applied to an mse object the historical and projection periods are row-bound and labelled via the Period column; historical rows carry MP = "Historical".

Value

• df = FALSE — the raw array slot (Biomass, SBiomass, or SProduction).

• df = TRUE — a tidy data.frame with columns Sim, Stock, Year, Period, MP (MSE only), and optionally Age / Area, plus Value, Variable, and Units.

See Also

Number()

Examples

Hist <- Simulate(SingleStockOM)
MSE <- Project(Hist, 'CurrentEffort')

# Raw array
Biomass(Hist)
Biomass(MSE)

# Tidy data frames
Biomass(Hist, df = TRUE)
Biomass(MSE,  df = TRUE)

# Retain age and area structure
Biomass(MSE, df = TRUE, byAge = TRUE)
Biomass(MSE, df = TRUE, byArea = TRUE)
Biomass(MSE, df = TRUE, byAge = TRUE, byArea = TRUE)

# Spawning biomass and production follow the same structure
SBiomass(MSE, df = TRUE, byAge = TRUE)
SProduction(MSE, df = TRUE, byArea = TRUE)

Description

Construct and manipulate a bioeconomic object storing revenue, cost, and investment dynamics for fleet-level or stock-level bioeconomic analyses.

Usage

Bioeconomic(
  Revenue = NULL,
  Cost = NULL,
  Investment = NULL,
  Disinvestment = NULL,
  Depreciation = NULL,
  Discount = NULL,
  Misc = list()
)

Bioeconomic(x) <- value

Revenue(x)

Revenue(x) <- value

Cost(x)

Cost(x) <- value

Investment(x)

Investment(x) <- value

Disinvestment(x)

Disinvestment(x) <- value

Depreciation(x)

Depreciation(x) <- value

Discount(x)

Discount(x) <- value

Arguments

Details

Note: The bioeconomic is not currently used by the MSE framework. It is included for future development and is available for custom analyses outside the standard model loop.

A bioeconomic object stores parameters and outputs for fleet-level bioeconomic modelling, including revenue, effort costs, and discounting. All slots are optional and default to NULL.

This class is not currently used by the MSE framework. It is included for future development.

Attaching to a Fleet

A bioeconomic object can be attached to a Fleet() with Bioeconomic(Fleet) <- MyBioeconomic and retrieved with Bioeconomic(Fleet).

Individual slots may be accessed or modified using Revenue(), Cost(), Investment(), Disinvestment(), Depreciation(), and Discount().

Value

• Bioeconomic() returns a bioeconomic object. If Revenue is a fleet object, the Bioeconomic slot of that fleet is returned.

• ⁠Bioeconomic<-⁠ returns x with the Bioeconomic slot replaced by value.

• Revenue(), Cost(), Investment(), Disinvestment(), Depreciation(), Discount() return the corresponding slot from x.

• Their replacement forms return x with the corresponding slot updated.

See Also

• bioeconomic for the class definition and slot-level documentation.

• Fleet() for the enclosing fleet constructor.

Other fleet: Catchability(), DiscardMortality(), Effort(), Fleet(), Retention(), Selectivity(), bioeconomic-class, catchability-class, discardmortality-class, effort-class, fleet-class, retention-class, selectivity-class

Examples

b <- Bioeconomic(Cost = 100, Discount = 0.05)
Cost(b)
Cost(b) <- 200
Discount(b)

# Attach to a Fleet
f <- Fleet(Name = "Trawl")
Bioeconomic(f) <- Bioeconomic(Cost = 100, Investment = 500, Discount = 0.05)
Cost(Bioeconomic(f))
Discount(Bioeconomic(f))

Description

Stores revenue, cost, and investment dynamics for fleet-level or stock-level bioeconomic analyses. Objects are typically created via the Bioeconomic() constructor, which documents all parameters in detail.

Details

Note: The bioeconomic is not currently used by the MSE framework. It is included for future development.

Slots

Revenue

numeric array or NULL. Revenue by simulation, fleet, and year. See Bioeconomic().

Cost

numeric or NULL. Operating cost per unit of effort. See Bioeconomic().

Investment

numeric or NULL. Cost of adding a unit of effort. See Bioeconomic().

Disinvestment

numeric or NULL. Cost of removing a unit of effort. See Bioeconomic().

Depreciation

numeric or NULL. Depreciation rate of effort units. See Bioeconomic().

Discount

numeric or NULL. Discount factor applied to future values. See Bioeconomic().

Misc

list. Miscellaneous additional inputs.

See Also

Bioeconomic() for the constructor and full parameter documentation. fleet for the enclosing fleet object.

Other fleet: Bioeconomic(), Catchability(), DiscardMortality(), Effort(), Fleet(), Retention(), Selectivity(), catchability-class, discardmortality-class, effort-class, fleet-class, retention-class, selectivity-class

Description

Boxplot of TAC recommendations

Usage

## S3 method for class 'Data'
boxplot(x, upq = 0.9, lwq = 0.1, ylim = NULL, outline = FALSE, col = NULL, ...)

Arguments

Value

Returns a data frame containing the information shown in the plot

Author(s)

A. Hordyk

Description

An example stock object representing a Butterfish (Peprilus triacanthus) stock. This is a short-lived, fast-growing forage species with high natural mortality and wide uncertainty on recruitment and maturity. See also AlbacoreExStock for a contrasting long-lived, slow-growing example.

Usage

ButterfishExStock

Format

A stock object with the following slots populated:

• Name: "ButterfishExStock".

• CommonName: "Butterfish".

• Species: "Peprilus triacanthus".

• Ages: An Ages() object with MaxAge = 8.

• Length: A Length() object with von Bertalanffy parameters — Linf (38–42 cm), K (0.16–0.24 yr^-1^), t0 (-0.032 to -0.028 yr) — and CVatAge (0.1–0.15).

• Weight: A Weight() object with allometric parameters alpha = 1.59e-05 and beta = 3.1.

• NaturalMortality: A NaturalMortality() object with M = 0.7–0.9 yr^-1^.

• Maturity: A Maturity() object with logistic maturity-at-length parameters L50 (4.5–10.2 cm) and L50_95 (1–8 cm). The wide ranges reflect substantial uncertainty in maturity schedule.

• Fecundity: An empty Fecundity() object; fecundity-at-age is computed internally during population (see Details).

• SRR: A SRR() object with Beverton-Holt steepness h (0.4–0.8), unfished recruitment R0 = 1000, recruitment variability SD (0.7–1.1), and autocorrelation AC (0.1–0.9). The high SD reflects the characteristically variable recruitment of forage species.

• Spatial: A Spatial() object with UnfishedDist (0.095–0.105), ProbStaying (0.4–0.6), and RelativeSize (0.095–0.105).

• Depletion: A Depletion() object with current biomass sampled from 5–60% of B0.

• nYear, pYear, nSim, CurrentYear, Years, Seasons: Set by PopulateStock().

• Misc: Empty list for user-defined information.

• Log: Internal list for tracking object state.

Details

Two-element numeric vectors in the slot descriptions above are uniform bounds. PopulateStock() samples from these bounds across simulations and expands the results into ⁠[nSim x nAge x nYear]⁠ arrays. The sections below describe what each component-level ⁠Populate*()⁠ function produces.

Ages

CalcAgeClasses() generates the age vector Ages@Classes (0:8), which is used as the age dimension in all subsequent arrays.

Length

PopulateLength() samples Linf, K, and t0 independently for each simulation from uniform distributions defined by the bounds, then computes mean length-at-age using the von Bertalanffy growth equation. CVatAge is expanded across simulations and, when ALK = TRUE, an age–length key is constructed.

Weight

PopulateWeight() applies the allometric relationship W = alpha × L^beta^ to the mean length-at-age array to produce mean weight-at-age. An age–weight key is optionally constructed when AWK = TRUE.

Natural Mortality

PopulateNaturalMortality() samples M for each simulation from the uniform prior and expands the result into a natural mortality-at-age array. Stochastic annual deviates are added via PopulateRandom(). The high M range (0.7–0.9 yr^-1^) is consistent with the short lifespan of this species.

Maturity

PopulateMaturity() applies the logistic maturity-at-length curve, parameterised by L50 and L50_95, to the populated length-at-age array to produce a maturity-at-age array. The wide priors on both parameters result in high inter-simulation variability in the maturity schedule.

Fecundity

Because the Fecundity slot is empty, PopulateFecundity() computes fecundity-at-age as the element-wise product of weight-at-age and maturity-at-age, representing spawning output per individual.

Stock–Recruitment

PopulateSRR() samples h for each simulation from the uniform prior and generates a time series of log-normal recruitment deviates with standard deviation SD and autocorrelation AC. The high SD (0.7–1.1) produces strongly variable recruitment, typical of forage fish.

Spatial

PopulateSpatial() samples UnfishedDist, ProbStaying, and RelativeSize for each simulation and uses them to construct a full inter-area movement matrix, then expands all spatial arrays across simulations and years. The moderate ProbStaying (0.4–0.6) allows substantial mixing between the two areas.

Depletion

PopulateDepletion() samples current biomass depletion relative to B0 for each simulation from the uniform prior, setting the initial conditions of the operating model.

See Also

AlbacoreExStock, Stock(), PopulateStock(), Populate(), stock

Examples

ButterfishExStock

## Not run: 
PopulatedStock <- PopulateStock(
  ButterfishExStock,
  nYear = 50,
  pYear = 30,
  nSim = 48,
  seed = 42
)

## End(Not run)

Description

Computes the numeric vector of age classes (in years) from an Ages() object, respecting sub-annual time steps.

Usage

CalcAgeClasses(Ages)

Arguments

Details

Age classes are always expressed in years, regardless of the time unit used to define MinAge and MaxAge. Units controls the within-year resolution via CalcSeasons(), which maps unit strings to a seasons divisor:

The sequence runs from MinAge / Seasons to MaxAge / Seasons in steps of 1 / Seasons, rounded to three decimal places.

Returns NULL if Units, MinAge, or MaxAge are not set.

Value

A numeric vector of age classes in years, or NULL if any of Ages@Units, Ages@MinAge, or Ages@MaxAge are empty.

See Also

Ages(), ages, PopulateStock()

Examples

# Annual age classes 0–5
CalcAgeClasses(Ages(MinAge = 0, MaxAge = 5, Units = "year"))
#> [1] 0 1 2 3 4 5

# Quarterly age classes 0–1
CalcAgeClasses(Ages(MinAge = 0, MaxAge = 4, Units = "quarter"))
#> [1] 0.00 0.25 0.50 0.75 1.00

Description

Generates an Age-Size key given mean and standard deviation of size-at-age. The size-at-age can be normally or log-normally distributed. By default the distribution is truncated at 2 standard deviations.

Usage

CalcAgeSizeKey(
  MeanAtAge,
  CVatAge,
  Classes,
  TruncSD = 2,
  Dist = c("normal", "lognormal"),
  silent = FALSE,
  type = "Length"
)

Arguments

Value

A 4D array with dimensions Sim, Age, Class, and Year.

Examples

nSim <- 5
nAge <- 15
nYear <- 2
ages <- 0:(nAge-1)
years <- 2001:2002

TruncSD <- 2
Dist <- 'normal'

set.seed(123)
Linf <- runif(nSim, min = 150, max = 200)
K <- 0.3      
t0 <- 0   

MeanAtAge <- array(0, 
                   dim = c(nSim, nAge, nYear),
                   dimnames = list(Sim = 1:nSim, Age = ages, Year = years))

for (sim in 1:nSim) {
  for (yr in 1:nYear) {
    MeanAtAge[sim, , yr] <- Linf[sim] * (1 - exp(-K * (ages - t0)))
  }
}

# Coefficient of variation (CV)
CVatAge <- array(0.1, dim = dim(MeanAtAge), dimnames = dimnames(MeanAtAge))

# Define size classes
SDatAge <- MeanAtAge * CVatAge
class_min <- floor(min(MeanAtAge - TruncSD * SDatAge))
class_max <- ceiling(max(MeanAtAge + TruncSD * SDatAge))

Classes <- seq(class_min, class_max, by = 10)


# Calculate Age-Size Key
ASK <- CalcAgeSizeKey(
  MeanAtAge = MeanAtAge,
  CVatAge = CVatAge,
  Classes = Classes,
  TruncSD = TruncSD,
  Dist = Dist
)

dim(ASK)


# Inspect first simulation, first year
ASK[1,,,1]

Description

Computes the stationary (asymptotic) distribution of a Markov chain movement matrix — the long-run proportion of the population expected to occupy each area. For a 2-area matrix a closed-form solution is used. For larger matrices, either a linear-algebra or iterative Markov chain approach is available.

Usage

CalcAsymDist(Movement, method = c("la", "mc"), tol = 1e-10, maxiter = 10000)

Arguments

Details

The movement matrix is treated as a row-stochastic transition matrix, where Movement[i, j] is the probability of moving from area i to area j. Diagonal entries represent the probability of remaining in an area. All rows must sum to 1.

Two solution methods are available for matrices larger than 2 × 2 via the method argument:

• "la" (default): solves the system pi * P = pi subject to sum(pi) = 1 using least-squares linear algebra (solve(t(A) %*% A, t(A) %*% B)). Exact and fast for well-conditioned matrices.

• "mc": iteratively multiplies the current distribution by Movement until convergence. More robust for nearly-reducible chains but slower.

For 2-area matrices the stationary distribution is computed analytically regardless of method:

pi[1] = P[2,1] / (P[1,2] + P[2,1])

pi[2] = P[1,2] / (P[1,2] + P[2,1])

Value

A numeric vector of length nArea giving the stationary probability of occupying each area. Values sum to 1.

See Also

Spatial(), CalcUnfishedDist()

Examples

# 2-area movement matrix
M <- matrix(c(0.8, 0.2,
              0.3, 0.7), nrow=2, byrow=TRUE)
CalcAsymDist(M)

# 3-area movement matrix using linear algebra (default)
M3 <- matrix(c(0.7, 0.2, 0.1,
               0.1, 0.8, 0.1,
               0.2, 0.2, 0.6), nrow=3, byrow=TRUE)
CalcAsymDist(M3)

# Using Markov chain iteration
CalcAsymDist(M3, method="mc")

Description

For a given vector of apical fishing mortality values, computes absolute equilibrium abundance and yield by combining per-recruit calculations with stock-recruitment relationship scaling. Results span all complexes defined in the operating model.

Usage

CalcEquilibrium(OM, apicalF = NULL, Years = NULL, Complex = NULL)

Arguments

Details

Default apicalF grid

When apicalF = NULL, a log-spaced sequence of 30 values is generated automatically, spanning from ⁠0.01 × max(M)⁠ to ⁠2 × max(M)⁠ with zero prepended, where max(M) is the maximum natural mortality across all stocks.

Log-spacing is used because population dynamics are approximately linear in log(F): yield and biomass change rapidly at low F relative to M but become increasingly insensitive at high F, so equal spacing on the log scale concentrates resolution where the equilibrium curve is most informative.

Supply an explicit vector to override, for example apicalF = seq(0, 2, by = 0.01).

Complexes

Per-recruit and equilibrium quantities are calculated separately for each complex, with apicalF defined as the maximum fishing mortality across all stocks within the complex.

Single year

Unlike CalcPerRecruit(), this function accepts only a single Year value. For multi-year equilibrium curves, call the function separately for each year.

Value

An equilibrium object containing absolute equilibrium numbers, biomass, spawning biomass, spawning production, removals, and landings evaluated at each value of apicalF, with results reported per stock.

See Also

CalcPerRecruit(), CalcMSY(), equilibrium

Description

Computes the innovation covariance matrix ($\Sigma_\epsilon$) for a multivariate AR(1) process given the stationary covariance matrix ($\Sigma_Z$) and lag-1 autocorrelation coefficients ($\phi$).

Usage

CalcInnovationCov(Sigma_Z, phi)

Arguments

Details

The relationship used is:

$\Sigma_\epsilon = \Sigma_Z - \Phi \Sigma_Z \Phi^T$

where $\Phi$ is a diagonal matrix of autocorrelation coefficients.

Only stocks with positive stationary variance (active stocks) are included in the computation. The result is embedded back into a full zero matrix, so inactive stocks contribute no innovation variance.

The active submatrix is forced to be symmetric and positive semi-definite. If negative eigenvalues are detected, Matrix::nearPD() is used to find the nearest PSD matrix. After correction, the diagonal is capped at the theoretical upper bound $\sigma^2_{Z,i}(1 - \phi_i^2)$ to prevent Matrix::nearPD() from inflating innovation variance beyond what is consistent with the stationary distribution.

Value

A numeric covariance matrix (nStock x nStock) representing the innovation covariance ($\Sigma_\epsilon$). Rows and columns corresponding to inactive stocks (zero diagonal in Sigma_Z) are set to zero.

See Also

GenerateStockTargeting(), FitStockTargeting()

Examples

Sigma_Z <- matrix(c(1, 0.5, 0.5, 1), 2, 2)
phi <- c(0.7, 0.6)

CalcInnovationCov(Sigma_Z, phi)

Description

Computes maximum sustainable yield (MSY) biological reference points for all complexes in a hist or om object by identifying the apical fishing mortality that maximises total yield, accounting for the stock-recruitment relationship. Results are stored in Hist@Reference@MSY and the updated hist object is returned.

Usage

CalcMSY(Hist, Years = NULL, type = c("Removals", "Landings"), silent = FALSE)

Arguments

Details

Complexes

Reference points are calculated separately for each complex defined in Hist@OM@Complexes. Within each complex:

• FMSY is the single apical fishing mortality maximising total yield across all stocks in the complex.

• Fleet-specific F is distributed according to effort-weighted catchability and selectivity.

• Stock-level quantities (BMSY, SBMSY, etc.) are reported for each stock evaluated at the complex-level FMSY.

Value

An a refpointsMSY object.

See Also

CalcPerRecruit(), CalcSPR0(), refpointsMSY,

Description

Extracts biological and fishery parameters from a hist or om object and evaluates per-recruit quantities at a given apical fishing mortality.

Usage

CalcPerRecruit(OM, apicalF = 0.1, Years = NULL, Complex = NULL)

Arguments

Details

Complexes

Per-recruit quantities are calculated separately for each complex, with apicalF defined as the maximum fishing mortality across all ages and stocks within the complex. Results are reported per stock and reassembled into a single perrecruit object spanning all stocks. The Complex argument can be used to restrict calculations to a subset of complexes.

Fleet allocation

The relative contribution of each fleet to total fishing mortality is computed as the effort-weighted catchability (i.e. ⁠Effort × Efficiency⁠) normalised across fleets. These proportions are used to distribute apicalF across fleets before selectivity is applied.

Years

When Years contains multiple values, biological and fishery parameters are subset to those years and the per-recruit calculations are evaluated for each year independently. When Years = NULL, only the final historical year is used, giving a single set of per-recruit quantities representative of current conditions.

Value

A perrecruit object containing numbers-per-recruit, spawning-per-recruit, biomass-per-recruit, removals, and landings evaluated at each value of apicalF, with results reported per stock and apical F defined as the maximum F across all stocks within each complex.

See Also

CalcSPR0(), perrecruit

Description

Calculate Reference Yield

Usage

calcRefYield(x, StockPars, FleetPars, pyears, Ncurr, nyears, proyears)

Arguments

Author(s)

A. Hordyk

Description

Computes standard deviation and lag-1 autocorrelation of log residuals for a simulated index (⁠sim x year⁠).

Usage

CalcResidualStats(LogResiduals, nSeasons = 1)

Arguments

Details

Contiguous NA values are handled by splitting into separate groups for autocorrelation calculation within each simulation. Seasons with all NA values across all years are dropped.

Value

A data.frame with columns:

• AC: weighted lag-1 autocorrelation of residuals

• SD: standard deviation of residuals

• NA_Season: a list length nSim with each element containing integer vector indicating which (if any) seasons have NA values for all years

See Also

ApplyAC(), GenResiduals()

Description

Calculates the unfished spawning production per recruit (SPR0) — the denominator of the spawning potential ratio — under equilibrium conditions. SPR0 is computed as the element-wise ratio of unfished spawning production SP0() to unfished recruitment R0(), with array broadcasting handled by ArrayDivide().

Usage

CalcSPR0(OM, silent = FALSE)

Arguments

Value

An array with dimensions ⁠[Sim, Stock, Year]⁠ containing the unfished spawning production per recruit. Dimensions where values are identical across simulations or years are collapsed by ReduceDims().

See Also

SP0(), R0(), ArrayDivide()

Description

Computes cumulative survival from recruitment to each age class, accounting for natural mortality, optional fishing mortality, spawn timing within a time step, and optional semelparous mortality. The calculation follows:

Usage

CalcSurvival(
  NaturalMortality,
  FishingMortality = NULL,
  PlusGroup = TRUE,
  SpawnTimeFrac = 0,
  Semelparous = FALSE
)

Arguments

Details

• Age 1: S[1] = exp(-Z[1] * SpawnTimeFrac)

• Age a: S[a] = S[a-1] * exp(-(Z[a-1] * (1 - f) + Z[a] * f)) * (1 - Semelparous[a-1])

where Z = M + F and f = SpawnTimeFrac.

If PlusGroup = TRUE, the plus-group age class is adjusted to account for ongoing mortality: S[nAge] = S[nAge] / (1 - exp(-Z[nAge])).

Value

A numeric array of cumulative survival-at-age with the same dimensions and dimnames as NaturalMortality. Each value represents the probability of surviving from recruitment to that age class in that year.

Description

Two complementary functions for converting between the integer number of seasons per year and the corresponding time unit label used throughout the package:

Usage

CalcTSUnits(Seasons)

CalcSeasons(Units)

Arguments

Details

• CalcTSUnits(): converts a season count to a time unit label string.

• CalcSeasons(): converts a time unit label string to a season count.

Supported conversions:

Value

• CalcTSUnits(): a character string time unit label.

• CalcSeasons(): an integer season count.

See Also

CalcYears()

Examples

CalcTSUnits(1)    # "year"
CalcTSUnits(4)    # "quarter"
CalcTSUnits(NULL) # "year"

CalcSeasons("year")    # 1
CalcSeasons("Quarter") # 4

Description

Calculate dynamic unfished population quantities for all Stock() objects in an operating model. Quantities include unfished number-at-age, total biomass, spawning biomass, and spawning production, evaluated dynamically over historical and projection years.

Usage

CalcUnfished_Dynamic(Hist, IdenticalHist = NULL, silent = FALSE)

Arguments

Value

A popdynamics object containing dynamic unfished Number, Biomass, SBiomass, and SProduction arrays with dimensions ⁠Sim × Stock × Year⁠.

See Also

CalcUnfished_Equilibrium()

Description

Calculate equilibrium unfished population quantities for all Stock() objects in an operating model. Quantities include unfished number-at-age, total biomass, spawning biomass, and spawning production, evaluated under equilibrium unfished conditions.

Usage

CalcUnfished_Equilibrium(OM, silent = FALSE)

Arguments

Details

If a Hist() object is supplied, its embedded operating model is used. The operating model is populated if required prior to calculation.

• Biomass is calculated as the sum over ages of unfished number-at-age multiplied by mean weight-at-age.

• Spawning biomass additionally applies maturity-at-age.

• Spawning production is calculated using fecundity-at-age and may be reassigned across stocks using the SPFrom slot of the stocks SRR() objects.

Value

A popdynamics object containing equilibrium unfished Number, Biomass, SBiomass, and SProduction arrays with dimensions ⁠Sim × Stock × Year⁠.

See Also

CalcUnfished_Dynamic()

Description

Computes the asymptotic unfished spatial distribution for each simulation, age class, and year by applying CalcAsymDist() to each ⁠nArea × nArea⁠ slice of Spatial@Movement. The result is stored in Spatial@UnfishedDist.

Usage

CalcUnfishedDist(Spatial, Ages = NULL, Years = NULL)

Arguments

Details

For a single-area model, all values are set to 1. For multi-area models, the stationary distribution of the movement matrix is computed for each ⁠Sim × Age × Year⁠ combination using CalcAsymDist().

Value

Spatial with Spatial@UnfishedDist populated as a named ⁠Sim × Area × Age × Year⁠ array, where each Area vector gives the stationary probability of occupying each area under unfished conditions.

See Also

CalcAsymDist(), Spatial()

Description

Calculates the equilibrium unfished number-at-age

Usage

CalcUnfishedNumber(OM, SP = FALSE)

Arguments

Details

Equilibrium N-at-Age is calculated from R0 (which may vary over time) but does NOT account for expected recruitment from the stock-recruit relationship.

Any changes in R0 due to time-varying biology (Fecundity-at-Age changes over time) should be accounted for in R0.

Value

A named list of length nStock() with each element an array with dimensions Sim, Age, and Year

Description

Calculate Unfished Survival

Usage

CalcUnfishedSurvival(
  OM,
  SP = FALSE,
  Years = NULL,
  silent = FALSE,
  Extend = TRUE
)

Arguments

Value

A list of length nStock() with an array with the unfished survival for each Stocks

Examples

## Not run: 
CalcUnfishedSurvival(OM)

## End(Not run)

Description

A function that condenses the number of catch-at-length bins in a data object

Usage

CALsimp(Data, nbins = 10, simno = 1)

Arguments

Author(s)

T. Carruthers

Description

Diagnostic tools that look up the slot requirements of each MP and compares to the data available in the Data object.

Usage

Can(Data, timelimit = 1, MPs = NA, dev = FALSE, silent = FALSE)

Cant(Data, timelimit = 1, silent = FALSE)

DLMdiag(
  Data,
  command = c("available", "not available", "needed"),
  reps = 5,
  timelimit = 1,
  funcs1 = NA,
  dev = FALSE,
  silent = FALSE
)

Needed(Data, timelimit = 1, silent = FALSE)

Arguments

Functions

• Can(): Identifies MPs that have the correct data, do not produce errors, and run within the time limit.

• Cant(): Identifies MPs that don't have sufficient data, lead to errors, or don't run in time along with a list of their data requirements.

• DLMdiag(): Internal function called by Can and Cant

• Needed(): Identifies what data are needed to run the MPs that are currently not able to run given a Data object

See Also

avail Data-legacy

Examples

CanMPs <- Can(MSEtool::Cobia)
CantMPs <- Cant(MSEtool::Cobia)
Needs <- Needed(MSEtool::Cobia)

Description

Interactions(), Landings(), Discards(), and Removals() extract total interactions (encounters), retained landings, discards, and removals (landings + discards) respectively.

Usage

Interactions(
  object,
  df = TRUE,
  byAge = FALSE,
  byArea = FALSE,
  byFleet = FALSE,
  Reduce = TRUE,
  IncYear = FALSE
)

Landings(
  object,
  df = TRUE,
  byAge = FALSE,
  bySize = FALSE,
  byArea = FALSE,
  byFleet = TRUE,
  Reduce = TRUE,
  IncYear = FALSE
)

Landings(x) <- value

Discards(
  object,
  df = TRUE,
  byAge = FALSE,
  bySize = FALSE,
  byArea = FALSE,
  byFleet = TRUE,
  Reduce = TRUE,
  IncYear = FALSE
)

Discards(x) <- value

Removals(
  object,
  df = TRUE,
  byAge = FALSE,
  bySize = FALSE,
  byArea = FALSE,
  byFleet = TRUE,
  Reduce = TRUE,
  IncYear = FALSE
)

Arguments

Details

When called on a hist or mse object, the functions return simulated catch arrays or tidy data frames as described below.

When called on an obs object, the functions return the corresponding catchobs slot directly (the observation error structure, not simulated values). When called on a data object, they return the corresponding catchdata slot directly (the observed or simulated values). In both cases no data frame conversion is performed, regardless of any df argument.

The assignment forms ⁠Landings<-⁠ and ⁠Discards<-⁠ replace the corresponding slot of an obs or data object.

When byAge = FALSE or bySize = FALSE for hist or mse objects, the catch data are in units of biomass (⁠N x Weight⁠), where Weight is the fleet-specific weight-at-age schedule from Fleet(). When byAge = TRUE or bySize = TRUE the values are in units of numbers. When byArea = TRUE the values are always in units of numbers.

When applied to an mse object the historical and projection periods are row-bound and labelled via the Period column; historical rows carry MP = "Historical".

Value

• For obs: the catchobs object stored in the Landings or Discards slot.

• For data: the catchdata object stored in the Landings or Discards slot.

• For hist or mse with df = FALSE: the raw array slot (Interactions, Landings, or Discards).

• For hist or mse with df = TRUE: a tidy data.frame with columns Sim, Stock, Year, Period, MP (MSE only), and optionally Age, Size, Area, and/or Fleet, plus Value and Variable.

• Assignment forms return x with the named slot replaced by value.

Examples

Hist <- Simulate(SingleStockOM)
MSE <- Project(Hist, 'CurrentEffort')

# Raw arrays from Hist / MSE
Interactions(Hist, df = FALSE)
Landings(MSE, df = FALSE)

# Tidy data frames
Interactions(Hist)
Landings(MSE)
Discards(MSE)
Removals(MSE)

# Retain fleet, age, and area structure
Landings(MSE, byFleet = TRUE, byAge = TRUE, byArea = TRUE)
Discards(MSE, byFleet = TRUE, bySize = TRUE)

# Direct slot access for obs and data objects
obs <- Obs(Landings = CatchObs(CV = 0.2))
Landings(obs)
Landings(obs) <- CatchObs(CV = 0.3)

dat <- Data(Landings = CatchData(Value = matrix(100, 1, 1)))
Landings(dat)
Landings(dat) <- CatchData()

Description

Construct and manipulate a catchability object defining fishing gear or vessel efficiency for a Fleet() object.

Usage

Catchability(Efficiency = NULL, qCV = NULL, qInc = NULL, Misc = list())

Catchability(x) <- value

Efficiency(x)

Efficiency(x) <- value

qCV(x)

qCV(x) <- value

qInc(x)

qInc(x) <- value

Theta(x)

Theta(x) <- value

Arguments

Details

A catchability object defines the efficiency with which a fleet converts fishing effort into fishing mortality (encounters/interactions, see Interactions()).

A constant scalar is sufficient for most applications; time-varying or simulation-varying efficiency can be specified via a full ⁠Sim x Year⁠ array.

Efficiency Array Format

When supplied as a scalar, Efficiency is wrapped internally into a ⁠1 x 1⁠ array and replicated across all simulations and years during PopulateCatchability(), producing constant efficiency. When supplied as an array, the Sim dimension may be length 1 or match nSim, and the Year dimension is extended to cover all historical and projected years if it does not already do so.

When Efficiency is NULL, PopulateCatchability() initialises it to 1 across all simulations and years, equivalent to supplying Efficiency = 1.

Projected-Year Adjustments: qInc and qCV