summary.fit_model: Extract summary of spatial estimates

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

Extract summary of spatial estimates

Description

summary.fit_model extracts commonly used quantities derived from a fitted VAST model

Usage

## S3 method for class 'fit_model'
summary(
  x,
  what = "density",
  n_samples = 250,
  working_dir = NULL,
  type = 1,
  random_seed = NULL,
  form = NULL,
  category_names = x$category_names,
  year_labels = x$year_labels,
  ...
)

Arguments

x	Output from fit_model
what	String indicating what to summarize; options are 'density', 'index' or 'residuals'
n_samples	Number of samples used when what="residuals"
type	integer stating what type of simulation to use from the following options: type=1 is a "measurement error" or "conditional" simulator that simulates new data conditional upon estimated fixed and random effects. type=2 is an "unconditional" simulator that simulates new random effects conditional upon fixed effects (but not otherwise conditioning upon original data), and new data conditional upon both. type=3 simulates new fixed and random effects from the joint precision matrix (i.e., conditioning upon the original data), and new data conditional upon these values. type=4 simulates new random effects from the internal Hessian matrix evaluated at the MLE (i.e., conditional on fixed effects estimates and the original data), and new data conditional upon these values.
random_seed	integer passed to set.seed, where the default value random_seed=NULL resets the random-number seed.
form	Optional predictor against which the residuals should be plotted. Default is to used the predicted(simulationOutput).
...	additional arguments passed to plotResiduals when what="residuals"

Details

summary.fit_model faciliates common queries for model output including:

• what="density" returns a tagged list containing element Density_dataframe, which lists the estimated density for every Latitude-Longitude-Year-Category combination for every modelled location in the extrapolation-grid.

• what="residuals" returns a DHARMa object containing PIT residuals; See details section for more information.

For calculating residuals, the function calls package DHARMa to create a diagnostic object for simulation-based quantile residuals. It specifically simulates replicated data sets from the predictive distribution of data conditional on estimated fixed and random effects. It then calculates probability-integral-transform (PIT) residuals from the observed and simulated values. It then replaces the automatically calculated residuals in the DHARMa object with these these PIT residuals, so that DHARMa can be used to plot those PIT residuals. PIT residuals are used because the original DHARMa calculations are not correct when using a delta-model (due to additional jittered values added by DHARMa when detecting multiple 0-valued observations), hence the need to call this function to correctly calculate PIT residuals for a delta-model.

Note that summary(fit, ..., type=0 uses oneStepPredict_deltaModel to calculate one-step-ahead residuals. These are probably the most appropriate method for evaluating residuals, but are also *very* slow to calculate relative to other methods.

See Also

plot_quantile_residuals to plot output of summary.fit_model(x,what="residuals")

James-Thorson/VAST documentation built on Feb. 9, 2025, 9:05 a.m.