Choropleth Map of Kulldorff Spatial Scan Cluster Results

Renders a choropleth map from a climasus_spatial_scan object produced by sus_mod_spatial_scan(). Each municipality polygon is coloured either by its cluster's Relative Risk (RR, continuous diverging scale) or by a categorical cluster label, making it straightforward to communicate the location, extent, and intensity of spatial health clusters.

Usage

sus_mod_plot_spatial_scan(
  x,
  municipalities,
  show_rr = TRUE,
  alpha = 0.05,
  title = NULL,
  lang = "pt",
  ...
)

Arguments

x

A climasus_spatial_scan object returned by sus_mod_spatial_scan().

municipalities

An sf object with POLYGON or MULTIPOLYGON geometry containing a code_muni column that matches the identifiers stored in x$most_likely_cluster$location_ids and x$secondary_clusters.

show_rr

Logical. TRUE (default) colours municipalities by Relative Risk using a continuous diverging scale. FALSE uses categorical cluster-membership colours.

alpha

Numeric in (0, 1). Significance threshold used to decide which cluster borders to emphasise. Must match the value used when running sus_mod_spatial_scan(). Default 0.05.

title

Character or NULL. Plot title. If NULL (default) a localised default title is used.

lang

Character. Output language: "pt" (default), "en", "es".

...

Currently unused; reserved for future extensions.

Value

A ggplot object. Assign to a variable to modify further or pass to ggplot2::ggsave().

Colour encoding

When show_rr = TRUE (default), the fill variable is the numeric RR of the cluster that each municipality belongs to. Background municipalities (cluster_id == 0) receive NA and are rendered in "grey80". A diverging gradient (navy to white to red) centred on RR = 1 is used. Municipalities belonging to a significant cluster (p-value < alpha) additionally receive a thicker border (linewidth = 1.5) to distinguish them from the most-likely cluster when it is not itself significant.

When show_rr = FALSE, municipalities are filled with categorical colours: the most-likely cluster, up to nine secondary clusters, and the background each receive a distinct colour via ggplot2::scale_fill_manual().

See also

sus_mod_spatial_scan(), sus_spatial_join(), sus_mod_plot_vulnerability()

Examples

if (FALSE) { # \dontrun{
library(geobr)
library(dplyr)

muni_sf <- geobr::read_municipality(code_muni = 31, year = 2020)
muni_sf <- dplyr::rename(muni_sf, code_muni = code_muni)

set.seed(1)
df_cases <- tibble::tibble(
  code_muni  = as.character(muni_sf$code_muni),
  cases      = rpois(nrow(muni_sf), 5),
  population = sample(5000:200000, nrow(muni_sf), replace = TRUE)
)

result <- sus_mod_spatial_scan(
  df             = df_cases,
  cases          = "cases",
  population     = "population",
  municipalities = muni_sf,
  n_simulations  = 199L,
  lang           = "pt"
)

# Continuous RR map (default)
sus_mod_plot_spatial_scan(result, municipalities = muni_sf, lang = "pt")

# Categorical cluster-membership map
sus_mod_plot_spatial_scan(result, municipalities = muni_sf,
                          show_rr = FALSE, lang = "en")
} # }