flexurba (version 0.2.3)

apply_threshold: 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:

1. How is the threshold value determined?

   • The threshold can be predefined by the user (type="predefined") or derived from the data (type="data-driven").

2. 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 not NULL).

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
)

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

Arguments

grid

SpatRaster with the data

type

character. Either "predefined" or "data-driven".

threshold_value

numeric or vector. The threshold value used to identify urban areas when type="predefined". If regions is not NULL, a vector of threshold values can be provided, where each value corresponds to a specific region (the respective values are linked to regions in alphabetical order based on their IDs; see examples). In addition, ensure that the threshold values are in the same unit as the grid values.

fun

character or function. This function is used to derive the threshold value from the data when type="data-driven". Either as character: "min", "max", "mean", "median", or "pX" where X denotes a percentile value (e.g., p95 for the 95% percentile value"). It is also possible to provide a custom function for relatively small grids.

...

additional arguments passed to fun

regions

character, SpatRaster or sf object. If not NULL, a different threshold value is applied in the separate regions (i.e. a relative thresholding approach). The argument can either be:

• a SpatRaster with a separate value for each region

• the path to the region data (as character)

• an sf polygon layer In the latter two cases, the function convert_regions_to_grid() will be used to convert the regions to a gridded format.

operator

character. Operator used to enforce the threshold. Either "greater_than", "greater_or_equal", "smaller_than", "smaller_or_equal" or "equals".

smoothing

logical. Whether to smooth the edges of the boundaries. If TRUE, boundaries will be smoothed with the function apply_majority_rule().

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)