% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_cluster_regions.R
\name{get_cluster_regions}
\alias{get_cluster_regions}
\alias{get_cluster_regions.default}
\alias{get_cluster_regions.iterative_scan}
\title{Extract Cluster Membership for Each Region}
\usage{
get_cluster_regions(result, n_clusters = 1L, overlap = TRUE, ...)

\method{get_cluster_regions}{default}(result, n_clusters = 1L, overlap = TRUE, ...)

\method{get_cluster_regions}{iterative_scan}(result, n_clusters = 1L, overlap = TRUE, ...)
}
\arguments{
\item{result}{Either a \code{"treespatial_scan"}/\code{"circular_scan"}
object (single-pass scan) or an \code{"iterative_scan"} object.}

\item{n_clusters}{Integer. (Single-pass methods only.) Number of
clusters to extract. \code{1} returns only the most likely cluster.
Values greater than 1 use \code{\link{filter_clusters}} internally
to identify distinct secondary clusters. Default is \code{1}.
Ignored for iterative-scan inputs (every iteration is returned).}

\item{overlap}{Logical. If \code{TRUE} (default), returns a facet-ready
data.frame: all regions are replicated for each cluster panel, with a
\code{panel} column for faceting and \code{cluster} marked only for
member regions. If \code{FALSE}, returns one row per region assigned
to its highest-ranked cluster (for single-panel maps).}

\item{...}{Further arguments passed to methods.}
}
\value{
A \code{data.frame} with columns from \code{result$regions} plus:
  \describe{
    \item{cluster}{Integer cluster number (1 = most likely / first
      iteration, 2 = first secondary / second iteration, etc.), or
      \code{NA} if the region is not in the cluster.}
    \item{node_id}{The tree node of the cluster, or \code{NA}.}
    \item{llr}{The log-likelihood ratio of the cluster, or \code{NA}.}
    \item{pvalue}{The p-value of the cluster, or \code{NA}.}
    \item{pvalue_adjusted, significant}{(Iterative method only) The
      Holm-Bonferroni adjusted p-value and corresponding significance
      flag for the iteration.}
    \item{panel}{(Only when \code{overlap = TRUE}) A two-line label
      for \code{facet_wrap}, with the cluster identifier on the first
      line and the test statistic on the second. For single-pass
      scans the label looks like \code{"#1 P209\\n(LR=39.6)"}; for
      iterative scans it looks like
      \code{"Iter 1: P209\\n(LR=39.6, p_adj=0.005)"}. The newline
      keeps long node identifiers from overflowing the strip in
      multi-panel layouts.}
  }
}
\description{
Returns a data.frame indicating which cluster (if any) each region
belongs to. This is the primary output for visualization — use it with
any mapping package (ggplot2, leaflet, tmap, etc.).
}
\details{
This is a generic with methods for objects returned by
\code{\link{treespatial_scan}}, \code{\link{circular_scan}}, and
\code{\link{iterative_scan}}.
}
\examples{
data(london_collisions); data(london_tree)
result <- treespatial_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,
  nsim        = 99, seed = 42
)

# Long format suitable for merging with a polygon layer.
cr <- get_cluster_regions(result, n_clusters = 2L, overlap = TRUE)
head(cr)

}
\seealso{
\code{\link{treespatial_scan}}, \code{\link{circular_scan}},
  \code{\link{iterative_scan}}, \code{\link{filter_clusters}}
}
