Project a fit WHAM model

Source: R/project_wham.R

Provides projections/forecasts for an existing (already fit) WHAM model.

project_wham(
  model,
  proj.opts = list(n.yrs = 3, use.last.F = TRUE, use.avg.F = FALSE, use.FXSPR = FALSE,
    use.FMSY = FALSE, proj.F = NULL, proj.catch = NULL, avg.yrs = NULL, cont.ecov = TRUE,
    use.last.ecov = FALSE, avg.ecov.yrs = NULL, proj.ecov = NULL, cont.Mre = NULL,
    avg.rec.yrs = NULL, percentFXSPR = 100, percentFMSY = 100, proj_F_opt = NULL,
    proj_Fcatch = NULL),
  n.newton = 3,
  do.sdrep = TRUE,
  MakeADFun.silent = FALSE,
  save.sdrep = TRUE
)

Arguments

model

a previously fit wham model

proj.opts

a named list with the following components:

  • $n.yrs (integer), number of years to project/forecast. Default = 3.

  • $use.last.F (T/F), use terminal year F for projections. Default = TRUE.

  • $use.avg.F (T/F), use average of F over certain years for projections. Default = FALSE. Years to average over determined by $avg.yrs defined below.

  • $use.FXSPR (T/F), calculate and use F at X

  • $use.FMSY (T/F), calculate and use FMSY for projections. Default = FALSE.

  • $proj.F (vector), user-specified fishing mortality for projections. Length must equal n.yrs.

  • $proj.catch (vector), user-specified aggregate catch for projections. Length must equal n.yrs.

  • $avg.yrs (vector), specify which years to average over for calculating reference points. Default = last 5 model years, tail(model$years, 5).

  • $cont.ecov (T/F), continue ecov process (e.g. random walk or AR1) for projections. Default = TRUE.

  • $use.last.ecov (T/F), use terminal year ecov for projections.

  • $avg.ecov.yrs (vector), specify which years to average over the environmental covariate(s) for projections.

  • $proj.ecov (matrix), user-specified environmental covariate(s) for projections. n.yrs x n.ecov.

  • $cont.Mre (T/F), continue M random effects (i.e. AR1_y or 2D AR1) for projections. Default = TRUE. If FALSE, M will be averaged over $avg.yrs (which defaults to last 5 model years).

  • $avg.rec.yrs (vector), specify which years to calculate the CDF of recruitment for use in projections. Default = all model years. Only used when recruitment is estimated as fixed effects (SCAA).

  • $percentFXSPR (scalar), percent of F_XSPR to use for calculating catch in projections, only used if $use.FXSPR = TRUE. For example, GOM cod uses F = 75

  • $percentFMSY (scalar), percent of F_MSY to use for calculating catch in projections, only used if $use.FMSY = TRUE.

  • $proj_F_opt (vector), integers specifying how to configure each year of the projection: 1: use terminal F, 2: use average F, 3: use F at X

  • $proj_Fcatch (vector), catch or F values to use each projection year: values are not used when using Fmsy, FXSPR, terminal F or average F. Overrides any of the above specifications of proj.F or proj.catch.

n.newton

integer, number of additional Newton steps after optimization. Passed to fit_tmb. Default = 0 for projections.

do.sdrep

T/F, calculate standard deviations of model parameters? See sdreport. Default = TRUE.

MakeADFun.silent

T/F, Passed to silent argument of TMB::MakeADFun. Default = FALSE.

save.sdrep

T/F, save the full TMB::sdreport object? If FALSE, only save summary.sdreport to reduce model object file size. Default = TRUE.

Value

a projected WHAM model with additional output if specified:

$rep

List of derived quantity estimates (see examples)

$sdrep

Parameter estimates (and standard errors if do.sdrep=TRUE)

$peels

Retrospective analysis (if do.retro=TRUE)

$osa

One-step-ahead residuals (if do.osa=TRUE)

Details

WHAM implements five options for handling fishing mortality in the projections. Exactly one of these must be specified in proj.opts:

  • Use last year F (default). Set proj.opts$use.last.F = TRUE. WHAM will use F in the terminal model year for projections.

  • Use average F. Set proj.opts$use.avg.F = TRUE. WHAM will use F averaged over proj.opts$avg.yrs for projections (as is done for M-, maturity-, and weight-at-age).

  • Use F at X

  • Specify F. Provide proj.opts$proj.F, an F vector with length = n.yrs.

  • Specify catch. Provide proj.opts$proj.catch, a vector of aggregate catch with length = n.yrs. WHAM will calculate F to get specified catch.

proj.opts$avg.yrs controls which years the following will be averaged over in the projections:

  • Maturity-at-age

  • Weight-at-age

  • Natural mortality-at-age

  • Fishing mortality-at-age (if proj.opts$use.avgF = TRUE)

If fitting a model with recruitment estimated freely in each year, i.e. as fixed effects as in ASAP, WHAM handles recruitment in the projection years similarly to using the empirical cumulative distribution function. WHAM does this by calculating the mean and standard deviation of log(R) over all model years (default) or a specified subset of years (proj.opts$avg.rec.yrs). WHAM then treats recruitment in the projections as a random effect with this mean and SD, i.e. log(R) ~ N(meanlogR, sdlogR).

WHAM implements four options for handling the environmental covariate(s) in the projections. Exactly one of these must be specified in proj.opts if ecov is in the model:

(Default) Continue ecov process model (e.g. random walk, AR1)

Set $cont.ecov = TRUE. WHAM will estimate the ecov process in projection years (i.e. continue the random walk / AR1 process).

Use last year ecov(s)

Set $use.last.ecov = TRUE. WHAM will use ecov value from the terminal year (of population model) for projections.

Use average ecov(s)

Provide $avg.yrs.ecov, a vector specifying which years to average over the environmental covariate(s) for projections.

Specify ecov

Provide $proj.ecov, a matrix of user-specified environmental covariate(s) to use for projections. Dimensions must be # projection years (proj.opts$n.yrs) x # ecovs (ncols(ecov$mean)).

If the original model fit the ecov in years beyond the population model, WHAM will use the already-fit ecov values for the projections. If the ecov model extended at least proj.opts$n.yrs years beyond the population model, then none of the above need be specified.

See also

fit_wham, fit_tmb

Examples

if (FALSE) {
data("input4_SNEMAYT") # load SNEMA yellowtail flounder input data and model settings
mod <- fit_wham(input4_SNEMAYT) # using default values (do.proj=T)

mod2 <- fit_wham(input4_SNEMAYT, do.retro=F, do.osa=F, do.proj=F) # fit model without projections, retro analysis, or OSA residuals
mod_proj <- project_wham(mod2) # add projections to previously fit model, using default values: use.lastF = TRUE, n.yrs = 3, avg.yrs = last 5 years

names(mod_proj$rep) # list of derived quantities
tail(mod_proj$rep$SSB, 3) # get 3-year projected SSB estimates (weight, not numbers)

x = summary(mod_proj$sdrep)
unique(rownames(x)) # list of estimated parameters and derived quanitites with SE
x = x[rownames(x) == "log_SSB",] # SSB estimates with SE
ssb.mat = exp(cbind(x, x[,1] + qnorm(0.975)*cbind(-x[,2],x[,2])))/1000 # calculate 95% CI
colnames(ssb.mat) <- c("SSB","SSB_se","SSB_lower","SSB_upper")
tail(ssb.mat, 3) # 3-year projected SSB estimates with SE and 95% CI
}