extract_dynamic_coords {dynamicSDM}

Extract temporally dynamic explanatory variable data for occurrence records.

Description

For each species occurrence record co-ordinate and date, temporally dynamic explanatory data are extracted using Google Earth engine

Usage

extract_dynamic_coords(
  occ.data,
  datasetname,
  bandname,
  spatial.res.metres,
  GEE.math.fun,
  save.method,
  temporal.res,
  temporal.direction,
  varname,
  resume = FALSE,
  save.directory
)

Arguments

occ.data

a data frame, with columns for occurrence record co-ordinates and dates with column names as follows; record longitude as "x", latitude as "y", year as "year", month as "month", and day as "day".

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.

spatial.res.metres

a numeric value, the spatial resolution in metres for data extraction.

GEE.math.fun

a character string, the mathematical function to compute across the temporal.res period for each record.

save.method

a character string, the method used to save extracted variable data. One of split or combined: can be abbreviated. See details.

temporal.res

a numeric value, the temporal resolution in days to extract data and calculate GEE.math.fun across from each record's date.

temporal.direction

a character string, the temporal direction for extracting data across relative to the record date. One of prior or post: can be abbreviated.

varname

optional; a character string, the unique name for the explanatory variable. Default varname is "bandname_temporal.res_temporal.direction_ GEE.math.fun".

resume

a logical indicating whether to search save.directory and start from previous progress by function. Only possible if save.method = split has been used.

save.directory

a character string, the path to a local directory to save extracted variable data to.

Details

For each individual species occurrence record co-ordinate and date, this function extracts data for a given band within a Google Earth Engine dataset across a user-specified period and calculates a mathematical function on such data.

Value

Returns details of successful explanatory variable extractions.

Google Earth Engine

extract_dynamic_coords() 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.

Mathematical function

GEE.math.fun specifies the mathematical function to be calculated over the temporal period from each record's date. 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

Please be aware, at current this function does not support the extraction of temporally dynamic variables for specific categories within categorical datasets.

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.

Exporting extracted data

For save.method = combined, the function with save “csv” files containing all occurrence records and associated values for the explanatory variable.

For save.method = split, the function will save individual “csv” files for each record with each unique period of the given temporal.level (e.g. each year, each year and month combination or each unique date).

split protects users if internet connection is lost when extracting data for large occurrence datasets. The argument resume can be used to resume to previous progress if connection is lost.

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.

Examples

data(sample_filt_data)



extract_dynamic_coords(occ.data=sample_filt_data,
 datasetname = "UCSB-CHG/CHIRPS/DAILY",
 bandname="precipitation",
 spatial.res.metres = 5566 ,
 GEE.math.fun = "sum",
 temporal.direction = "prior",
 temporal.res = 364,
 save.method = "split",
 resume = TRUE,
 varname = "total_annual_precipitation_prior",
 save.directory= tempdir())