Skip to contents

Estimate a compactness value

Source: R/sc_tune_compactness.R
sc_tune_compactness.Rd

Estimates a compactness value for a chosen raster scale. The current implementation supports one tuning metric, "local_variability", which estimates compactness directly from local value variability.

Usage

sc_tune_compactness(
  x,
  step = NULL,
  dist_fun = "euclidean",
  metric = "local_variability",
  stat = stats::median,
  k = NULL,
  centers = NULL,
  ...
)

Arguments

x

A SpatRaster (terra) or stars object.

step

Initial center spacing (alternative is k). Provide a plain numeric value for cell units, or use use_meters() for map-distance steps in meters (automatically converted to cells using raster resolution).

dist_fun

A supported distance name from sc_list_distances() or a custom function that takes two numeric vectors and returns one finite, nonnegative value. Smaller values must mean greater similarity.

metric

Which compactness metric to return. Currently only "local_variability" is supported. The argument is kept for future additions. For "local_variability", compactness = median(local_mean(d_value)) / dim_scale, where local means are computed in windows around initial centers and dim_scale is inferred from the number of raster layers and dist_fun. Root-sum-square measures use sqrt(n_layers), additive and path-sum measures use n_layers, and other named or custom measures use 1. This keeps compactness adjustable to dimensionality without requiring a separate user-facing scaling argument.

stat

The summary statistic to use for the local variability metric. Default is median. If it is NULL, all local variability values will be returned without summarization.

k

The number of supercells desired (alternative to step).

centers

Optional sf object of custom initial centers. Requires step.

...

Additional arguments for the compactness metric. For example, dim_scale for "local_variability" if you want to override the default scaling.

Value

A data frame with columns step, metric, dist_fun, and compactness. With the default stat = median, it contains one row. With stat = NULL, it contains one row per initial center, with step, metric, and dist_fun repeated for each row.

See also

sc_slic(), use_meters(), use_adaptive()

Examples

library(terra)
#> terra 1.9.50
vol = rast(system.file("raster/volcano.tif", package = "supercells"))
tune = sc_tune_compactness(vol, step = 8)
tune$compactness
#> [1] 9.241536