Distinction

Distinction is an average distance between the focus region and all of the other regions. This value is between 0 and 1, where large value indicates that the values in the region stands out from the other regions.

reg_distinction(
  region,
  raster,
  dist_fun = "euclidean",
  sample_size = 1,
  unit = "log2",
  na.rm = FALSE,
  optimize_for = c("memory", "speed"),
  ...
)

Arguments

region

An object of class sf with a POLYGON or MULTIPOLYGON geometry type

raster

An object of class SpatRaster (terra)

dist_fun

Distance measure used. This function uses philentropy::distance (run philentropy::getDistMethods() to find possible distance measures) or proxy::dist (run names(proxy::pr_DB$get_entries()) to find possible distance measures) in the background. It is also possible to use "dtw" (dynamic time warping)

sample_size

Proportion of the cells inside of each region to be used in calculations. Value between 0 and 1. It is also possible to specify an integer larger than 1, in which case the specified number of cells of each region will be used in calculations.

unit

a character string specifying the logarithm unit that should be used to compute distances that depend on log computations.

na.rm

Whether NA values should be stripped from the calculations.

optimize_for

A character string specifying what to optimize for (default: "memory"). "memory" extracts values on the fly for each comparison, which minimizes memory usage but can be substantially slower for large rasters or many regions. "speed" caches per-region extracts once and reuses them across comparisons, which increases memory usage but is typically much faster.

...

Additional arguments for philentropy::dist_one_one, proxy::dist, or dtwclust::dtw_basic. When dist_fun = "dtw" is used, ndim should be set to specify how many dimension the input raster time-series has.

Value

A vector with the distinction values

Examples

if (FALSE) { # \dontrun{
  library(terra)
  if (requireNamespace("sf", quietly = TRUE)) {
    library(sf)
    volcano = rast(system.file("raster/volcano.tif", package = "regional"))
    vr = read_sf(system.file("regions/volcano_regions.gpkg", package = "regional"))
    vr$dis = reg_distinction(vr, volcano, sample_size = 0.5)

    mean(vr$dis)

    plot(volcano)
    plot(vect(vr), add = TRUE)
    plot(volcano)
    plot(vr["dis"], add = TRUE)
 }
} # }