circular_scan: Kulldorff's Circular Spatial Scan Statistic

In treeSS: Tree-Spatial Scan Statistic for Cluster Detection

Kulldorff's Circular Spatial Scan Statistic

Description

Performs Kulldorff's circular spatial scan statistic for detecting spatial clusters. Inputs are passed as parallel vectors with one entry per region (cases must already be aggregated to the region level).

Usage

circular_scan(
  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

cases	Numeric vector of length n (one entry per region): total cases in each region.
population	Numeric vector of length n: population (or denominator) of each region.
region_id	Vector of region identifiers, length n.
x, y	Numeric vectors of region centroid coordinates, length n.
max_pop_pct	Numeric. Default 0.5.
nsim	Integer. Number of MC simulations. Default 999.
alpha	Numeric. Significance level. Default 0.05.
n_secondary	Integer. Default 1000.
model	Character. "poisson" or "binomial".
seed	Integer or NULL. Random seed for the Monte Carlo loop. When non-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.
n_cores	Integer. OpenMP threads.

Value

An object of class "circular_scan".

References

Kulldorff, M. (1997). A spatial scan statistic. Communications in Statistics - Theory and Methods, 26(6), 1481-1496.

See Also

filter_clusters, tree_scan, treespatial_scan, get_cluster_regions, iterative_scan

Examples

set.seed(42)
n <- 20
cases <- rpois(n, lambda = 10)
cases[1:5] <- rpois(5, lambda = 30)

result <- circular_scan(
  cases       = cases,
  population  = rep(1000, n),
  region_id   = 1:n,
  x           = runif(n, 0, 10),
  y           = runif(n, 0, 10),
  nsim        = 99
)
print(result)

treeSS documentation built on May 16, 2026, 1:08 a.m.