Run annual MSY over an SBT posterior

run_msy() reconstructs the model report once per retained posterior draw and applies the annual MSY calculation, including draw-specific modelled catch shares, to every requested catch year. By default, all retained iterations in every chain and all years from first_yr_catch through last_yr are used. Pre-catch model years are excluded because the legacy calculation has no fishery catch allocation for them.

Usage

run_msy(
  fit,
  object = NULL,
  posterior = TRUE,
  years = NULL,
  iters = NULL,
  chains = NULL,
  lambda = 1e+05,
  phase1_lambda = 100,
  control = list(eval.max = 100000L, iter.max = 100000L),
  cores = 1L,
  mle_par = NULL
)

Arguments

fit

An sbt_fit object. For legacy use, this may instead be the fitted model data list when object is supplied.

object

Legacy RTMB objective with par and report elements. Do not supply this when fit is an sbt_fit.

posterior

TRUE (default) to use posterior draws stored in fit, FALSE for one MLE evaluation, or a SparseNUTS-compatible posterior object. Active fixed-effect draws and complete joint fixed/random-effect draws are both supported; active draws condition random effects before reporting.

years

Calendar years to evaluate. The default is every fitted catch year. Requested years must have observed catch allocations.

iters

Optional unique retained-iteration indices to use within every selected chain. NULL uses all retained iterations.

chains

Optional unique chain indices. NULL uses every chain.

lambda

Final catch-allocation penalty passed to find_msy().

phase1_lambda

First-phase catch-allocation penalty passed to find_msy().

control

Control list passed to stats::nlminb().

cores

Positive integer number of forked workers. Parallel execution is used on non-Windows platforms; Windows falls back to sequential execution.

mle_par

Optional fitted fixed-parameter vector for legacy MLE use. When omitted, a fitted object$opt$par is required (and is supplied by a rebuilt sbt_fit). It cannot be supplied with posterior draws.

Value

An object of class sbt_msy. Its summary data frame has one row per draw and year, preserving chain, iteration, optimizer diagnostics, fitted spawning output and fishing mortality, unfished spawning output, and the corresponding Bmsy_B0, B_Bmsy, and F_Fmsy ratios. Fitted and MSY fishing mortality are both biomass-weighted over ages 2–15. F_full, MSY_f, catch_split, and target_catch_split are draw-by-year-by-fishery arrays. Fmsy_a and Bmsy_a are draw-by-year-by-age arrays. source records exact source and implementation signatures plus fit provenance; settings$draws records the resolved draw selection.

See also

Other MSY calculations: find_msy(), msy_calc(), sbt_add_msy()

Examples

if (FALSE) { # \dontrun{
fit <- sbt_example_fit()
msy <- run_msy(
  fit,
  posterior = FALSE,
  years = fit$data$last_yr,
  cores = 1L
)
msy$summary[, c("year", "MSY", "Bmsy_B0", "B_Bmsy", "F_Fmsy")]
} # }