ssim_bandwidth: Bandwidth selection for polygon maps

In SSIMmap: The Structural Similarity Index Measure for Maps

Bandwidth selection for polygon maps

Description

Computes bias–variance trade-off curves for two polygon maps using an adaptive Gaussian kernel. The two input variables can be optionally transformed (e.g. normal scores or min–max normalisation) before smoothing. A suggested bandwidth range is obtained by balancing standardized bias and variance for each variable, and a single bandwidth is chosen from this range.

Usage

ssim_bandwidth(
  shape,
  map1,
  map2,
  max_bandwidth,
  transform = c("normal_score", "percentile", "none", "minmax"),
  option = "midpoint"
)

Arguments

shape	An sf polygon object with attributes containing the two variables of interest.
map1	Character string; column name in shape for the first map.
map2	Character string; column name in shape for the second map.
max_bandwidth	Integer (at least 12). Upper bound of the bandwidth k for the adaptive k-nearest-neighbour kernel. Must not exceed the number of polygons.
transform	One of c("normal_score","percentile","none","minmax"). "normal_score" applies a Blom normal scores transform; "percentile" maps values to empirical percentiles in (0, 1); "minmax" applies min–max normalisation to [0, 1]; and "none" leaves the variables on their original scale.
option	Character string specifying how to choose a single bandwidth from the bias–variance trade-off range: one of "midpoint", "lower", or "upper" (default "midpoint"). The square-root of the number of polygons (sqrt(n)) is also shown on the plot as a reference.

Details

This function does *not* compute SSIM; it is intended to be used in combination with ssim_polygon(), which can then be called with the selected bandwidth.

The kernel is Gaussian with adaptive bandwidth:

w_{ij} = \exp\left\{-\tfrac12 (d_{ij} / h_i)^2 \right\},

where d_{ij} is the distance between polygon centroids and h_i is the distance from polygon i to its k-th nearest neighbour. Bandwidth selection is based purely on bias–variance trade-off and does not involve any SSIM computation or permutation testing.

Value

A list with components:

plot	A ggplot object showing the bias–variance trade-off curves for both variables, the suggested bandwidth range, the chosen bandwidth, and sqrt(n) as a reference.
bandwidth	The chosen bandwidth k_star.
tradeoff	A list with elements map1, map2, kA, kB, and k_sqrt, where map1 and map2 are data frames containing the standardized bias and variance across k for each variable.

SSIMmap documentation built on May 8, 2026, 1:07 a.m.