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 use to average population attributes (MAA,FAA,WAA,maturity,movement) in projection years. Any BRPs calculated in projection years will also use these. Default = last 5 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 the environmental covariate(s) over 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.M (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.move (which defaults to last 5 model years).

  • $cont.L.re (T/F), continue any L ("extra mortality rate") random effects for projections. Default = FALSE. If FALSE, L parameters will be averaged over $avg.yrs.L (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 projections, only used if $use.FXSPR = TRUE. For example, to project with F = 75% F_40%SPR, proj.opts$percentFXSPR = 75. Default = 100.

  • $percentFMSY (scalar), percent of F_MSY to use for projections, only used if $use.FMSY = TRUE and a stock-recruit relationship is assumed. Default = 100.

  • $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. 3: average recruitment deviations over $avg.yrs.R (if $sigma = "rec") 4: no recruitment deviations (if $sigma = "rec").

  • $proj_NAA_opt (integer), 1: continue any RE processes for NAA, 2: average NAA deviations over $avg.yrs.NAA. 3: no NAA deviations.

  • $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.

  • $proj_F_init which F to initialize internal newton search for annual projected F for a given user-specifed catch. Default is 0.1

  • $avg.yrs.sel list (length = n_fleets), years to average selectivity or FAA for each fleet for projection years. Any BRPs calculated in projection years will also use this. Default = last 5 years, tail(model$years, 5).

  • $avg.yrs.waacatch list (length = n_fleets), years to average weight at age for each fleet for projection years (if $proj_waa is NULL). Any BRPs calculated in projection years will also use this. Default = last 5 years, tail(model$years, 5).

  • $avg.yrs.waassb list (length = n_stocks), years to average weight at age for each stock SSB for projection years (if $proj_waa is NULL). Any BRPs calculated in projection years will also use this. Default = last 5 years, tail(model$years, 5).

  • $avg.yrs.mature list (length = n_stocks), years to average maturity at age for each stock for projection years (if $proj_mature is NULL). Any BRPs calculated in projection years will also use this. Default = last 5 years, tail(model$years, 5).

  • $avg.yrs.L list (length = n_regions), years to average extra mortality at age for each region for projection years (if $cond.L.re = FALSE). Any BRPs calculated in projection years will also use this. Default = last 5 years, tail(model$years, 5).

  • $avg.yrs.M list (length = n_stocks, each is a list with length = n_regions), years to average natural mortality at age for each stock and region for projection years (if $cont.M.re = FALSE). Any BRPs calculated in projection years will also use this. Default = last 5 years, tail(model$years, 5).

  • $avg.yrs.move list (length = n_stocks, each is a list with length = n_regions), years to average movement rates at age and season for each stock and region (at beginning of interval) for projection years (if $cont.move.re = FALSE). Any BRPs calculated in projection years will also use this. Default = last 5 years, tail(model$years, 5).

  • $avg.yrs.R list (length = n_stocks), years to average recruitment deviations for each stock and region for projection years (if $proj_R_opt = 3). Any BRPs calculated in projection years will also use this. Default = last 5 years, tail(model$years, 5).

  • $avg.yrs.NAA list (length = n_stocks, each is a list with length = n_regions), years to average NAA deviations for each stock and region for projection years (if $proj_NAA_opt = 2). Any BRPs calculated in projection years will also use this. Default = last 5 years, tail(model$years, 5).

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
}