% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/filter_clusters.R
\name{filter_clusters}
\alias{filter_clusters}
\title{Filter Overlapping Secondary Clusters}
\usage{
filter_clusters(result, alpha = NULL)
}
\arguments{
\item{result}{An object of class \code{"treespatial_scan"},
\code{"circular_scan"}, or \code{"tree_scan"}.}

\item{alpha}{Numeric. Significance level for filtering. Default is
\code{NULL}, which uses the alpha from the original analysis.}
}
\value{
A \code{data.frame} of distinct significant clusters ordered by
  descending LLR.
}
\description{
Removes overlapping secondary clusters from the output of
\code{\link{treespatial_scan}}, \code{\link{circular_scan}}, or
\code{\link{tree_scan}}.
}
\details{
For \code{treespatial_scan} objects, two clusters overlap if they have
BOTH tree overlap (one node is ancestor/descendant of the other) AND
spatial overlap (same center or identical set of regions). This follows
Cancado et al. (2025).

For \code{circular_scan} objects, the criterion follows Kulldorff (1997):
a secondary cluster is distinct if its center is not contained in any
previously retained cluster's zone, and no previously retained cluster's
center is contained in the candidate zone.

For \code{tree_scan} objects, a secondary cluster is distinct if its node
is NOT an ancestor or descendant of any previously retained node. This
follows Kulldorff et al. (2003).

When a dominant signal saturates the candidate pool (making distinct
secondary clusters hard to find), or when clusters shadow each other,
consider using \code{\link{sequential_scan}} (Zhang, Assuncao and
Kulldorff, 2010), which re-runs the scan after removing each detected
cluster.
}
\examples{
data(london_collisions); data(london_tree)
result <- treespatial_scan(
  london_collisions,
  cases       = cases,
  population  = population,
  region_id   = region_id,
  x           = x,
  y           = y,
  node_id     = node_id,
  tree        = london_tree,
  nsim        = 99, seed = 42
)
filter_clusters(result)

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

Kulldorff, M., Fang, Z., & Walsh, S. J. (2003). A tree-based scan
statistic for database disease surveillance. \emph{Biometrics}, 59(2),
323-331.

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