Retrospective analysis for an sdmTMB index

Runs an analytical retrospective on an index from sdmTMB::sdmTMB(). The function refits the model for each peel (successively dropping the most recent years) and calculates an index for each peel using sdmTMB::get_index_split(). All model settings are inherited from the original call of the fitted object (as with sdmTMB::update.sdmTMB()); only data and mesh are replaced. Arguments of the original call are evaluated in the environment of the model formula, so objects referenced there (e.g. priors = my_priors) must still exist.

Usage

sdmTMB_retro(
  object,
  newdata,
  nyears = 5,
  refit_meshes = FALSE,
  cutoff = NULL,
  bias_correct = FALSE,
  level = 0.95,
  area = 1,
  save_models = FALSE,
  silent = TRUE,
  n_workers = 1,
  nsplit = NULL,
  predict_args = list(),
  future_seed = TRUE
)

Arguments

object

A fitted model from sdmTMB::sdmTMB().

newdata

A data frame to make predictions on, with the same predictor columns as the fitted data and a time column with the same name as in the fitted data. Must contain all years needed for the retrospective (see nyears).

nyears

Integer. How many peels the retrospective should contain, including the terminal (most recent) year. Clamped to the number of fitted years available.

refit_meshes

Logical. Rebuild the mesh for each peel from the peeled data using cutoff? If FALSE (default) the original model mesh is reused unchanged, including any barrier. Rebuilt meshes have no barrier (a warning is given if the original mesh has one).

cutoff

Numeric. Mesh cutoff (in model coordinate units) used to rebuild the meshes when refit_meshes = TRUE. Required in that case, since the original cutoff is not stored in the fitted model.

bias_correct

Logical. Apply bias correction via TMB::sdreport()? Recommended TRUE for final analyses, FALSE (default) while experimenting.

level

Numeric. Confidence level for the index intervals.

area

Grid cell area for area weighting the index. Can be a numeric vector of length nrow(newdata), a single numeric value, or a character column name in newdata. Passed to sdmTMB::get_index_split().

save_models

Logical. Retain the fitted model object for each peel in the output?

silent

Logical. Suppress model fitting output?

n_workers

Integer. Number of parallel workers. Default 1, which uses whatever future::plan() is currently set (sequential by default). Values > 1 set a temporary parallel plan (forked future::multicore where supported, otherwise future::multisession).

nsplit

Integer. Number of splits for sdmTMB::get_index_split(). NULL (default) uses about 75 000 grid rows per split, which avoids the silent crashes of bias-corrected extraction on very large grids.

predict_args

A list of extra arguments passed to sdmTMB::predict.sdmTMB() when calculating each peel's index (the predict_args argument of sdmTMB::get_index_split()), e.g. list(re_form_iid = NA).

future_seed

Logical or integer. Future-compatible random seed for parallel processing. See future.apply::future_lapply().

Value

A list of class sdmTMB_retro. Each element corresponds to a peel and contains an index data frame (and, if save_models = TRUE, the fitted model object).

See also

sdmTMB::sdmTMB(), sdmTMB::get_index(), plot.sdmTMB_retro()

Author

Mikko Vihtakari, with examples and documentation adapted from the sdmTMB package.

Examples

# \donttest{
mesh <- sdmTMB::make_mesh(sdmTMB::pcod, c("X", "Y"), cutoff = 25)
m <- sdmTMB::sdmTMB(
  data = sdmTMB::pcod,
  formula = density ~ 0 + as.factor(year),
  time = "year", mesh = mesh, family = sdmTMB::tweedie(link = "log")
)
nd <- sdmTMB::replicate_df(sdmTMB::qcs_grid, "year", unique(sdmTMB::pcod$year))
retr <- sdmTMB_retro(m, nd, nyears = 3, n_workers = 1)
#> Model for 2017 did not pass sdmTMB::sanity() checks.
#> Model for 2015 did not pass sdmTMB::sanity() checks.
#> Model for 2013 did not pass sdmTMB::sanity() checks.
plot(retr)

# }