# Extract covariate values from spatial rasters and prepare rasters for spatial predictions This function extracts covariate values from spatial raster data (e.g. for use in modelling) and prepares these covariates for use in spatial predictions. It accepts a camera trap table containing spatial information, along with either a directory containing covariate raster files, a character vector specifying the file paths of these covariate rasters, or direct SpatRaster objects from the terra package. Additionally, users can provide parameters to control how covariates are extracted, and how they are aggregated to prediction rasters. The function can also download elevation data and calculate terrain metrics if requested. The function generates prediction rasters based on a provided template or creates one automatically if no template is provided. The function returns a list containing the camera trap dataset with extracted covariate values (e.g for use in occupancy modelling), and prediction rasters ready for spatial modeling. ```r createCovariates( CTtable, directory, filenames, rasters, buffer_ct = 0, bilinear = FALSE, buffer_aoi = 1000, raster_template = NULL, resolution = NULL, append = TRUE, formats = ".tif", recursive = FALSE, download_elevation = FALSE, elevation_zoom = 10, terrain_measures = NULL, standardize_na = FALSE, scale_covariates = FALSE ) ``` ## Arguments - `CTtable`: sf object as defined by the `sf` package. Essentially a camera trap data frame with spatial information. - `directory`: character. The directory containing the covariate rasters. - `filenames`: character (optionally named). A vector of file paths of covariate rasters. If it is named the covariates will be named according to the names. If unnamed the file names will be used as covariate names. - `rasters`: SpatRaster object or list of SpatRaster objects. Direct input of rasters from the terra package instead of reading from disk. - `buffer_ct`: numeric. A value (in meters) by which to buffer the point locations in `CTtable` for extraction of covariate values. - `bilinear`: logical. If `TRUE`, extract covariate values with bilinear interpolation (nearest 4 raster cells). If `FALSE`, extract value at the cell the point falls in. Only relevant if `buffer_ct` is 0. - `buffer_aoi`: numeric. A value (in meters) by which to buffer the overall camera trapping grid to ensure that prediction rasters are larger than the camera trapping grid. - `raster_template`: SpatRaster. A SpatRaster (as defined in the `terra` package) to use as template for the creation of prediction rasters. - `resolution`: numeric. Spatial resolution of prediction rasters in the units of the coordinate reference system. Ignored if `raster_template` is provided. - `append`: logical. If `TRUE`, add the extracted covariates to the existing `CTtable`. If `FALSE`, return only the extracted covariate values without the existing `CTtable`. - `formats`: character. Possible file formats for raster data (must include the dot). Defaults to `.tif` files. - `recursive`: logical. If `TRUE`, search for raster files recursively in subdirectories when a directory is provided. Defaults to `FALSE`. - `download_elevation`: logical. If `TRUE`, download elevation data from AWS. Defaults to `FALSE`. - `elevation_zoom`: numeric. Zoom level for elevation data download (6-12). Higher values provide more detail but longer download times. Zoom 12 corresponds to ~20m pixel resolution, 11 to ~40m, 10 to ~80m, and so on (resolution halves with each decrease in zoom level). Defaults to 9. - `terrain_measures`: character. Vector of terrain metrics to calculate from elevation data. Options include "slope" (slope in degrees), "aspect" (compass direction in degrees), "TRI" (Terrain Ruggedness Index, measuring elevation difference between adjacent cells), "TPI" (Topographic Position Index, comparing cell elevation to mean of surrounding cells), and "roughness" (difference between max and min of surrounding cells). Defaults to NULL (no terrain metrics). - `standardize_na`: logical. Logical. If `TRUE`, ensures all layers in the prediction raster have identical NA patterns by setting a cell to NA in all bands if it's NA in any band. This creates consistency for spatial predictions across covariates but may lose data in covariates. - `scale_covariates`: logical. If `TRUE`, scale numeric covariates and return both original and scaled versions of data and prediction rasters. Scaling is performed using R's `scale` function. Defaults to `FALSE`. ## Returns - **CTtable**: An `sf` object representing the camera trap data frame with extracted covariate values. - **predictionRaster**: A `SpatRaster` object containing covariate raster layers - **originalRaster**: A list of the original input rasters - **CTtable**: The original `sf` object with unscaled covariate values - **CTtable_scaled**: The `sf` object with scaled numeric covariate values - **predictionRaster**: The original unscaled prediction raster - **predictionRaster_scaled**: The prediction raster with scaled numeric layers - **originalRaster**: A list of the original input rasters - **scaling_params**: A list containing center and scale information of numeric covariates ## Details The input camera trap table must be an `sf` object (a data frame with a geometry column specifying the spatial information). For details on how to convert an exising camera trap table to sf, see the examples below. The input rasters can be in different coordinate systems. During covariate extraction the CTtable is projected to each raster's coordinate system individually. For the prediction raster all input rasters are either resampled or reprojected to a consistent coordinate system. When `recursive = TRUE` and a directory is provided, the function will search for raster files in all subdirectories. In this case, the subdirectory names are used as covariate names, and only one raster file per subdirectory is allowed. When `download_elevation = TRUE`, the function will download elevation data from AWS using the `elevatr` package. The `elevation_zoom` parameter controls the level of detail, with values between 6 and 12. Higher zoom levels provide finer resolution but require longer download times and may consume significant memory. Approximate resolutions: zoom 12 = ~20m, 11 = ~40m, 10 = ~80m, etc. If `terrain_measures` is specified, the function calculates the requested terrain metrics from the elevation data using `terra::terrain()` with the default 3x3 neighborhood. Available terrain metrics include "slope", "aspect", "TRI" (Terrain Ruggedness Index), "TPI" (Topographic Position Index), and "roughness". When using `scale_covariates = TRUE`, the function returns both original and scaled versions of the data and prediction rasters. #' The function uses R's `scale()` function to perform centering and scaling, and includes the scaling parameters in the returned metadata. ### Warning about Categorical Covariates This function does not explicitly handle categorical rasters. All raster values are treated as numeric, which can be problematic when scaling is applied. The function attempts to identify "likely categorical" variables (numeric variables with few unique integer values) and will provide warnings, but it cannot automatically handle them correctly for scaling. When using scaled covariates with categorical variables in models: * Use `CTtable_scaled` for numeric predictors * Use `CTtable` (original) for categorical predictors * Similarly, use `predictionRaster_scaled` for numeric predictors in spatial predictions * Use `predictionRaster` for categorical predictors in spatial predictions Future versions may implement proper categorical raster handling with RAT (Raster Attribute Table) support. ## Examples ```r ## Not run: # load camera trap table data(camtraps) # create sf object camtraps_sf <- st_as_sf(camtraps, coords = c("utm_x", "utm_y"), crs = 32650) # extract covariates (with 100m buffer around cameras) # doesn't run because 'directory' is only a placeholder covariates <- createCovariates(camtraps_sf, "path/to/covariate_rasters", buffer_ct = 100, buffer_aoi = 1000, resolution = 100) # extract covariates with elevation data (this code runs) covariates_elev <- createCovariates(camtraps_sf, buffer_ct = 100, buffer_aoi = 1000, resolution = 100, download_elevation = TRUE, elevation_zoom = 11, terrain_measures = c("slope", "aspect", "TRI")) # Note that if local rasters are available they can be extracted alongside # elevation data in a single function call # camera trap table with extracted covariate values camtraps_sf_cov <- covariates_elev$CTtable # covariate raster layer r_cov <- covariates_elev$predictionRaster plot(r_cov) # Use SpatRaster objects directly as input r1 <- rast("elevation.tif") r2 <- rast("landcover.tif") raster_list <- list(elevation = r1, landcover = r2) covariates_direct <- createCovariates(camtraps_sf, rasters = raster_list, buffer_ct = 100, resolution = 100) # Scale numeric covariates for modeling covariates_scaled <- createCovariates(camtraps_sf, rasters = raster_list, buffer_ct = 100, resolution = 100, scale_covariates = TRUE) # Use scaled data with categorical variables # Mix and match from original and scaled outputs for tabular data model_data <- covariates_scaled$CTtable_scaled # Use scaled numeric covariates model_data$landcover <- covariates_direct$CTtable$landcover # Use original categorical covariate # Mix and match for prediction rasters # Create combined prediction raster (scaled numeric variables & original categorical variables) # Extract scaled elevation layer elev_scaled <- covariates_scaled$predictionRaster_scaled$elevation # Extract original landcover layer (categorical) landcover_orig <- covariates_direct$predictionRaster$landcover # Combine into a new SpatRaster for predictions prediction_raster <- c(elev_scaled, landcover_orig) names(prediction_raster) <- c("elevation", "landcover") # Use this combined raster for spatial predictions plot(prediction_raster) ## End(Not run) ```

createCovariates function