extract_buffered_raster {dynamicSDM}  R Documentation 
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 "YYYYMMDD". 
spatial.ext 
the spatial extent for the extracted raster. Object from which extent
can be extracted of class 
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 remotesensing
dataset ( 
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 
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 
temporal.direction 
optional; a character string, the temporal direction for extracting
dynamic variable data across relative to each projection date given. One of 
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 
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/earthengine/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 postaggregation 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 login credentials. Please follow
instructions on the following website https://cran.rproject.org/package=rgee

datasetname
must be in the accepted Google Earth Engine catalogue layout (e.g. “MODIS/006/MCD12Q1” or “UCSBCHG/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/earthengine/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 login
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 remotesensing 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("20180101", "20181201", 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())