Fits a spatial or spatiotemporal GLMM using sdmTMB::sdmTMB(). This function
handles data preparation, mesh creation, model fitting, and optionally saves
results to a structured directory. The fitted model is returned with minimal
attachments for downstream diagnostic and index calculations.
run_sdmtmb(
data,
family,
formula,
dir = NULL,
dir_main = lifecycle::deprecated(),
n_knots = 500,
spatial = list("on", "on"),
spatiotemporal = list("iid", "iid"),
anisotropy = TRUE,
share_range = FALSE,
sdmtmb_control = sdmTMB::sdmTMBcontrol(newton_loops = 3),
...
)A data frame containing the survey data. Must include columns:
year, fyear, survey_name, common_name, catch_weight, effort,
x, y, latitude, longitude, and depth.
A family object specifying the response distribution and link.
See sdmTMB::sdmTMB() for options. Common choices include
sdmTMB::delta_gamma() and sdmTMB::tweedie().
A formula specifying the fixed effects structure. Should
reference columns in data. See sdmTMB::sdmTMB() for details.
A string specifying a path where results will be saved. The
default is your current working directory. A subdirectory structure will be
created based on the species, survey, and model family. If NULL, the fitted
object is returned with nothing saved to disk
Deprecated. A string specifying a path where results will be saved. The
default is your current working directory. A subdirectory structure will be
created based on the species, survey, and model family. If NULL, the fitted
object is returned with nothing saved to disk
An integer specifying the number of knots you want in your mesh that is created by fmesher. More knots is not always better. The default is to use 500 knots. Future work will look at specifying a threshold distance between points rather than number of knots.
Estimate spatial random fields? Options are 'on' / 'off' or TRUE / FALSE. Optionally, a list for delta models, e.g. list('on', 'off'). Default is list('on', 'on') to estimate spatial random fields for a delta model.
Estimate the spatiotemporal random fields as 'iid' (independent and identically distributed; default), stationary 'ar1' (first-order autoregressive), a random walk ('rw'), or fixed at 0 'off'. If a delta model, can be a list. Default is list('iid', 'iid') to estimate spatiotemporal random fields for a delta model. These settings are available in the configuration file under spatiotemporal1 for the presence absence model and spatiotemporal2 for the catch rate model.
Logical: allow for anisotropy (spatial correlation that is directionally dependent). This is commonly needed for West Coast groundfish stocks that have a coastwide range due to the directionality of the coast line. Default is TRUE.
Logical, whether or not to share the range between the
spatial and spatiotemporal fields. This defaults to FALSE, but adds extra
parameters. The default in sdmTMB is TRUE, and sharing the range may
improve estimation for data limited applications.
Optional list, in the format of sdmTMB::sdmTMBcontrol().
By default, this includes 3 newton loops.
Optional arguments passed to sdmTMB::sdmTMB().
A list object of class sdmTMB returned by sdmTMB::sdmTMB() when fitting
data to the model. Two additional components are attached for convenience:
mesh - The mesh object used for fitting (useful for plotting)
The fitted model's data (fit$data) contains the truncated data used for
fitting. Original data and prediction grid can be accessed from saved files
or recreated as needed.
The function performs the following steps:
Creates a structured directory for outputs
Filters data to positive catch locations and truncates to data extent
Creates a prediction grid using lookup_grid()
Builds a mesh with specified number of knots
Fits the model using sdmTMB::sdmTMB()
Refits with extra optimization if not converged
Optionally saves fit, data, and mesh plot
diagnose(), run comprehensive diagnostics on the fitted model
calc_index_areas(), calculate abundance indices from the fitted model
sdmTMB::sdmTMB(), the underlying fitting function
lookup_grid(), creates the prediction grid