Run sdmTMB::sdmTMB()

Source: R/run_sdmtmb.R

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(
  dir_main = getwd(),
  data,
  family,
  formula,
  n_knots = 500,
  share_range = FALSE,
  sdmtmb_control = sdmTMB::sdmTMBcontrol(newton_loops = 3),
  ...
)

Arguments

dir_main

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

data

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.

family

A family object specifying the response distribution and link. See sdmTMB::sdmTMB() for options. Common choices include sdmTMB::delta_gamma() and sdmTMB::tweedie().

formula

A formula specifying the fixed effects structure. Should reference columns in data. See sdmTMB::sdmTMB() for details.

n_knots

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.

share_range

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.

sdmtmb_control

Optional list, in the format of sdmTMB::sdmTMBcontrol(). By default, this includes 3 newton loops.

...

Optional arguments passed to sdmTMB::sdmTMB().

Value

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.

Details

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

See also

Author

Chantel R. Wetzel