project_model: Project a fitted VAST model forward in time

In James-Thorson/VAST: Vector-Autoregressive Spatio-Temporal (VAST) Model

Project a fitted VAST model forward in time

Description

project_model simulates random effects forward in time, for use to generate a predictive interval without actually re-fitting the model. This is useful e.g., to generate end-of-century projections.

Usage

project_model(
  x,
  n_proj,
  n_samples = 1,
  new_covariate_data = NULL,
  historical_uncertainty = "both",
  seed = 123456,
  working_dir = paste0(getwd(), "/"),
  what = NULL
)

Arguments

x	Output from fit_model
n_proj	Number of time-steps to include in projection
n_samples	Number of samples to include. If n_samples=1 then project_model just returns the list of REPORTed variables. If n_samples>1 then project_model returns a list of lists, where each element is the list of REPORTed variables.
new_covariate_data	New covariates to include for future intervals
historical_uncertainty	Whether to incorporate uncertainty about fitted interval historical_uncertainty="both" Include uncertainty in fixed and random effects using joint precision matrix historical_uncertainty="random" Include uncertainty in random effects using inner Hessian matrix historical_uncertainty="none" Condition upon MLE for fixed and Empirical Bayes for random effects

Details

The function specifically simulates new values for random effects occurring during forecasted years. This includes some combination of intercepts beta1/beta2 and spatio-temporal terms epsilon1/epsilon2 depending on which are treated as random during estimation. It does *not* generate new values of covariates or random-effects that are not indexed by time omega1/omega2

Note that the model may behave poorly when historical_uncertainty="both" and the estimation model includes an AR1 process for any component. Given this combination of features, some samples may have a 'rho' value >1 or <1, which will result in exponential growth for any such sampled value. This behavior could be improved in future code updates by using tmbstan instead of the normal approximation to generate parametric uncertainty during the historical period.

Similarly, estimating a RW process for epsilon will result in an exponential increase in forecasted total abundance over time. This occurs because the variance across locations of epsilon increases progressively during the forecast period, such that the index is again dominated by the forecasted density at a few sites.

Value

All obj$report() output for a single simulation of historical period as well as n_proj forecast intervals

Examples

## Not run: 
# Run model
fit = fit_model( ... )

# Add projection
project_model( x = fit,
               n_proj = 80,
               new_covariate_data = NULL,
               historical_uncertainty = "both",
               seed = NULL )

## End(Not run)

James-Thorson/VAST documentation built on Jan. 31, 2024, 12:13 p.m.