extract_buffered_raster: Extract spatially buffered and temporally dynamic rasters of...

In dynamicSDM: Species Distribution and Abundance Modelling at High Spatio-Temporal Resolution

Extract spatially buffered and temporally dynamic rasters of explanatory variable data.

Description

Extract rasters for spatially buffered and temporally dynamic explanatory variables at each projection date using Google Earth Engine.

Usage

extract_buffered_raster(
  dates,
  spatial.ext,
  datasetname,
  bandname,
  temporal.level,
  spatial.res.metres,
  GEE.math.fun,
  moving.window.matrix,
  user.email,
  varname,
  temporal.res,
  temporal.direction,
  categories,
  save.directory,
  agg.factor,
  save.drive.folder,
  resume = TRUE
)

Arguments

dates	a character string, vector of dates in format "YYYY-MM-DD".
spatial.ext	the spatial extent for the extracted raster. Object from which extent can be extracted of class SpatExtent, SpatRaster, sf polygon or numeric vector listing xmin, xmax, ymin and ymax in order.
datasetname	a character string, the Google Earth Engine dataset to extract data from.
bandname	a character string, the Google Earth Engine dataset bandname to extract data for.
temporal.level	a character string indicating the temporal resolution of the remote-sensing dataset (datasetname). One of day, month or year: can be abbreviated. Default; day.
spatial.res.metres	a numeric value, specifying the spatial resolution in metres of the raster to be extracted.
GEE.math.fun	a character string, the mathematical function to compute across the specified period and spatial buffer from each projection date and cell.
moving.window.matrix	a matrix of weights with an odd number of sides to specify spatial neighbourhood of cells ("moving window") to calculate GEE.math.fun across for each cell in spatial.ext. See details for more information.
user.email	a character string, user email for initialising Google Drive.
varname	optional; a character string, the unique name for the explanatory variable. Default varname is “bandname_temporal.res_temporal.direction_ GEE.math.fun_buffered_raster".
temporal.res	optional; a numeric value, the temporal resolution in days prior or post each projection date to calculate GEE.math.fun across.
temporal.direction	optional; a character string, the temporal direction for extracting dynamic variable data across relative to each projection date given. One of prior or post: can be abbreviated.
categories	optional; a character string, the categories to use in the calculation if data are categorical. See details for more information.
save.directory	optional; a character string, path to local directory to save extracted rasters to.
agg.factor	optional;a postive integer, the aggregation factor expressed as number of cells in each direction. See details.
save.drive.folder	optional; a character string, Google Drive folder to save extracted rasters to. Folder must be uniquely named within Google Drive. Do not provide path.
resume	a logical indicating whether to search save.directory or save.drive.folder and return to previous progress through projection dates.Default = TRUE.

Details

For each projection date, this function downloads rasters at a given spatial extent and resolution for spatially buffered and temporally dynamic explanatory variables. Rasters can be saved directly to Google Drive or a local directory. These rasters can be combined to create projection covariate data frames for projecting dynamic species distribution and abundance at high spatiotemporal resolution.

Value

Returns details of successful explanatory variable raster extractions for each projection date.

Temporal dimension

If temporal.res and temporal.direction are not given, explanatory variable data for all cells within spatial.ext are extracted. If temporal.res and temporal.direction are given, explanatory variable data for all cells within spatial.ext are extracted, for which GEE.math.fun has been first calculated over the specified period in relation to the projection date (prior or post).

Categorical data and temporally dynamic variables

Please be aware, if specific categories are given (argument categories) when extracting categorical data, then temporal buffering cannot be completed. The most recent categorical data to the occurrence record date will be used and spatial buffering will take place.

If, specific categories are not given when extracting from categorical datasets, be careful to choose appropriate mathematical functions for such data. For instance, "first" or "last" may be more relevant that "sum" of land cover classification numbers.

Spatial dimension

Using the focal function in terra R package (Hijmans et al., 2022), GEE.math.fun is calculated across the spatial buffer area from each cell in spatial.ext. The spatial buffer area used is defined by ⁠moving.window matrix⁠, which dictates the neighbourhood of cells surrounding each cell in spatial.ext to include in the calculation. See get_moving_window.

Mathematical function

GEE.math.fun specifies the mathematical function to be calculated over the spatial buffered area and temporal period. Options are limited to Google Earth Engine ImageCollection Reducer functions (https://developers.google.com/earth-engine/apidocs/) for which an analogous R function is available. This includes: "allNonZero","anyNonZero", "count", "first","firstNonNull", "last", "lastNonNull", "max","mean", "median","min", "mode","product", "sampleStdDev", "sampleVariance", "stdDev", "sum" and "variance".

Categorical data

If explanatory variable data are categorical (e.g. land cover classes), categories can be used to specify the categories of importance to the calculation. The category or categories given will be converted in a binary representation, with “1” for those listed, and “0” for all others in the dataset. Ensure that the GEE.math.fun given is appropriate for such data.

For example, this function could return the sum of suitable land cover classified cells in the “moving window” from each cell across spatial extent given.

Aggregation factor

agg.factor given represents the factor to aggregate SpatRaster data with function aggregate in terra R package (Hijmans et al., 2022). Aggregation uses the GEE.math.fun as the function. Following aggregation spatial buffering using the moving window matrix occurs. This is included to minimise computing time if data are of high spatial resolution and a large spatial buffer is needed. Ensure to calculate get_moving_window() with the spatial resolution of the data post-aggregation by this factor.

Google Earth Engine

extract_buffered_raster() requires users to have installed R package rgee (Aybar et al., 2020) and initialised Google Earth Engine with valid log-in credentials. Please follow instructions on the following website https://cran.r-project.org/package=rgee

• datasetname must be in the accepted Google Earth Engine catalogue layout (e.g. “MODIS/006/MCD12Q1” or “UCSB-CHG/CHIRPS/DAILY”)

• bandname must be as specified under the dataset in the Google Earth Engine catalogue (e.g. “LC_Type5”, “precipitation”). For datasets and band names, see https://developers.google.com/earth-engine/datasets.

Google Drive

extract_buffered_raster() also requires users to have installed the R package googledrive(D'Agostino McGowan and Bryan, 2022) and initialised Google Drive with valid log-in credentials, which must be stated using argument user.email. Please follow instructions on https://googledrive.tidyverse.org/ for initialising the googledrive package.

The save.drive.folder must be uniquely named within your Google Drive and do not provide the path.

Occasional rgee errors

As this function uses the rgee package to extract rasters from Google Earth Engine, below we outline occasional rgee errors that may occur when extracting rasters:

• "To avoid memory excess problems, ee_as_raster will not build Raster objects for large images"

This can be a sporadic error. It may be related to GEE server usage or internet connection at the time you tested the function. Try restarting your R session or try again at another time. Also, try clearing the files from the "dynamicSDM_download_bucket" in your Google Drive.

This error could also be due to an issue with your input spatial.res.metres. This function will extract rasters at all typical spatial resolutions of remote-sensing data and at global extents. If this error persists, please ensure you have not accidentally given an unrealistically high spatial resolution (e.g. spatial.res.metres = 0.01 when you may be confusing the spatial resolution in degrees with metres).

• "Pixel type not supported: Type Long. Convert the image to a floating point type or a smaller integer type, for example, using ee.Image.toDouble()"

This error appears when rgee has been given an input that cannot be extracted. Some common causes include:

• Inappropriate GEE.math.fun for extracting categorical data.

• Dates or spatial extents that are not covered by the chosen GEE dataset. Remember to check whether the first projection date minus temporal.res is still within the temporal extent of the dataset.

References

Aybar, C., Wu, Q., Bautista, L., Yali, R. and Barja, A., 2020. rgee: An R package for interacting with Google Earth Engine. Journal of Open Source Software, 5(51), p.2272.

D'Agostino McGowan L., and Bryan J., 2022. googledrive: An Interface to Google Drive. https://googledrive.tidyverse.org, https://github.com/tidyverse/googledrive.

Hijmans, R.J., Bivand, R., Forner, K., Ooms, J., Pebesma, E. and Sumner, M.D., 2022. Package 'terra'. Maintainer: Vienna, Austria.

Examples

dates <- dynamic_proj_dates("2018-01-01", "2018-12-01", interval = 3,interval.level = "month")


data("sample_extent_data")
user.email<-as.character(gargle::gargle_oauth_sitrep()$email)

matrix<-get_moving_window(radial.distance = 10000,
                            spatial.res.degrees = 0.05,
                            spatial.ext = sample_extent_data)

extract_buffered_raster(dates = dates,
                       datasetname = "MODIS/006/MCD12Q1",
                       bandname="LC_Type5",
                       spatial.res.metres = 500,
                       GEE.math.fun = "sum",
                       moving.window.matrix = matrix,
                       user.email = user.email,
                       categories=c(6,7),
                       agg.factor = 12,
                       spatial.ext = sample_extent_data,
                       varname = "total_grass_crop_lc",
                       save.directory = tempdir())

dynamicSDM documentation built on June 28, 2024, 5:08 p.m.