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-neighbor (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("none", "normal_score", "percentile", "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 neighbors). 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("none", "normal_score", "percentile", "minmax"). The default "none" retains the original values. "normal_score" applies a Blom normal scores transform; "percentile" maps values to empirical percentiles in (0, 1); "minmax" applies min–max normalization 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, SIM, SIV, and SIP. Tests are two-sided and centered on each statistic's permutation mean.
R	Integer; number of permutations for the significance tests (default R = 1000).
fdr	Logical; if TRUE (default), apply Benjamini–Hochberg FDR correction across polygons separately for each local statistic.
alpha	Numeric; significance threshold for local results (default 0.05). Local features with q <= alpha are flagged as significant when fdr = TRUE; otherwise use p <= alpha.
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 summarizing 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;

• With do_test = TRUE, each statistic has columns with suffixes _p, _q, and _sig, for example SIM_p, SIM_q, and SIM_sig. These contain its local permutation p-value, BH-adjusted q-value, and logical significance flag (q <= alpha). When fdr = FALSE, the _q columns equal the unadjusted p-values.

• p_value, q_value, sig remain aliases for SSIM_p, SSIM_q, SSIM_sig, respectively, for compatibility with earlier versions.

SSIMmap documentation built on Nov. 13, 2026, 5:09 p.m.