Extract values from a raster over time — extract_over

This function extracts raster data over time ranges of each row and summarises the extracted data using a custom function. The function summarises this information for each row in your dataset (x). This function is best used within the fetch function.

Usage

extract_over_time(
  x,
  r,
  subds = 0,
  temporal_fun = function(x) {
     rowMeans(x, na.rm = TRUE)
 },
  spatial_extraction_fun = function(x, r, ...) {
     extract_over_space(x = x, r = r,
    ...)
 },
  scale = NULL,
  time_buffer = lubridate::days(0),
  debug = FALSE,
  override_terraOptions = TRUE,
  time_column_name = NULL,
  is_vectorised_summarisation_function = FALSE,
  verbose = TRUE,
  trim_raster = TRUE,
  subset_raster_indices = TRUE,
  ...
)

Arguments

x: A sf collection with a geometry column and a time column.
r: A file path to a raster file or a SpatRaster object from the terra package. This is the raster data. source from which the data will be extracted.
subds: positive integer or character to select a sub-dataset to extract from. If zero or "", all sub-datasets are extracted.
temporal_fun: A function used to summarise multiple data points found within a time interval. Default is rowMeans(x, na.rm=TRUE). The user can supply vectorised summarisation functions (using rowMeans or rowSums) or non-vectorised summarisation functions (e.g., sum, mean, min, max). If supplying a custom vectorised temporal_fun, set is_vectorised_temporal_fun to TRUE to ensure the vectorised approach is used for performance. Note, vectorised summarisation functions are not possible when fun=NULL and you are extracting with polygon or line geometries (i.e. temporal_fun is used to summarise, treating each time and space value independently).
spatial_extraction_fun: A function used to extract points spatially for each time slice of the raster. Default is the default implementation of extract_over_space (extracts the mean of geometries within rasters, removing NAs).
scale: The scale to aggregate your raster to (in units of the original raster). Note this will be rounded to fit the nearest aggregation factor (number of cells in each direction). Leave as NULL (the default) if you do not want any aggregation. See aggregate.
time_buffer: Time buffer used to adjust the time interval for data extraction. The function always uses the time before and after the interval to prevent errors when summarising the earliest and latest times. Default is 0 days.
debug: If TRUE, pauses the function and displays a plot for each extracted point. This is useful for debugging unexpected extracted values. Default is FALSE.
override_terraOptions: If TRUE, overrides terra's default terraOptions with those specified in the envfetch's package. Default is TRUE.
time_column_name: Name of the time column in the dataset. If NULL (the default), a column of type lubridate::interval is automatically selected.
is_vectorised_summarisation_function: Whether the summarisation is vectorised (like rowSums or rowMeans). Is only necessary to be TRUE if the row-wise vectorised summarisation function has not been automatically detected (does not use rowSums or rowMeans).
verbose: Whether to print messages to the console. Defaults to TRUE.
trim_raster: Whether to trim the raster to time bounds as a performance optimisation. Defaults to TRUE.
subset_raster_indices: Whether to subset raster by time indices as a performance optimisation. Defaults to TRUE.
...: Additional arguments to pass to the spatial_extraction_fun.

Value

A modified version of the input 'x' with additional columns containing the extracted data.

Examples

if (FALSE) { # \dontrun{
extracted <- d %>%
  fetch(
    ~extract_over_time(.x, r = '/path/to/netcdf.nc'),
  )

# extract and summarise data every fortnight for the past six months
# relative to the start of the time column in `d`
rep_extracted <- d %>%
  fetch(
      ~extract_over_time(.x, r = '/path/to/netcdf.nc'),
      .time_rep=time_rep(interval=lubridate::days(14), n_start=-12),
  )
} # }