Run CTP projections

High-level projection runner for SBT assessment workflows. The function uses supplied recruitment and selectivity projection inputs, builds catch and future monitoring inputs, runs population dynamics, optionally applies the CTP management procedure at the configured TAC update years, simulates CPUE with a historical fitted-residual AR(1), simulates GT, HSP, and POP observations, and returns the objects needed for projection reporting.

Usage

run_projections(
  data,
  object,
  mcmc = NULL,
  first_yr = 2022L,
  last_yr = 2035L,
  n_iter = NULL,
  iters = NULL,
  seed = 102L,
  cores = 1L,
  fixed_catch_n_years = 4L,
  fixed_projection_tac = rep(20647L, fixed_catch_n_years),
  ctp_tac_schedule = 3L,
  ctp_tac_calculation_lag = 2L,
  ctp_catch_data_lag = 3L,
  ctp_cpue_data_lag = 3L,
  ctp_gt_data_lag = 4L,
  ctp_ckmr_data_lag = 8L,
  projection_tac_split_yf = NULL,
  projection_tac_split_f = NULL,
  gt_skip_years = integer(0L),
  gt_skip_recapture_years = integer(0L),
  gt_projection_nrel = 5000L,
  gt_projection_nsam = 10000L,
  pop_projection_n_juvenile = 1500L,
  pop_projection_n_adult = 1500L,
  pop_projection_min_cohort = 2002L,
  pop_projection_adult_ages = 5L:30L,
  hsp_projection_nC = 1500L^2L,
  rdev_y = NULL,
  sel_fya = NULL,
  catch_ysf = NULL,
  run_ctp = TRUE,
  simulate_observations = TRUE,
  catch_shortfall_rule = c("error", "cap"),
  catch_shortfall_limit = biological_state_contract()$hrate_limit,
  cache_file = NULL,
  cache_signature = NULL,
  legacy_cache_signatures = character(),
  overwrite = FALSE,
  cache_only = FALSE,
  verbose = TRUE,
  projection_removal_multiplier_f = NULL
)

Arguments

data: Assessment data list from get_data.
object: RTMB model object from MakeADFun. For grid-MCMC projections this should be the projection object whose parameter vector matches mcmc.
mcmc: Optional SparseNUTS fit. If supplied, projection draws are taken from extract_samples(mcmc); otherwise the model object's last.par.best is repeated.
first_yr, last_yr: First and last projection years.
n_iter: Optional number of projection iterations to run. If NULL, this is inferred from the supplied rdev_y and sel_fya inputs.
iters: Optional integer row indices into the MCMC posterior draws. If NULL, the first n_iter rows are used.
seed: Integer random seed used for stochastic projection components.
cores: Number of parallel cores for per-iteration work.
fixed_catch_n_years: Number of future years with fixed TAC before CTP.
fixed_projection_tac: Numeric vector of fixed TACs. A scalar is repeated for all fixed-TAC years.
ctp_tac_schedule: Integer number of years between CTP TAC updates.
ctp_tac_calculation_lag: Integer lag from a TAC implementation year to its CTP calculation year.
ctp_catch_data_lag, ctp_cpue_data_lag: Integer lags defining the latest catch and CPUE data years available to each CTP calculation.
ctp_gt_data_lag, ctp_ckmr_data_lag: Integer lags defining the latest gene-tagging and close-kin data years available to each CTP calculation.
projection_tac_split_yf: Optional matrix of TAC split proportions with dimensions projection year by fishery.
projection_tac_split_f: Optional named vector of TAC split proportions to repeat for all projection years when projection_tac_split_yf is not supplied.
gt_skip_years: Integer vector of GT release years to omit from simulated future observations. A release in year $y$ would otherwise be recaptured in year $y + 1$.
gt_skip_recapture_years: Integer vector of GT harvest-sampling or recapture years to omit independently of the release-year schedule.
gt_projection_nrel, gt_projection_nsam: Future GT release and scanned sample sizes. Each may be a scalar, an unnamed vector with one value per projected release year, or a vector named by every projected release year.
pop_projection_n_juvenile, pop_projection_n_adult: Future juvenile and adult sample sizes used for POP projection.
pop_projection_min_cohort: Minimum juvenile cohort used for projected POP comparisons.
pop_projection_adult_ages: Adult capture ages used for projected POP comparisons.
hsp_projection_nC: Future HSP comparison count per cohort pair.
rdev_y: Matrix of supplied recruitment deviates with dimensions n_iter by projection year.
sel_fya: Array of supplied projected selectivity with dimensions n_iter by fishery by projection year by age. It may include only the model fishing fleets or the fishing fleets plus the CPUE fleet.
catch_ysf: Optional precomputed catch input with dimensions year by season by fishery, or iteration by year by season by fishery. Future entries are interpreted as nominal TAC allocations and converted to removals with projection_removal_multiplier_f. If NULL, nominal catch is built from the fixed TAC and CTP settings.
run_ctp: Logical; run the CTP TAC updates after the fixed-TAC block.
simulate_observations: Logical; simulate future CPUE, GT, HSP, and POP observations and attach them to the returned dynamics paths. This must be TRUE when run_ctp = TRUE because those observations are CTP inputs.
catch_shortfall_rule: Catch-implementation rule. "error" retains fail-closed behavior when a requested catch is biologically infeasible. "cap" proportionally reduces every season and fishery within an affected draw-year until the raw combined harvest rate is no greater than catch_shortfall_limit; nominal CTP TAC advice is retained separately from realized catch.
catch_shortfall_limit: Maximum raw combined seasonal harvest rate used by the "cap" rule. It must not exceed the biological-state ceiling and defaults to that ceiling (0.9).
cache_file: Optional RDS cache file for the complete projection output. Compatible caches are read before simulation, corrupt or incomplete files are treated as cache misses, and new cache files are replaced atomically.
cache_signature: Optional character string included in cache validation.
legacy_cache_signatures: Optional character vector of explicitly approved signatures from the immediately preceding cache contract. A matching cache must still pass complete internal validation and match the current scientific inputs; it is then migrated to the current version-independent signature. This is intended only for audited, one-time cache migrations.
overwrite: Logical; ignore an existing cache and recompute.
cache_only: Logical. If TRUE, return a compatible existing cache or stop before projection simulation. Default is FALSE.
verbose: Logical; print basic cache/timing messages.
projection_removal_multiplier_f: Optional numeric vector with one positive multiplier per fishery. Multipliers convert nominal future TAC allocations to biological removals; historical assessment catches through data$last_yr are not multiplied. Named values must match the model fisheries exactly. The default is one for every fishery.

Value

A named list containing the projection configuration, generated inputs, projected dynamics, CTP status table, checksum-bound snapshots of the complete raw simulated observation arrays available at each CTP update, separate nominal TAC-advice, realized nominal-catch, and biological-removal arrays, and a timing data frame with elapsed run time in seconds.

Details

When mcmc and iters are supplied, iters selects model-parameter rows only. The supplied rdev_y and sel_fya objects are always taken from their first n_iter rows. Callers must therefore construct those objects in exactly the same draw order as the selected posterior rows. The function sets deterministic per-draw seeds for stochastic projection components and does not restore the caller's previous random-number state. For each draw, future CPUE log residuals use the empirical lag-one correlation of the fitted historical log residuals and begin from the final fitted residual. The configured combined CPUE observation-error SD is treated as the marginal SD, so the innovation SD is multiplied by sqrt(1 - rho^2), as in the legacy ADMB projection.

Examples

if (FALSE) { # \dontrun{
fit <- sbt_example_fit()
object <- sbt_obj(fit, fresh = TRUE)
first_yr <- fit$data$last_yr + 1L
last_yr <- first_yr + 1L

set.seed(102)
recruitment <- project_rec_devs(
  fit$data, object,
  first_yr = first_yr,
  last_yr = last_yr,
  samp_years = fit$data$first_yr:fit$data$last_yr,
  option = "AR1",
  bootstrap = FALSE,
  pin_year = fit$data$last_yr
)
selectivity <- project_selectivity(
  fit$data, object,
  first_yr = first_yr,
  last_yr = last_yr,
  option = "mean_last",
  n_years = 10L
)
projection <- run_projections(
  data = fit$data,
  object = object,
  first_yr = first_yr,
  last_yr = last_yr,
  n_iter = 1L,
  fixed_catch_n_years = 2L,
  fixed_projection_tac = rep(20000, 2L),
  rdev_y = recruitment$proj_rdev_y[
    , as.character(first_yr:last_yr), drop = FALSE
  ],
  sel_fya = selectivity,
  run_ctp = FALSE,
  simulate_observations = FALSE,
  catch_shortfall_rule = "cap",
  verbose = FALSE
)
} # }

Usage

Arguments

Value

Details

See also

Examples