get_cluster_regions: Extract Cluster Membership for Each Region

In treeSS: Tree-Spatial Scan Statistic for Cluster Detection

Extract Cluster Membership for Each Region

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.).

Usage

get_cluster_regions(result, n_clusters = 1L, overlap = TRUE, ...)

## Default S3 method:
get_cluster_regions(result, n_clusters = 1L, overlap = TRUE, ...)

## S3 method for class 'iterative_scan'
get_cluster_regions(result, n_clusters = 1L, overlap = TRUE, ...)

Arguments

result	Either a "treespatial_scan"/"circular_scan" object (single-pass scan) or an "iterative_scan" object.
n_clusters	Integer. (Single-pass methods only.) Number of clusters to extract. 1 returns only the most likely cluster. Values greater than 1 use filter_clusters internally to identify distinct secondary clusters. Default is 1. Ignored for iterative-scan inputs (every iteration is returned).
overlap	Logical. If TRUE (default), returns a facet-ready data.frame: all regions are replicated for each cluster panel, with a panel column for faceting and cluster marked only for member regions. If FALSE, returns one row per region assigned to its highest-ranked cluster (for single-panel maps).
...	Further arguments passed to methods.

Details

This is a generic with methods for objects returned by treespatial_scan, circular_scan, and iterative_scan.

Value

A data.frame with columns from result$regions plus:

cluster

Integer cluster number (1 = most likely / first iteration, 2 = first secondary / second iteration, etc.), or NA if the region is not in the cluster.

node_id

The tree node of the cluster, or NA.

llr

The log-likelihood ratio of the cluster, or NA.

pvalue

The p-value of the cluster, or NA.

pvalue_adjusted, significant

(Iterative method only) The Holm-Bonferroni adjusted p-value and corresponding significance flag for the iteration.

panel

(Only when overlap = TRUE) A two-line label for 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 "#1 P209\n(LR=39.6)"; for iterative scans it looks like "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.

See Also

treespatial_scan, circular_scan, iterative_scan, filter_clusters

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)

treeSS documentation built on May 16, 2026, 1:08 a.m.