% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ssim_polygon.R
\name{ssim_polygon}
\alias{ssim_polygon}
\title{Structural similarity index (SSIM) for polygon maps}
\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{
\item{shape}{An \code{sf} polygon object.}

\item{map1}{Character string; column name in \code{shape} for the first map.}

\item{map2}{Character string; column name in \code{shape} for the second map.}

\item{global}{Logical. If \code{TRUE}, compute and print a summary table of
global SSIM, SIM, SIV, SIP. If \code{FALSE}, return an \code{sf} object
with local metrics (and local p-/q-values if \code{do_test = TRUE}).}

\item{bandwidth}{Integer; adaptive k-NN size (number of neighbours). The
default is \code{ceiling(sqrt(n))}, where \code{n} is the number of
polygons. Must be at least 3 and not exceed \code{n}.}

\item{transform}{One of \code{c("normal_score", "percentile", "none", "minmax")}.
\code{"normal_score"} applies a Blom normal scores transform;
\code{"percentile"} maps values to empirical percentiles in (0, 1);
\code{"minmax"} applies min–max normalisation to [0, 1]; and
\code{"none"} leaves the variables on their original scale.}

\item{k1, k2}{SSIM constants. If \code{NULL}, defaults are \code{k1 = 0.01},
\code{k2 = 0.03}.}

\item{do_test}{Logical; if \code{TRUE}, perform permutation tests for global
and local SSIM. Local p-values can be FDR-adjusted if \code{fdr = TRUE}.}

\item{R}{Integer; number of permutations for the significance tests
(default \code{R = 1000}).}

\item{fdr}{Logical; if \code{TRUE} (default), apply Benjamini–Hochberg
FDR correction to local p-values.}

\item{alpha}{Numeric; significance threshold for local results (default
\code{0.05}). Local features with \code{q_value < alpha} are flagged as
significant.}

\item{seed}{Optional integer; random seed for reproducibility of the
permutation tests.}
}
\value{
If \code{global = TRUE} and \code{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 \code{data.frame}
  (invisibly).

  If \code{global = TRUE} and \code{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 \code{list} with
  components:
  \itemize{
    \item \code{summary}: \code{data.frame} with global SSIM/SIM/SIV/SIP
      summary statistics;
    \item \code{p_global}: \code{data.frame} with global means and
      permutation p-values for SSIM, SIM, SIV, SIP.
  }

  If \code{global = FALSE}, the function returns an \code{sf} object equal to
  \code{shape} with additional columns:
  \itemize{
    \item \code{SSIM}, \code{SIM}, \code{SIV}, \code{SIP}: local similarity
      metrics for each polygon;
    \item \code{p_value}, \code{q_value}, \code{sig} (only if
      \code{do_test = TRUE}): local permutation p-value, FDR-adjusted q-value,
      and a logical flag indicating significance \code{(q_value < alpha)}.
  }
}
\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.
}
