Compare survey indices across different mesh cutoff values

Refits an sdmTMB model using a range of mesh cutoff values and compares the resulting survey indices and predictions to the original (reference) model. Useful for assessing the sensitivity of an index to mesh resolution. All model settings are inherited from the original call of the fitted object (as with sdmTMB::update.sdmTMB()); only mesh is replaced.

Usage

compare_meshes(
  object,
  mesh_cutoffs,
  newdata,
  object_crs = NULL,
  coord_multiplier = 1000,
  bias_correct = FALSE,
  level = 0.95,
  area = 1,
  save_models = FALSE,
  silent = TRUE,
  n_workers = 1,
  nsplit = NULL,
  future_seed = TRUE,
  reference_name = "Reference"
)

Arguments

object: A fitted model from sdmTMB::sdmTMB().
mesh_cutoffs: Numeric vector of mesh cutoff values (in the units of the model coordinates, typically km) to compare.
newdata: A data frame for predictions, with the same predictor columns as the fitted data and a time column matching the fitted data. Must contain the model's coordinate columns (object$spde$xy_cols).
object_crs: Coordinate reference system for the model data. If NULL (default), extracted from the model's mesh.
coord_multiplier: Numeric factor to convert the model coordinates to CRS units for the spatial maps. Default 1000 (coordinates in km, CRS in m); use 1 for coordinates already in CRS units.
bias_correct: Logical. Apply bias correction via TMB::sdreport()? Default FALSE.
level: Numeric. Confidence level for index intervals. Default 0.95.
area: Grid cell area for area-weighted index calculation. Passed to sdmTMB::get_index_split().
save_models: Logical. Retain fitted model objects in the output? Default FALSE.
silent: Logical. Suppress model output? Default TRUE.
n_workers: Integer. Number of parallel workers. Default 1, which uses whatever future::plan() is currently set. 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.
future_seed: Logical or integer. Future-compatible random seed for parallel processing.
reference_name: Character. Label for the reference (original) model. Default "Reference".

Value

An object of class sdmTMB_mesh_comparison, a list with index, pred_diff (and optionally models). The time column of index is always named year. Coordinates in pred_diff are returned as X and Y columns. Carries crs, coord_multiplier and reference_name attributes.

Details

The alternative meshes are built with sdmTMB::make_mesh(). If object uses a barrier mesh, the alternatives have no barrier and a warning is given, since the comparison then mixes cutoff and barrier effects.

Author

Mikko Vihtakari

Examples

# \donttest{
mesh <- sdmTMB::make_mesh(sdmTMB::pcod, c("X", "Y"), cutoff = 20)
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))
mesh_indices <- compare_meshes(
  object = m, mesh_cutoffs = c(10, 30), newdata = nd, object_crs = 32609,
  reference_name = "20 km"
)
#> Model for cutoff 30 did not pass sdmTMB::sanity() checks.
plot(mesh_indices)

# }