make_covariates: Format density covariate matrix
In James-Thorson/VAST: Vector-Autoregressive Spatio-Temporal (VAST) Model

make_covariates

R Documentation

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, `function`s 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 `factor`s.

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,

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.
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.
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