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
)
a previously fit wham model
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.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% 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), 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.
$proj_mature
(matrix), user-supplied maturity values for the projection years with dimensions (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.
integer, number of additional Newton steps after optimization. Passed to fit_tmb
. Default = 0
for projections.
T/F, calculate standard deviations of model parameters? See sdreport
. Default = TRUE
.
T/F, Passed to silent argument of TMB::MakeADFun
. Default = FALSE
.
T/F, save the full TMB::sdreport
object? If FALSE
, only save summary.sdreport
to reduce model object file size. Default = TRUE
.
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
)
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:
Set $cont.ecov = TRUE
. WHAM will estimate the ecov process in projection years (i.e. continue the random walk / AR1 process).
Set $use.last.ecov = TRUE
. WHAM will use ecov value from the terminal year (of population model) for projections.
Provide $avg.yrs.ecov
, a vector specifying which years to average over the environmental covariate(s) for projections.
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.
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
}