Extracts specified bands from an image collection using Google Earth Engine

This function uses Google Earth Engine to extract specified bands from an image collection. The function summarises this information for each row in your dataset (x). The function handles memory constraints on Google Earth Engine's end by extracting data in time chunks based on the start date of each interval in the dataset. This function is best used within the fetch function.

Usage

extract_gee(
  x,
  collection_name,
  bands,
  scale = 250,
  time_buffer = lubridate::days(20),
  temporal_fun = "last",
  lazy = FALSE,
  debug = FALSE,
  initialise_gee = TRUE,
  use_gcs = FALSE,
  use_drive = FALSE,
  max_chunk_time_day_range = "3 months",
  max_feature_collection_size = 5000,
  ee_reducer_fun = rgee::ee$Reducer$mean(),
  time_column_name = NULL,
  verbose = TRUE,
  is_vectorised_summarisation_function = FALSE,
  ...
)

Arguments

x: A sf collection with a geometry column and a time column.
collection_name: A character string representing the Google Earth Engine image collection from which to extract data.
bands: A vector of character strings representing the band names to extract from the image collection.
scale: A numeric value representing the scale at which to perform the extraction in meters. Default is 250.
time_buffer: A lubridate duration representing the amount of time to add before and after each time interval when filtering the image collection. Default is lubridate::days(20).
temporal_fun: A function or string representing the function used to summarise the data extracted for each interval. Default is 'last', which returns the value closest to the start of the interval. Other built-in options are 'closest' and 'next'.
lazy: A logical indicating whether to download Google Earth Engine data lazily with future::sequential objects to evaluate the task in the future. Defaults to FALSE.
debug: A logical indicating whether to produce debugging plots. Default is FALSE.
initialise_gee: A logical indicating whether to initialise Google Earth Engine within the function. Default is TRUE.
use_gcs: A logical indicating whether to use Google Cloud Storage for larger requests. Default is FALSE.
use_drive: A logical indicating whether to use Google Drive for larger requests. Default is FALSE.
max_chunk_time_day_range: An string representing the maximum number of time units to include in each time chunk when splitting the dataset for efficient memory use on Google Earth Engine's end. Default is '3 months'.
max_feature_collection_size: An integer representing the maximum number of features (rows) to include in each chunk when splitting the dataset for efficient memory use on Google Earth Engine's end. Default is 5000.
ee_reducer_fun: A Google Earth Engine reducer function representing the function used to aggregate the data extracted from each image. Default is rgee::ee$Reducer$mean().
time_column_name: Name of the time column in the dataset. If NULL (the default), a column of type lubridate::interval is automatically selected.
verbose: Whether to print messages to the console. Defaults to TRUE.
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).
...: Additional arguments for underlying extraction function, rgee::ee_extract.

Value

A dataframe or sf object with the same rows as the input x, and new columns representing the extracted data. The new column names correspond to the bands parameter.

Examples

if (FALSE) { # \dontrun{
#' extracted <- d %>%
  fetch(
    ~extract_gee(
       .x,
       collection_name='MODIS/061/MOD13Q1',
       bands=c('NDVI', 'DetailedQA'),
       time_buffer=16,
     )
  )

# extract and summarise data every fortnight for the last six months
# relative to the start of the time column in `d`
rep_extracted <- d %>%
  fetch(
    ~extract_gee(
       .x,
       collection_name='MODIS/061/MOD13Q1',
       bands=c('NDVI', 'DetailedQA'),
       time_buffer=16,
     ),
    .time_rep=time_rep(interval=lubridate::days(14), n_start=-12),
  )
} # }