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, cont.ecov = TRUE, use.last.ecov = FALSE, percentFXSPR = 100,
    percentFMSY = 100),
  n.newton = 3,
  do.sdrep = TRUE,
  MakeADFun.silent = FALSE,
  save.sdrep = TRUE,
  check.version = TRUE,
  TMB.bias.correct = FALSE,
  TMB.jointPrecision = FALSE
)

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% SPR for projections. Default = FALSE.

  • $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.M.re (T/F), continue M random effects (i.e. AR1_y or 2D AR1) for projections. Default = FALSE. If FALSE, M will be averaged over $avg.yrs (which defaults to last 5 model years).

  • $cont.move.re (T/F), continue any movement random effects for projections. Default = FALSE. If FALSE, movement parameters will be averaged over $avg.yrs (which defaults to last 5 model years).

  • $cont.L.re (T/F), continue any movement random effects for projections. Default = FALSE. If FALSE, movement parameters 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% F_40%SPR, so proj.opts$percentFXSPR = 75. Default = 100.

  • $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% SPR, 4: use specified F, 5: use specified catch, 6: use Fmsy. Overrides any of the above specifications.

  • $proj_Fcatch (vector or matrix), 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. if vector, total catch or F is supplied else matrix columns should be fleets for fleet-specific F to be found/used (n.yrs x 1 or n_fleets).

  • $proj_mature (array), user-supplied maturity values for the projection years with dimensions (n_stocks x n.yrs x n_ages).

  • $proj_waa (3-d array), user-supplied waa values for the projection years with first and third dimensions equal to that of model$input$data$waa (waa source x n.yrs x n_ages).

  • $proj_R_opt (integer), 1: continue any RE processes for recruitment, 2: make projected recruitment consistent with average recruitment in SPR reference points and cancel any bias correction for NAA in projection years.

  • $proj_NAA_init (scalar), the default starting value for all NAA random effects in projection years is exp(10), which may not be large enough for some catch specification. Use this to change the default if a call to project_wham suggests it.

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.

check.version

T/F check whether version WHAM and TMB for fitted model match that of the version of WHAM using for projections. Default = TRUE.

TMB.bias.correct

T/F whether to use the bias.correct feature of TMB::sdreport. Default = FALSE.

TMB.jointPrecision

T/F whether to return the joint precision matrix for the fixed and random effects from TMB::sdreport. Default = FALSE.

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% SPR. Set proj.opts$use.FXSPR = TRUE. WHAM will calculate F at X% SPR.

  • 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
}