Skip to contents

Global supercells metrics

Source: R/sc_metrics_global.R
sc_metrics_global.Rd

Computes global distance diagnostics for supercells

Usage

sc_metrics_global(
  x,
  sc,
  metrics = c("spatial", "value", "combined", "balance"),
  scale = TRUE,
  step,
  compactness,
  dist_fun = NULL
)

Arguments

x

The input SpatRaster used to create sc.

sc

An sf object returned by sc_slic().

metrics

Character vector of metric ideas to return. Options: "spatial", "value", "combined", "balance". Default: c("spatial", "value", "combined", "balance").

scale

Logical. If TRUE, scales spatial and value distances; output columns are named with the _scaled suffix.

step

A step value used for the supercells If missing, uses attr(sc, "step") when available

compactness

A compactness value used for the supercells If missing, uses attr(sc, "compactness") when available. Compactness mode is read from attr(sc, "compactness_method") when available.

dist_fun

A distance function name or function, as in sc_slic(). If missing or NULL, uses attr(sc, "dist_fun") when available.

Value

A data.frame with a single row and columns:

step

Step size used to generate supercells. Returned in meters when the input used step = use_meters(...), otherwise in cells.

compactness

Compactness value used to generate supercells; NA for adaptive compactness.

compactness_method

Compactness method: "constant" for fixed compactness, "local_max" for adaptive compactness.

n_supercells

Number of supercells with at least one non-missing pixel.

mean_value_dist / mean_value_dist_scaled

Mean per-supercell value distance from cells to their supercell centers, averaged across supercells. Returned as mean_value_dist (or mean_value_dist_scaled when scale = TRUE). Lower values indicate more homogeneous supercells.

mean_spatial_dist / mean_spatial_dist_scaled

Mean per-supercell spatial distance from cells to their supercell centers, averaged across supercells; units are grid cells (row/column index distance). If the input supercells were created with step = use_meters(...), distances are reported in meters. Returned as mean_spatial_dist (or mean_spatial_dist_scaled when scale = TRUE). Lower values indicate more compact supercells.

mean_combined_dist

Mean per-supercell combined distance, computed from value and spatial distances using compactness and step, averaged across supercells. Returned as mean_combined_dist. Lower values indicate lower overall distance and are mainly useful for ranking.

balance

Mean signed log ratio of scaled value distance to scaled spatial distance (averaged across supercells); 0 indicates balance between value and spatial terms, negative values indicate spatial dominance, and positive values indicate value dominance. Supercells with a zero scaled component are excluded; NA is returned if none remain.

Details

Requires sc with metadata columns (supercells, x, y). If they are missing, they are derived from geometry and row order. Use outcomes = c("supercells", "coordinates", "values") when calling sc_slic() or supercells() to preserve original centers and IDs. Metrics are averaged across supercells (each supercell has equal weight). With adaptive compactness (set compactness = use_adaptive() in sc_slic()), value distances are scaled separately for each center using a local maximum calculated from its final position and search window. The combined and balance metrics use these scaled distances.

See also

sc_slic(), sc_metrics_pixels(), sc_metrics_supercells()

Examples

library(supercells)
vol = terra::rast(system.file("raster/volcano.tif", package = "supercells"))
vol_sc = sc_slic(vol, step = 8, compactness = 7)
sc_metrics_global(vol, vol_sc)
#>   step compactness compactness_method n_supercells mean_spatial_dist_scaled
#> 1    8           7           constant           88                0.4466124
#>   mean_value_dist_scaled mean_combined_dist    balance
#> 1              0.3710111          0.6294388 -0.2780825