% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ssim_bandwith.R
\name{ssim_bandwidth}
\alias{ssim_bandwidth}
\title{Bandwidth selection for polygon maps}
\usage{
ssim_bandwidth(
  shape,
  map1,
  map2,
  max_bandwidth,
  transform = c("normal_score", "percentile", "none", "minmax"),
  option = "midpoint"
)
}
\arguments{
\item{shape}{An \code{sf} polygon object with attributes containing the two
variables of interest.}

\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{max_bandwidth}{Integer (at least 12). Upper bound of the bandwidth
\code{k} for the adaptive k-nearest-neighbour kernel. Must not exceed the
number of polygons.}

\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{option}{Character string specifying how to choose a single bandwidth
from the bias–variance trade-off range: one of
\code{"midpoint"}, \code{"lower"}, or \code{"upper"} (default
\code{"midpoint"}). The square-root of the number of polygons (\code{sqrt(n)})
is also shown on the plot as a reference.}
}
\value{
A list with components:
  \item{plot}{A \code{ggplot} object showing the bias–variance trade-off
    curves for both variables, the suggested bandwidth range, the chosen
    bandwidth, and \code{sqrt(n)} as a reference.}
  \item{bandwidth}{The chosen bandwidth \code{k_star}.}
  \item{tradeoff}{A list with elements
    \code{map1}, \code{map2}, \code{kA}, \code{kB}, and \code{k_sqrt},
    where \code{map1} and \code{map2} are data frames containing the
    standardized bias and variance across \code{k} for each variable.}
}
\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.
}
\details{
This function does *not* compute SSIM; it is intended to be used in
combination with \code{ssim_polygon()}, which can then be called with the
selected bandwidth.


The kernel is Gaussian with adaptive bandwidth:
\deqn{w_{ij} = \exp\left\{-\tfrac12 (d_{ij} / h_i)^2 \right\},}
where \eqn{d_{ij}} is the distance between polygon centroids and
\eqn{h_i} is the distance from polygon \eqn{i} to its \eqn{k}-th nearest
neighbour. Bandwidth selection is based purely on bias–variance trade-off
and does not involve any SSIM computation or permutation testing.
}
