Skip to contents

Supercell-level metrics

Source: R/sc_metrics_supercells.R
sc_metrics_supercells.Rd

Computes per-supercell distance diagnostics

Usage

sc_metrics_supercells(
  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

An sf object with one row per supercell and columns:

supercells

Supercell ID.

mean_spatial_dist

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

mean_value_dist

Mean value distance from cells to the supercell center in value space. Lower values indicate more homogeneous supercells. Returned as mean_value_dist_scaled when scale = TRUE.

mean_combined_dist

Mean combined distance using compactness and step to scale value and spatial distances. Overall distance; mainly useful for ranking.

balance

Signed log ratio of scaled value distance to scaled spatial distance. 0 indicates balance; negative values indicate spatial dominance; positive values indicate value dominance. Returns NA when either scaled component is zero.

Details

If sc lacks supercells, x, or y columns, they are derived from geometry and row order, which may differ from the original centers. 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_global()

Examples

library(supercells)
vol = terra::rast(system.file("raster/volcano.tif", package = "supercells"))
vol_sc = sc_slic(vol, step = 8, compactness = 7)
cl = sc_metrics_supercells(vol, vol_sc)
head(cl)
#> Simple feature collection with 6 features and 5 fields
#> Geometry type: POLYGON
#> Dimension:     XY
#> Bounding box:  xmin: 2667400 ymin: 6479025 xmax: 2667500 ymax: 6479575
#> Projected CRS: NZGD49 / New Zealand Map Grid
#>   supercells mean_spatial_dist_scaled mean_value_dist_scaled mean_combined_dist
#> 1          1                0.4095206             0.09007318          0.4222508
#> 2          2                0.4312237             0.06200361          0.4380981
#> 3          3                0.3717557             0.16420635          0.4168714
#> 4          4                0.4261679             0.14332676          0.4633701
#> 5          5                0.4191004             0.30019033          0.5423462
#> 6          6                0.4520404             0.30186667          0.5812408
#>      balance                       geometry
#> 1 -1.5143648 POLYGON ((2667400 6479575, ...
#> 2 -1.9394344 POLYGON ((2667410 6479495, ...
#> 3 -0.8171130 POLYGON ((2667400 6479405, ...
#> 4 -1.0897063 POLYGON ((2667450 6479335, ...
#> 5 -0.3336939 POLYGON ((2667440 6479245, ...
#> 6 -0.4037861 POLYGON ((2667460 6479165, ...