Plot validation LISA indicators on user-supplied boundaries — validate_flow_plot_lisa

Maps residual-derived Local Moran/LISA cluster classes returned by validate_flow_residual_structure(local_moran = TRUE). The function requires users to supply sf boundary objects because debiasR does not ship, download, or infer spatial boundaries. Optional outline boundaries can be supplied for larger administrative areas.

Usage

validate_flow_plot_lisa_map(
  structure_results,
  boundaries,
  boundary_area_col = "area",
  area_col = "area",
  comparisons = "adjusted_vs_benchmark",
  methods = NULL,
  method_col = "method",
  method_labels = NULL,
  cluster_col = "lisa_cluster",
  p_value_col = "p_value",
  p_value_threshold = 0.05,
  palette = NULL,
  missing_fill = "#F3F4F6",
  boundary_colour = NA,
  boundary_linewidth = 0,
  outline_boundaries = NULL,
  outline_colour = "white",
  outline_linewidth = 0.45,
  sort = c("none", "ascending", "descending"),
  sort_metric = c("significant_area_share", "mean_abs_local_moran", "mean_local_moran")
)

Arguments

structure_results: A data frame containing LISA map data, one validate_flow_residual_structure() result, or a named list of results. The data must contain lisa_cluster, which is produced when validate_flow_residual_structure(local_moran = TRUE).
boundaries: User-supplied sf polygon or multipolygon object with one row per area to map.
boundary_area_col: Column in boundaries identifying areas. Default "area".
area_col: Column in the validation map data identifying areas. Default "area".
comparisons: Flow comparison(s) to plot. Defaults to "adjusted_vs_benchmark". Use "all" when structure_results contains several comparison rows.
methods: Optional character vector of method identifiers or display labels to include. Default NULL includes all methods.
method_col: Column containing the method identifier. Default "method".
method_labels: Optional named character vector used to relabel methods.
cluster_col: Column containing LISA cluster classes. Default "lisa_cluster".
p_value_col: Column containing Local Moran/LISA p-values. Default "p_value".
p_value_threshold: Numeric threshold used to display statistically significant LISA clusters. Areas with p-values above this threshold are shown as not significant. Set NULL to plot cluster_col without p-value masking. Default 0.05.
palette: Optional named or unnamed character vector of colours for LISA clusters. Defaults to the supplied validation review palette plus neutral greys for non-significant or undefined areas.
missing_fill: Fill colour for boundaries that are not present in the validation results. Default "#F3F4F6".
boundary_colour: Boundary line colour for mapped areas. Default NA avoids drawing small-area internal borders.
boundary_linewidth: Boundary line width for mapped areas. Default 0.
outline_boundaries: Optional user-supplied sf object for larger administrative boundaries to draw over the mapped areas.
outline_colour: Larger-boundary outline colour. Default "white".
outline_linewidth: Larger-boundary outline width. Default 0.45.
sort: Method sort order. Use "none" to keep the supplied method order, "ascending" for smallest-to-largest values, or "descending" for largest-to-smallest values. The unadjusted raw MPD baseline remains at the final facet. Default "none".
sort_metric: LISA-map summary used when sort is not "none". "significant_area_share" sorts by the share of mapped areas in a significant LISA class, "mean_abs_local_moran" by the mean absolute Local Moran statistic, and "mean_local_moran" by the mean Local Moran statistic. Default "significant_area_share".

Value

A ggplot object.