% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api.R
\name{select_bandwidth}
\alias{select_bandwidth}
\title{Select an optimal bandwidth for GWPR}
\usage{
select_bandwidth(
  formula,
  data,
  spatial,
  id,
  time,
  family = c("gaussian", "binomial"),
  model = c("within", "pooling", "random"),
  effect = c("individual", "time", "two-way", "nested"),
  method = c("sgd", "grid", "random"),
  control = list(),
  kernel = c("bisquare", "gaussian", "exponential", "tricube", "boxcar"),
  adaptive = FALSE,
  threshold = 0.5,
  workers = 1L,
  seed = NULL,
  ...
)
}
\arguments{
\item{formula}{A \code{formula} object.}

\item{data}{A \code{data.frame} with panel data.}

\item{spatial}{An \code{sf} object.}

\item{id}{Character scalar; unit ID column name.}

\item{time}{Character scalar; time column name.}

\item{family}{\code{"gaussian"} or \code{"binomial"}.}

\item{model}{\code{"within"}, \code{"pooling"}, or \code{"random"}.}

\item{effect}{\code{"individual"}, \code{"time"}, \code{"two-way"}, or
\code{"nested"}.}

\item{method}{Bandwidth search method: \code{"sgd"} (default),
\code{"grid"}, or \code{"random"}.}

\item{control}{Named list of search control parameters.}

\item{kernel}{Kernel function name.}

\item{adaptive}{Logical; \code{TRUE} for adaptive (k-NN) bandwidth.}

\item{threshold}{Numeric; classification threshold (binomial only).}

\item{workers}{Positive integer; number of parallel workers.}

\item{seed}{Integer random seed, or \code{NULL}.}

\item{...}{Additional arguments (currently unused).}
}
\value{
A \code{gwpr_bandwidth} object with fields:
\describe{
  \item{\code{best_bandwidth}}{The selected bandwidth value.}
  \item{\code{best_score}}{The criterion value at the best bandwidth.}
  \item{\code{method}}{The search method used.}
  \item{\code{history}}{Search history data frame.}
}
}
\description{
Validates inputs, prepares data, and dispatches to the appropriate bandwidth
search algorithm: grid search, stochastic gradient descent (sgd), or random
search, depending on the \code{method} argument.
}
\examples{
\donttest{
library(sf)
pts <- sf::st_as_sf(
  data.frame(id = 1:4, X = c(0,1,0,1), Y = c(0,0,1,1)),
  coords = c("X", "Y"), crs = NA_integer_
)
dat <- data.frame(
  id   = rep(1:4, each = 5),
  time = rep(1:5, 4),
  y    = rnorm(20),
  x1   = rnorm(20)
)
bw <- select_bandwidth(
  y ~ x1, data = dat, spatial = pts, id = "id", time = "time",
  method  = "grid",
  control = list(lower = 0.5, upper = 2, step = 0.5),
  workers = 1
)
bw$best_bandwidth
}

}
