| 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 "YYYY-MM-DD". |
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 "YYYY-MM-DD".
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 distance-weighted 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 "YYYY-MM-DD" 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 log-in 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
co-ordinate. 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/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".
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("2018-01-01", "2018-12-01", 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 = "UCSB-CHG/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 = "UCSB-CHG/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())