ssim_polygon: Structural similarity index (SSIM) for polygon maps

In SSIMmap: The Structural Similarity Index Measure for Maps

Structural similarity index (SSIM) for polygon maps

Description

Computes local and global SSIM (and its components SIM, SIV, SIP) for two polygon maps using an adaptive k-nearest-neighbour (k-NN) Gaussian kernel. Input variables can be optionally transformed (e.g. rank-based inverse normal scores or min–max normalization). Optionally performs permutation tests for global and local significance with BH-FDR correction. Under the null hypothesis for the permutation test, both variables are randomly permuted at each iteration, breaking spatial structure and association between them. Local p-values can be optionally adjusted using the Benjamini–Hochberg FDR procedure.

Usage

ssim_polygon(
  shape,
  map1,
  map2,
  global = TRUE,
  bandwidth = NULL,
  transform = c("normal_score", "percentile", "none", "minmax"),
  k1 = NULL,
  k2 = NULL,
  do_test = FALSE,
  R = 1000,
  fdr = TRUE,
  alpha = 0.05,
  seed = NULL
)

Arguments

shape	An sf polygon object.
map1	Character string; column name in shape for the first map.
map2	Character string; column name in shape for the second map.
global	Logical. If TRUE, compute and print a summary table of global SSIM, SIM, SIV, SIP. If FALSE, return an sf object with local metrics (and local p-/q-values if do_test = TRUE).
bandwidth	Integer; adaptive k-NN size (number of neighbours). The default is ceiling(sqrt(n)), where n is the number of polygons. Must be at least 3 and not exceed n.
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.
k1, k2	SSIM constants. If NULL, defaults are k1 = 0.01, k2 = 0.03.
do_test	Logical; if TRUE, perform permutation tests for global and local SSIM. Local p-values can be FDR-adjusted if fdr = TRUE.
R	Integer; number of permutations for the significance tests (default R = 1000).
fdr	Logical; if TRUE (default), apply Benjamini–Hochberg FDR correction to local p-values.
alpha	Numeric; significance threshold for local results (default 0.05). Local features with q_value < alpha are flagged as significant.
seed	Optional integer; random seed for reproducibility of the permutation tests.

Value

If global = TRUE and do_test = FALSE, the function prints a knitr table summarising the global mean, minimum, maximum, and standard deviation of SSIM, SIM, SIV, and SIP, and returns this data.frame (invisibly).

If global = TRUE and do_test = TRUE, the function prints the same summary table plus a table of global permutation p-values (two-sided) for SSIM, SIM, SIV, and SIP, and returns (invisibly) a list with components:

• summary: data.frame with global SSIM/SIM/SIV/SIP summary statistics;

• p_global: data.frame with global means and permutation p-values for SSIM, SIM, SIV, SIP.

If global = FALSE, the function returns an sf object equal to shape with additional columns:

• SSIM, SIM, SIV, SIP: local similarity metrics for each polygon;

• p_value, q_value, sig (only if do_test = TRUE): local permutation p-value, FDR-adjusted q-value, and a logical flag indicating significance (q_value < alpha).

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