dynamic_proj_covariates {dynamicSDM}  R Documentation 
Combine explanatory variable rasters into covariates for each projection date.
Description
Explanatory variable rasters are imported, resampled to a given spatial resolution and extent, stacked and then exported as a covariate data frame or raster stack for each projection date.
Usage
dynamic_proj_covariates(
dates,
varnames,
drive.folder,
user.email,
local.directory,
spatial.ext,
spatial.mask,
spatial.res.degrees,
resample.method,
cov.file.type,
prj = "+proj=longlat +datum=WGS84",
cov.prj,
save.directory,
save.drive.folder,
static.rasters,
static.varnames,
static.resample.method,
static.moving.window.matrix,
static.GEE.math.fun
)
Arguments
dates 
a character string, vector of dates in format "YYYYMMDD". 
varnames 
a character string, the unique names for each explanatory variable. 
drive.folder 
optional; a character string or vector, Google Drive folder or folders to read projection covariate rasters from. Folder must be uniquely named within Google Drive. Do not provide path. 
user.email 
optional; a character string, user email for initialising Google Drive. Required
if 
local.directory 
optional; a character string or vector, path to local directory or directories to read projection covariate rasters from. 
spatial.ext 
optional; the spatial extent to crop explanatory variable
rasters to. Object of class 
spatial.mask 
an object of class 
spatial.res.degrees 
optional; a numeric value, the spatial resolution in degrees for
projection rasters to be resampled to. Required if 
resample.method 
a character string or vector length of varnames, specifying resampling
method to use. One of 
cov.file.type 
a character string, the type of file to export projection covariates as. One
of: 
prj 
a character string, the coordinate reference system desired for projection covariates. Default is "+proj=longlat +datum=WGS84". 
cov.prj 
a character string, the coordinate reference system desired for output projection
covariates. Default is assumed to be the same as 
save.directory 
optional; a character string, path to local directory to save projection covariates to. 
save.drive.folder 
optional; a character string, Google Drive folder to save projection covariates to. Folder must be uniquely named within Google Drive. Do not provide path. 
static.rasters 
a RasterStack of one or more rasters to be added to covariates for each date. 
static.varnames 
a character string or vector, the unique names for each
explanatory variable in order of rasters in 
static.resample.method 
a character string or vector length of 
static.moving.window.matrix 
optional; a matrix of weights with an odd number
of sides, representing the spatial neighbourhood of cells (“moving
window”) to calculate 
static.GEE.math.fun 
optional; a character string, the mathematical function to
compute across the specified spatial matrix for each cell in 
Value
Exports combined covariates in "csv" or "tif" file for each projection date to the local directory or Google Drive folder.
Input variable rasters
For each projection date, the rasters for each explanatory variable are imported from a local directory or Google Drive folder.
Such rasters should be uniquely named "tif" files within the directory or drive folder and
contain the variable name (as stated in varnames
) and projection date in format "YYYYMMDD".
If more than one “tif” file in the Google Drive folder or local directory matches the projection
date and explanatory variable name, then the function will error.
Processing rasters
If required, rasters are cropped and resampled to the same spatial extent and
resolution. If spatial.mask
is given, then cells with NA in this mask layer
are removed from the returned projection covariates. See terra::mask()
in R
package terra
for details (Hijmans et al., 2022).
Rasters are then stacked and reprojected if cov.prj
is different to prj
.
Note: if explanatory variable rasters are not of the same spatial resolution and extent, then the
function will error. Resample methods (resample.method
) include:

near
: Each cell acquires the value of its nearest neighbour cell in the original raster. This is typically used for categorical variables. 
bilinear
: the distanceweighted average of the four nearest cells are used to estimate a new cell value. This is typically used for continuous variables.
If only one resample.method
is given, but these are more than one explanatory variables, the
same resample.method
is used for all.
Output covariates
The raster stacks are then converted into data frames or remain as raster stacks depending on
cov.file.type
. Column names or raster layer names will be the unique explanatory variable names
(varnames
). These are exported to the local directory or Google Drive folder with file names
containing the relevant projection date in "YYYYMMDD" format.
Google Drive compatibility
If drive.folder
or save.drive.folder
given, please ensure the folder name is unique within
your Google Drive. Do not provide the path if the folder is nested within others.
If one of drive.folder
or save.drive.folder
are used then user.email is required to access the
appropriate Google Drive user account. This requires users to have installed R package
googledrive
and initialised Google Drive with valid login credentials. Please follow
instructions on https://googledrive.tidyverse.org/.
Static rasters
If static datasets are to be added into the dynamic projection covariates, then five arguments are available to specify their inclusion.
Please provide the static rasters in RasterStack format, specifying any
spatial buffering needed (using static.moving.window.matrix
and
static.GEE.math.fun
as described below).
The resample method or methods for rasters within the static raster stack need
to be specified too using static.resample.method
. Please also provide
static.varnames
to name the static variables in the covariate data exported.
#' # Spatial buffering of static rasters (optional)
Using the focal
function from terra
R package (Hijmans et al., 2022),
GEE.math.fun
is calculated across the spatial buffer area from the record
coordinate. The spatial buffer area used is specified by the argument
moving.window.matrix
, which dictates the neighbourhood of cells
surrounding the cell containing the occurrence record to include in this
calculation.
See function get_moving_window()
to generate appropriate
moving.window.matrix
.
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".
References
Hijmans, R.J., Bivand, R., Forner, K., Ooms, J., Pebesma, E. and Sumner, M.D., 2022. Package 'terra'. Maintainer: Vienna, Austria.
Examples
data("sample_extent_data")
# Set extraction variables
projectiondates < dynamic_proj_dates("20180101", "20181201", interval = 3,interval.level =
"month")
variablenames < c("eight_sum_prec", "year_sum_prec")
spatial.res.metres < 500
cov_resolution < 0.05
# Get Google Drive email
user.email<as.character(gargle::gargle_oauth_sitrep()$email)
extract_dynamic_raster(dates=projectiondates,
datasetname = "UCSBCHG/CHIRPS/DAILY",
bandname="precipitation",
user.email = user.email,
spatial.res.metres = spatial.res.metres,
GEE.math.fun = "sum",
temporal.direction = "prior",
temporal.res = 56,
spatial.ext = sample_extent_data,
varname = variablenames[1],
save.directory = tempdir())
extract_dynamic_raster(dates=projectiondates,
datasetname = "UCSBCHG/CHIRPS/DAILY",
bandname="precipitation",
user.email = user.email,
spatial.res.metres = spatial.res.metres,
GEE.math.fun = "sum",
temporal.direction = "prior",
temporal.res = 364,
spatial.ext = sample_extent_data,
varname = variablenames[2],
save.directory = tempdir())
dynamic_proj_covariates(dates = projectiondates,
varnames = variablenames,
local.directory = tempdir(),
spatial.ext = sample_extent_data,
spatial.mask = sample_extent_data,
spatial.res.degrees = cov_resolution,
resample.method = c("bilinear","bilinear"),
cov.file.type = "csv",
prj="+proj=longlat +datum=WGS84",
save.directory = tempdir())