% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api.R
\name{gwpr}
\alias{gwpr}
\title{Fit a Geographically Weighted Panel Regression (main entry point)}
\usage{
gwpr(
  formula,
  data,
  spatial,
  id,
  time,
  family = c("gaussian", "binomial"),
  model = c("within", "pooling", "random"),
  effect = c("individual", "time", "two-way", "nested"),
  bandwidth = NULL,
  bandwidth_method = c("sgd", "grid", "random"),
  bandwidth_control = list(),
  kernel = c("bisquare", "gaussian", "exponential", "tricube", "boxcar"),
  adaptive = FALSE,
  threshold = 0.5,
  workers = 1L,
  seed = NULL,
  diagnostics = TRUE,
  ...
)
}
\arguments{
\item{formula}{A \code{formula} object specifying the model (e.g.
\code{y ~ x1 + x2}).}

\item{data}{A \code{data.frame} containing the panel data.  Must include
the columns referenced by \code{id} and \code{time}.}

\item{spatial}{An \code{sf} object with one row per spatial unit.  Must
include the column referenced by \code{id}.}

\item{id}{Character scalar.  Name of the unit (individual) ID column shared
by \code{data} and \code{spatial}.}

\item{time}{Character scalar.  Name of the time-period column in \code{data}.}

\item{family}{Character scalar.  Model family: \code{"gaussian"} (default,
linear GWPR) or \code{"binomial"} (binary panel logistic GWPR).}

\item{model}{Character scalar.  Panel model type: \code{"within"} (default),
\code{"pooling"}, or \code{"random"}.}

\item{effect}{Character scalar.  Panel effect: \code{"individual"} (default),
\code{"time"}, \code{"two-way"}, or \code{"nested"}.}

\item{bandwidth}{Numeric scalar or \code{NULL} (default).  When \code{NULL}
the bandwidth is selected automatically via \code{select_bandwidth()}.}

\item{bandwidth_method}{Character scalar.  Method for automatic bandwidth
search: \code{"sgd"} (default), \code{"grid"}, or \code{"random"}.
Ignored when \code{bandwidth} is supplied.}

\item{bandwidth_control}{Named list of control parameters passed to the
bandwidth search function.  For \code{"grid"}: \code{lower}, \code{upper},
\code{step}.  For \code{"sgd"}: \code{lower}, \code{upper}, learning rate
etc.  For \code{"random"}: \code{lower}, \code{upper}, \code{n_samples}.}

\item{kernel}{Character scalar.  Kernel function: \code{"bisquare"}
(default), \code{"gaussian"}, \code{"exponential"}, \code{"tricube"}, or
\code{"boxcar"}.}

\item{adaptive}{Logical scalar.  \code{FALSE} (default) uses a fixed
distance bandwidth; \code{TRUE} uses an adaptive (k-nearest-neighbour)
bandwidth.}

\item{threshold}{Numeric scalar.  Classification threshold for
\code{family = "binomial"} (default \code{0.5}).}

\item{workers}{Positive integer.  Number of parallel workers.  \code{1}
(default) uses serial execution; values \code{> 1} enable explicit
parallelism.}

\item{seed}{Integer or \code{NULL}.  Random seed for reproducibility of any
stochastic steps (bandwidth search, parallel RNG).}

\item{diagnostics}{Logical scalar.  When \code{TRUE} (default),
\code{diagnose_gwpr()} is called after fitting and its results are stored
in the returned object.}

\item{...}{Additional arguments passed to the bandwidth search or fitting
functions.}
}
\value{
A \code{gwpr_fit} object.  Key fields:
\describe{
  \item{\code{local_results}}{Per-unit local model results.}
  \item{\code{predictions}}{In-sample predicted values / probabilities.}
  \item{\code{residuals}}{Residuals or Pearson residuals.}
  \item{\code{metrics}}{Overall goodness-of-fit metrics.}
  \item{\code{spatial_results}}{Data frame of per-unit coefficients.}
  \item{\code{search}}{Bandwidth search result (\code{gwpr_bandwidth}), or
    \code{NULL} when bandwidth was supplied directly.}
  \item{\code{diagnostics}}{A \code{gwpr_diagnostics} object, or
    \code{NULL}.}
}
}
\description{
Orchestrates the complete GWPR pipeline: input validation, data preparation,
optional memory estimation, optional bandwidth search, model fitting, and
optional diagnostics.
}
\examples{
\donttest{
# Minimal linear GWPR with a fixed bandwidth
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)
)
fit <- gwpr(y ~ x1, data = dat, spatial = pts, id = "id", time = "time",
            bandwidth = 2, diagnostics = FALSE, workers = 1)
print(fit)
}

}
