blockCV: envBlock – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

envBlock

Use environmental clustering to separate train and test folds

Description

Environmental blocking for cross-validation. This function uses clustering methods to specify sets of similar environmental conditions based on the input covariates. Species data corresponding to any of these groups or clusters are assigned to a fold. This function does the clustering in raster space and species data. Clustering is done using kmeans for both approaches. This function works on single or multiple raster files; multiple rasters need to be in a raster brick or stack format.

Usage

envBlock(
  rasterLayer,
  speciesData,
  species = NULL,
  k = 5,
  standardization = "normal",
  rasterBlock = TRUE,
  sampleNumber = 10000,
  biomod2Format = TRUE,
  numLimit = 0,
  verbose = TRUE
)

Arguments

`rasterLayer`	A raster object of covariates to identify environmental groups.
`speciesData`	A simple features (sf) or SpatialPoints object containing species data (response variable).
`species`	Character. Indicating the name of the field in which species data (binary response i.e. 0 and 1) is stored. If `speceis = NULL` the presence and absence data (response variable) will be treated the same and only training and testing records will be counted. This can be used for multi-class responses such as land cover classes for remote sensing image classification, but it is not necessary. Do not use this argument when the response variable is continuous or count data.
`k`	Integer value. The number of desired folds for cross-validation. The default is `k = 5`.
`standardization`	Standardize input raster layers. Three possible inputs are "normal" (the default), "standard" and "none". See details for more information.
`rasterBlock`	Logical. If TRUE, the clustering is done in the raster layer rather than species data. See details for more information.
`sampleNumber`	Integer. The number of samples from raster layers to build the clusters.
`biomod2Format`	Logical. Creates a matrix of folds that can be directly used in the biomod2 package as a DataSplitTable for cross-validation.
`numLimit`	Integer value. The minimum number of points in each category of data (train_0, train_1, test_0 and test_1). Shows a message if the number of points in any of the folds happens to be less than this number.
`verbose`	Logical. To print the report of the recods per fold.

Details

As k-means algorithms use Euclidean distance to estimate clusters, the input covariates should be quantitative variables. Since variables with wider ranges of values might dominate the clusters and bias the environmental clustering (Hastie et al., 2009), all the input rasters are first standardized within the function. This is done either by normalizing based on subtracting the mean and dividing by the standard deviation of each raster (the default) or optionally by standardizing using linear scaling to constrain all raster values between 0 and 1.

By default, the clustering is done in the raster space. In this approach the clusters will be consistent throughout the region and across species (in the same region). However, this may result in a cluster(s) that covers none of the species records (the spatial location of response samples), espcially when species data is not dispersed throughout the region or the number of clusters (k or folds) is high. In this case, the number of folds is less than specified k. If rasterBlock = FALSE, the clustering will be done in species points and the number of the folds will be the same as k.

Note that the input raster layer should cover all the species points, otherwise an error will rise. The records with no raster value should be deleted prior to the analysis or another raster layer would be provided.

Value

An object of class S3. A list of objects including:

folds - a list containing the folds. Each fold has two vectors with the training (first) and testing (second) indices
foldID - a vector of values indicating the number of the fold for each observation (each number corresponds to the same point in species data)
biomodTable - a matrix with the folds to be used in biomod2 package
k - number of the folds
species - the name of the species (column), if provided
records - a table with the number of points in each category of training and testing

References

Hastie, T., Tibshirani, R., & Friedman, J. (2009). The elements of statistical learning: Data Mining, Inference, and Prediction (2nd ed., Vol. 1). Springer series in statistics New York.

Roberts et al., (2017). Cross-validation strategies for data with temporal, spatial, hierarchical, or phylogenetic structure. Ecography. 40: 913-929.

Examples

# load package data
awt <- raster::brick(system.file("extdata", "awt.grd", package = "blockCV"))
# import presence-absence species data
PA <- read.csv(system.file("extdata", "PA.csv", package = "blockCV"))
# make a sf object from data.frame
pa_data <- sf::st_as_sf(PA, coords = c("x", "y"), crs = raster::crs(awt))

# environmental clustering
eb <- envBlock(rasterLayer = awt,
               speciesData = pa_data,
               species = "Species", # name of the column with response
               k = 5,
               standardization = "standard",
               rasterBlock = TRUE)

blockCV

Spatial and Environmental Blocking for K-Fold Cross-Validation

v2.1.1

GPL-3

Authors

Roozbeh Valavi [aut, cre], Jane Elith [aut], José Lahoz-Monfort [aut], Gurutzeta Guillera-Arroita [aut]

Initial release

2020-02-16