Skip to contents

Build Spatial Weights from Municipality Polygons

Source: R/sus_mod_spatial_weights.R
sus_mod_spatial_weights.Rd

Constructs a spdep spatial weights object from an sf data frame of municipality (or any polygon) boundaries. The result — a climasus_weights object — is the required input for all other sus_mod_spatial_* functions in the climasus4r pipeline.

Usage

sus_mod_spatial_weights(
  municipalities,
  style = "W",
  queen = TRUE,
  snap = NULL,
  zero_policy = TRUE,
  return_matrix = FALSE,
  lang = "pt",
  verbose = TRUE
)

Arguments

municipalities

An sf object with polygon or multipolygon geometry. Typically the result of geobr::read_municipality() or any shape file read with sf::st_read(). A column named code_muni is used as row labels when present; otherwise integer indices are used.

style

Character. Weight normalisation style passed to spdep::nb2listw(). One of "W" (default), "B", "C", "U", "S", "minmax". See Weight styles section.

queen

Logical. If TRUE (default) Queen contiguity is used (shared edge or vertex). If FALSE, Rook contiguity (shared edge only).

snap

Numeric or NULL. Snap distance tolerance passed to spdep::poly2nb(). NULL (default) uses 1e-3. See Snap distance section.

zero_policy

Logical. If TRUE (default) municipalities with no neighbours ("islands") are allowed — their spatial lag is set to NA. If FALSE an error is raised when islands are found.

return_matrix

Logical. If TRUE, a dense \(n \times n\) spatial weights matrix W is included in the output (slot $W). This can be memory-intensive for large datasets. Default FALSE.

lang

Character. Language for CLI messages: "pt" (default), "en", "es".

verbose

Logical. Print progress messages. Default TRUE.

Value

A climasus_weights object (named list with class c("climasus_weights", "list")) containing:

$listw

spdep listw object ready for spatial modelling.

$nb

spdep nb neighbour list (before weight normalisation).

$n_regions

Integer. Total number of regions / municipalities.

$n_islands

Integer. Number of regions with zero neighbours.

$island_ids

Character or integer vector of island identifiers (empty if none).

$W

Dense numeric \(n \times n\) weight matrix, or NULL when return_matrix = FALSE.

$style

Character. Weight normalisation style used.

$call

The matched call().

Details

Contiguity neighbours are detected with spdep::poly2nb(), which supports both Queen (default, shared edge or vertex) and Rook (shared edge only) contiguity. Municipalities that share no boundary ("spatial islands") are automatically detected and reported. The resulting neighbour list is normalised to a listw object via spdep::nb2listw().

Snap distance

Municipal boundaries digitised at different scales often have small gaps or overlaps at shared borders. The snap argument passes a distance tolerance (in the units of the CRS) to spdep::poly2nb(): any two polygon boundaries within snap distance are treated as touching. The default (NULL) uses 1e-3 (appropriate for degree-based CRS such as EPSG:4674 / SIRGAS2000). For projected CRS (metres) consider values around 1 to 100.

Weight styles

  • "W" (default) — row-standardised: each neighbour weight = 1/n_neighbours

  • "B" — binary: 1 if neighbour, 0 otherwise

  • "C" — globally standardised

  • "U" — equal to "C" divided by number of neighbours

  • "S" — variance-stabilising (Tiefelsdorf et al. 1999)

  • "minmax" — min/max normalisation

References

Bivand, R. S., Pebesma, E., & Gomez-Rubio, V. (2013). Applied Spatial Data Analysis with R (2nd ed.). Springer.

Cliff, A. D., & Ord, J. K. (1981). Spatial Processes: Models and Applications. Pion.

Anselin, L. (1988). Spatial Econometrics: Methods and Models. Kluwer Academic.

See also

sus_mod_spatial_reg() for spatial lag model (SAR/SLM), sus_mod_spatial_reg() for spatial error model (SEM), sus_mod_spatial_bayes() for Bayesian hierarchical spatial models, sus_mod_spatial_scan() for spatial scan statistics.

Examples

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

# Download Nordeste municipalities (SIRGAS2000 / EPSG:4674)
muni <- geobr::read_municipality(code_muni = "all", year = 2022)
muni_ne <- muni[muni$abbrev_state %in% c("CE","RN","PB","PE","AL",
                                         "SE","BA","PI","MA"), ]

# Row-standardised Queen contiguity (default)
w <- sus_mod_spatial_weights(muni_ne)
print(w)

# Binary Rook weights, returning the dense W matrix
w_rook <- sus_mod_spatial_weights(
  municipalities = muni_ne,
  style          = "B",
  queen          = FALSE,
  return_matrix  = TRUE
)
dim(w_rook$W)
} # }