apply_threshold {flexurba} | R Documentation |
Identify urban areas by applying a threshold on grid cells
Description
The function identifies urban areas by applying a threshold to individual grid cells. Two key decisions must be made regarding the thresholding approach:
-
How is the threshold value determined?
The threshold can be predefined by the user (
type="predefined"
) or derived from the data (type="data-driven"
).
-
How and where is the threshold enforced?
The threshold can be enforced consistently across the study area (= absolute approach,
regions=NULL
) or tailored within specific regions (= relative approach,regions
notNULL
).
For more details on these thresholding approaches, including their advantages and limitations, see the vignette("vig8-apply-thresholds")
The table below outlines the appropriate combination of function arguments for each approach:
Absolute Approach | Relative Approach | |
Predefined Value | type="predefined" with threshold_value not NULL , and regions=NULL | type="predefined" with threshold_value not NULL , and regions not NULL |
Data-Driven Value | type="data-driven" with fun not NULL , and regions=NULL | type="data-driven" with fun not NULL , and regions not NULL |
Usage
apply_threshold(
grid,
type = "predefined",
threshold_value = NULL,
fun = NULL,
...,
regions = NULL,
operator = "greater_than",
smoothing = TRUE
)
Arguments
grid |
SpatRaster with the data |
type |
character. Either |
threshold_value |
numeric or vector. The threshold value used to identify urban areas when |
fun |
character or function. This function is used to derive the threshold value from the data when |
... |
additional arguments passed to fun |
regions |
character, SpatRaster or sf object. If not
|
operator |
character. Operator used to enforce the threshold. Either |
smoothing |
logical. Whether to smooth the edges of the boundaries. If |
Value
named list with the following elements:
-
rboundaries
: SpatRaster in which cells that are part of an urban area have a value of '1' -
vboundaries
: sf object with the urban areas as separate polygons -
threshold
: dataframe with per region the threshold value that is applied -
regions
: SpatRaster with the gridded version of the regions that is employed
Examples
proxies <- load_proxies_belgium()
# option 1: predefined - absolute threshold
predefined_absolute <- apply_threshold(proxies$pop,
type = "predefined",
threshold_value = 1500
)
terra::plot(predefined_absolute$rboundaries)
# option 2: data-driven - absolute threshold
datadriven_absolute <- apply_threshold(proxies$pop,
type = "data-driven",
fun = "p90"
)
terra::plot(datadriven_absolute$rboundaries)
# in the examples below we will use 'Bruxelles', 'Vlaanderen' and 'Wallonie' as separate regions
regions <- convert_regions_to_grid(flexurba::units_belgium, proxies$pop, "NAME_1")
terra::plot(regions)
# option 3: predefined - relative threshold
# note that the threshold values are linked to the regions in alphabetical
# order based on their IDs. So, the threshold of 1500 is applied to
# 'Bruxelles', # 1200 to 'Vlaanderen', and 1000 to 'Wallonie'.
predefined_relative <- apply_threshold(proxies$pop,
type = "predefined",
threshold_value = c(1500, 1200, 1000),
regions = regions
)
terra::plot(predefined_relative$rboundaries)
# option 4: data-driven - relative threshold
datadriven_relative <- apply_threshold(proxies$pop,
type = "data-driven",
fun = "p95",
regions = regions
)
terra::plot(datadriven_relative$rboundaries)