make_covariates: Format density covariate matrix

In James-Thorson-NOAA/FishStatsUtils: Utilities (shared code and data) for FishStats spatio-temporal modeling toolbox

Format density covariate matrix

Description

make_covariates uses a formula interface to generate covariates

Usage

make_covariates(
  formula,
  covariate_data,
  Year_i,
  spatial_list,
  contrasts.arg = NULL
)

Arguments

formula	an object of class "formula" (or one that can be coerced to that class): a symbolic description of the model to be fitted. Similar specification to lm
covariate_data	data frame of covariate values with columns Lat, Lon, and Year, and other columns matching names in formula; Year=NA can be used for covariates that do not change among years (e.g., depth)
contrasts.arg	a list, whose entries are values (numeric matrices, functions or character strings naming functions) to be used as replacement values for the contrasts replacement function and whose names are the names of columns of data containing factors.

Details

This function generates 3D arrays Cov_gtp, Cov_ip, and Cov_stp as required by VAST::make_data to incorporate density covariates. The user must supply a data frame covariate_data of covariate values, with columns named Lat, Lon, and Year, as well as values for all covariates as additional named columns. This data frame is then used as a "look-up table", and is matched against variables listed in formula.

Covariates then affect the linear predictor via coefficients that are estimated separately for every category. Therefore, in a multivariate model the formula specifies the structure of covariates that is applied separately to each category.

Specifically,

1. for every observation i at location Lat_i[i] and Lon_i[i] in year t_i[t], the nearest Lat-Lon observation in that year is identified in covariate_data, and covariate values in that row of covariate_data are assigned to observation i. Covariate values are then used to predict densities at each sample location.

2. Similarly, for every extrapolation-grid cell g at location spatial_list$latlon_g[g,] in each year, the nearest row of covariate_data in that year is used to assign covariate values. Covariate values are then used to predict densities at each extrapolation-grid cell.

3. Finally, for every mesh-location s at location spatial_list$latlon_s[s,] in each year, the nearest row of covariate_data in that year is used to assign covariate values. Covariate values could be used in the future to predict habitat-specific variance-covariance for spatial variables (although this feature has not been built yet).

make_covariates then formats these covariate values appropriately and returns them.

If all covariates as "static" (not changing among years), then set Year = NA to cause values to be duplicated internally for all values of Year. If using a mix of static and dynamic covariates, then duplicate rows for static covariates for every value of Year

Value

Tagged list of useful output

Cov_gtp

3-dimensional array for use in VAST::make_data

Cov_ip

2-dimensional array for use in VAST::make_data

Cov_stp

3-dimensional array for use in VAST::make_data

James-Thorson-NOAA/FishStatsUtils documentation built on June 10, 2025, 6:18 p.m.