% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/circular_scan.R
\name{circular_scan}
\alias{circular_scan}
\title{Kulldorff's Circular Spatial Scan Statistic}
\usage{
circular_scan(
  data,
  cases,
  population,
  region_id,
  x,
  y,
  max_pop_pct = 0.5,
  nsim = 999L,
  alpha = 0.05,
  n_secondary = 1000L,
  model = c("poisson", "binomial"),
  seed = NULL,
  n_cores = 1L
)
}
\arguments{
\item{data}{A \code{data.frame} with one row per region. The
\code{cases}, \code{population}, \code{region_id}, \code{x} and \code{y}
arguments name columns of this data.frame.}

\item{cases}{Column of \code{data} giving the total cases in each region.
Given as an unquoted column name (a string or expression also works).}

\item{population}{Column of \code{data} giving the population (or
denominator) of each region.}

\item{region_id}{Column of \code{data} giving the region identifier.}

\item{x, y}{Columns of \code{data} giving the region centroid coordinates.}

\item{max_pop_pct}{Numeric. Default \code{0.5}.}

\item{nsim}{Integer. Number of MC simulations. Default \code{999}.}

\item{alpha}{Numeric. Significance level. Default \code{0.05}.}

\item{n_secondary}{Integer. Default \code{1000}.}

\item{model}{Character. \code{"poisson"} or \code{"binomial"}.}

\item{seed}{Integer or \code{NULL}. Random seed for the Monte
Carlo loop. When non-\code{NULL}, the user's pre-existing RNG
state is saved on entry and restored on exit, so the seed
argument affects only this call and does not leak into
subsequent draws in the user's session.}

\item{n_cores}{Integer. OpenMP threads.}
}
\value{
An object of class \code{"circular_scan"}.
}
\description{
Performs Kulldorff's circular spatial scan statistic for detecting
spatial clusters. Inputs are supplied through a single \code{data}
data.frame with one row per region (cases must already be aggregated to
the region level); the relevant columns are referenced by name.
}
\examples{
set.seed(42)
n <- 20
regions <- data.frame(
  region_id  = 1:n,
  cases      = rpois(n, lambda = 10),
  population = rep(1000, n),
  x          = runif(n, 0, 10),
  y          = runif(n, 0, 10)
)
regions$cases[1:5] <- rpois(5, lambda = 30)

result <- circular_scan(
  regions,
  cases       = cases,
  population  = population,
  region_id   = region_id,
  x           = x,
  y           = y,
  nsim        = 99
)
print(result)
}
\references{
Kulldorff, M. (1997). A spatial scan statistic. \emph{Communications in
Statistics - Theory and Methods}, 26(6), 1481-1496.
}
\seealso{
\code{\link{filter_clusters}}, \code{\link{tree_scan}},
  \code{\link{treespatial_scan}}, \code{\link{get_cluster_regions}},
  \code{\link{sequential_scan}}
}
