% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tree_scan.R
\name{tree_scan}
\alias{tree_scan}
\title{Tree-Based Scan Statistic}
\usage{
tree_scan(
  tree = NULL,
  cases,
  population = NULL,
  nsim = 999L,
  alpha = 0.05,
  model = c("poisson", "binomial"),
  seed = NULL,
  n_cores = 1L,
  tree_node_id = NULL,
  tree_parent_id = NULL
)
}
\arguments{
\item{tree}{A \code{data.frame} with columns \code{node_id} and
\code{parent_id}. Root node(s) must have \code{parent_id = NA}.
Alternatively, pass the tree as parallel vectors via
\code{tree_node_id} and \code{tree_parent_id}.}

\item{cases}{A numeric vector of case counts at the leaf level.}

\item{population}{A numeric vector of population at the leaf level, or a
single value. For the binomial model, \code{population} is the number
of trials (cases + controls) per leaf and is required. For the
Poisson model, defaults to \code{1} per leaf if \code{NULL}.}

\item{nsim}{Integer. Number of Monte Carlo simulations. Default is
\code{999}.}

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

\item{model}{Character. Likelihood model: either \code{"poisson"}
(default) 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. Number of OpenMP threads for the Monte Carlo
loop. Default is \code{1L} (serial). Set higher to parallelize.}

\item{tree_node_id, tree_parent_id}{Optional parallel vectors describing
the tree as an alternative to the \code{tree} data.frame. Both must
have the same length, and the root node(s) must have
\code{tree_parent_id = NA}. Ignored when \code{tree} is supplied.}
}
\value{
An object of class \code{"tree_scan"} (see package help for
  details).
}
\description{
Performs the tree-based scan statistic for detecting clusters in
hierarchical data. Uses a Poisson or binomial model with Monte Carlo
simulation (implemented in C++ via Rcpp) for significance testing.
}
\examples{
tree <- data.frame(
  node_id   = c(1, 2, 3, 4, 5, 6, 7, 8),
  parent_id = c(NA, 1, 1, 2, 2, 3, 3, 3)
)
cases <- c(50, 5, 3, 2, 4)
pop   <- c(100, 100, 100, 100, 100)

result <- tree_scan(tree, cases, population = pop, nsim = 99)
print(result)
}
\references{
Kulldorff, M., Fang, Z., & Walsh, S. J. (2003). A tree-based scan
statistic for database disease surveillance. \emph{Biometrics}, 59(2),
323–331.
}
\seealso{
\code{\link{circular_scan}}, \code{\link{treespatial_scan}},
  \code{\link{aggregate_tree}}
}
