% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/iterative_scan.R
\name{iterative_scan}
\alias{iterative_scan}
\title{Iterative Scan}
\usage{
iterative_scan(
  cases = NULL,
  population = NULL,
  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,
  model = c("poisson", "binomial"),
  seed = NULL,
  verbose = TRUE,
  n_cores = 1L
)
}
\arguments{
\item{cases}{Numeric vector. For tree-spatial scan: one entry per
(region, leaf) row. For circular: one entry per region. For tree-only:
one entry per leaf.}

\item{population}{Numeric vector parallel to \code{cases}.}

\item{region_id, x, y}{Vectors parallel to \code{cases} (omit for
tree-only scan).}

\item{node_id}{Vector parallel to \code{cases} (omit for circular and
tree-only scans).}

\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.}

\item{alpha}{Numeric. Significance threshold applied to Holm-Bonferroni
adjusted p-values.}

\item{nsim}{Integer. MC simulations per iteration.}

\item{max_pop_pct}{Numeric. Passed to inner scans.}

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

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

\item{verbose}{Logical.}

\item{n_cores}{Integer. OpenMP threads.}
}
\value{
An object of class \code{"iterative_scan"} with components:
  \describe{
    \item{clusters}{A data.frame with one row per iteration, containing
      the raw p-value (\code{pvalue}), the Holm-Bonferroni adjusted
      p-value (\code{pvalue_adjusted}), a logical \code{significant}
      column, plus the cluster's node, regions, cases, expected, RR, and
      LLR.}
    \item{iterations}{A list with the full scan result of each iteration.}
    \item{regions, tree, alpha, n_iter, scan_type}{Bookkeeping fields.}
  }
}
\description{
Runs the scan statistic iteratively, removing the cases of each detected
cluster before the next iteration. Supports tree-spatial, circular, and
tree-only scans, dispatched by which arguments are supplied.
}
\details{
\strong{Note on methodology.} This iterative procedure is \emph{not} part
of the original tree-spatial scan statistic of Cancado et al. (2025). It is
an extension inspired by the conditional scan approach of Zhang et al.
(2010), which sequentially removes cases attributed to detected clusters
before re-running the scan to find additional, distinct anomalies. To
reproduce the secondary-cluster procedure described in Section 5.1.1 of
Cancado et al. (2025), use \code{\link{filter_clusters}} or
\code{\link{get_cluster_regions}} with \code{n_clusters > 1} on a single
scan result instead.

\strong{Multiple-testing correction.} Because each iteration is a separate
hypothesis test on data that has been modified by the previous iteration,
the raw p-values overstate significance. This function collects raw p-values
from all iterations performed and applies the Holm-Bonferroni correction
(\code{\link[stats]{p.adjust}} with \code{method = "holm"}) at the end. The
returned \code{clusters} data.frame includes both the raw p-value
(\code{pvalue}) and the adjusted p-value (\code{pvalue_adjusted}), plus a
logical \code{significant} column indicating whether the cluster is
significant after correction at level \code{alpha}.

The loop stops early only when the residual signal is exhausted (the most
likely cluster has \code{LR = 0} or zero cases), not based on raw p-values,
since the multiple-testing correction depends on the full set of tests.
}
\examples{
\donttest{
data(london_collisions); data(london_tree)
result <- iterative_scan(
  cases       = london_collisions$cases,
  population  = london_collisions$population,
  region_id   = london_collisions$region_id,
  x           = london_collisions$x,
  y           = london_collisions$y,
  node_id     = london_collisions$node_id,
  tree        = london_tree,
  max_iter = 3, nsim = 99, seed = 42
)
print(result)
}
}
\references{
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.

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

Zhang, Z., Assuncao, R., & Kulldorff, M. (2010). Spatial scan statistics
adjusted for multiple clusters. \emph{Journal of Probability and
Statistics}, 2010, 642379.

Holm, S. (1979). A simple sequentially rejective multiple test procedure.
\emph{Scandinavian Journal of Statistics}, 6(2), 65-70.
}
\seealso{
\code{\link{treespatial_scan}}, \code{\link{circular_scan}},
  \code{\link{tree_scan}}, \code{\link{filter_clusters}},
  \code{\link{get_cluster_regions}}
}
