% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequential_scan.R
\name{sequential_scan}
\alias{sequential_scan}
\title{Sequential Scan for Secondary Clusters}
\usage{
sequential_scan(
  data,
  cases,
  population,
  region_id = NULL,
  x = NULL,
  y = NULL,
  node_id = NULL,
  tree = NULL,
  tree_node_id = NULL,
  tree_parent_id = NULL,
  max_iter = 5L,
  alpha = 0.05,
  nsim = 999L,
  max_pop_pct = 0.5,
  buffer_size = 0L,
  model = c("poisson", "binomial"),
  seed = NULL,
  verbose = TRUE,
  n_cores = 1L
)
}
\arguments{
\item{data}{A \code{data.frame} whose columns are named by the
\code{cases}, \code{population} and (depending on scan type)
\code{region_id}, \code{x}, \code{y}, \code{node_id} arguments.}

\item{cases}{Column of \code{data} giving case counts. Given as an
unquoted column name (a string or expression also works).}

\item{population}{Column of \code{data} giving the denominator.}

\item{region_id, x, y}{Columns of \code{data} (omit for tree-only scan).}

\item{node_id}{Column of \code{data} (omit for circular scan).}

\item{tree}{Tree as a 2-column data.frame
(\code{node_id, parent_id}), or use
\code{tree_node_id}/\code{tree_parent_id}. Omit for circular scan.}

\item{tree_node_id, tree_parent_id}{Optional. Parallel vectors as an
alternative to \code{tree}.}

\item{max_iter}{Integer. Maximum number of iterations (including the
primary MLC). Default 5.}

\item{alpha}{Numeric. Significance level. Iteration stops when the
MLC p-value of the current reduced data exceeds \code{alpha}.
Default 0.05.}

\item{nsim}{Integer. Monte Carlo replications per iteration.
Default 999.}

\item{max_pop_pct}{Numeric. Maximum zone-size constraint, passed to
the inner scans. Default 0.5.}

\item{buffer_size}{Integer. Number of nearest-neighbour regions to
remove together with each detected cluster, computed by Euclidean
distance from each cluster region to the remaining ones. Default
0. Zhang et al. (2010) report that the type I error and power are
essentially insensitive to the buffer size and that
\code{buffer_size = 0} is generally adequate. Ignored for
tree-only scans.}

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

\item{seed}{Integer or \code{NULL}. Seed for the first iteration;
subsequent iterations advance the RNG state to avoid using the
same seed across iterations.}

\item{verbose}{Logical. Print progress at each iteration.}

\item{n_cores}{Integer. OpenMP threads passed to inner scans.}
}
\value{
An object of class \code{"sequential_scan"} with components:
  \describe{
    \item{clusters}{A data.frame with one row per iteration performed,
      with columns \code{iteration}, \code{node_id} (only for
      tree-spatial / tree-only scans), \code{n_regions} (only for
      scans with a spatial component), \code{cases}, \code{expected},
      \code{population}, \code{rr} (only for scans with a spatial
      component), \code{llr}, \code{pvalue}, and a logical
      \code{significant} flag (\code{pvalue <= alpha}). The list-
      columns \code{region_ids} and/or \code{leaf_ids} carry the
      cluster composition.}
    \item{iterations}{A list with the full scan result of each
      iteration.}
    \item{regions, tree, alpha, nsim, buffer_size, n_iter,
          scan_type}{Bookkeeping fields. \code{n_iter} is the number
      of iterations actually performed.}
  }
}
\description{
Implements the sequential adjustment of Zhang, Assuncao and Kulldorff
(2010) for detecting secondary clusters. After the most likely cluster
(MLC) is detected and found significant, the regions composing it
(optionally together with a buffer of nearest-neighbour regions) are
\emph{removed} from the dataset -- treated as a \dQuote{lake} with no
population and no cases -- and the scan is re-run on the reduced data
with a fresh Monte Carlo simulation. The procedure is iterated until
the MLC of the current reduced data is no longer significant, or
\code{max_iter} is reached.
}
\details{
This differs from \code{\link{filter_clusters}}, which scans the
single-pass candidate pool for non-overlapping clusters (the original
Cancado et al. 2025 criterion). The sequential approach computes a
fresh, unconservative p-value for each secondary cluster, conditional
on the prior detections.

Inputs are supplied through a single \code{data} data.frame; the
relevant columns are referenced by name. Which columns are supplied
selects one of three scan types:
\itemize{
  \item tree-spatial: all of \code{cases}, \code{population},
        \code{region_id}, \code{x}, \code{y}, \code{node_id},
        \code{tree} are required (\code{data} in long format, one row
        per (region, leaf));
  \item circular: \code{cases}, \code{population}, \code{region_id},
        \code{x}, \code{y} (no \code{node_id} / \code{tree};
        one row per region);
  \item tree-only: \code{cases}, \code{population}, \code{node_id},
        \code{tree} (no spatial inputs). \code{buffer_size} is ignored
        for the tree-only case.
}
}
\examples{
\donttest{
data(london_collisions); data(london_tree)
result <- sequential_scan(
  london_collisions,
  cases       = cases,
  population  = population,
  region_id   = region_id,
  x           = x,
  y           = y,
  node_id     = node_id,
  tree        = london_tree,
  max_iter = 3, nsim = 99, seed = 42
)
print(result)
}
}
\references{
Zhang, Z., Assuncao, R., & Kulldorff, M. (2010). Spatial scan
statistics adjusted for multiple clusters. \emph{Journal of
Probability and Statistics}, 2010, 642379.

Cancado, A. L. F., Oliveira, G. S., Quadros, A. V. C., & Duczmal,
L. H. (2025). A tree-spatial scan statistic. \emph{Environmental
and Ecological Statistics}, 32, 953-978.
\doi{10.1007/s10651-025-00670-w}

Kulldorff, M. (1997). A spatial scan statistic.
\emph{Communications in Statistics - Theory and Methods}, 26(6),
1481-1496.
}
\seealso{
\code{\link{treespatial_scan}}, \code{\link{circular_scan}},
  \code{\link{tree_scan}}, \code{\link{filter_clusters}},
  \code{\link{get_cluster_regions}}
}
