build_w: Build Spatial Weights Matrix

In saeHB.Spatial.Beta: Small Area Estimation Hierarchical Bayes for Spatial Beta Model

Build Spatial Weights Matrix

Description

This function constructs spatial weights matrices (W) for spatial modeling. It supports various methods including Contiguity, Distance-based, and Kernel-based weights, and provides a robust fallback mechanism to automatically connect isolated areas (islands).

Usage

build_w(
  data,
  coords = NULL,
  method = c("contiguity", "distance", "kernel"),
  contiguity = c("queen", "rook", "bishop"),
  distance = c("knn", "inverse_distance", "exponential"),
  k = 2,
  dmax = NULL,
  power = 1,
  alpha = 1,
  epsilon = 1e-12,
  kernel = c("uniform", "gaussian", "triangular", "epanechnikov", "quartic"),
  bandwidth = NULL,
  lonlat = TRUE,
  style = "W",
  zero.policy = TRUE,
  fallback = c("knn", "distance", "none"),
  fallback_k = 2,
  fallback_dmax = NULL,
  output = c("all", "matrix", "listw", "nb")
)

Arguments

data	An sf object (polygons/points) or a standard data frame. If a standard data frame is provided, coords must be specified.
coords	An N \times 2 matrix of coordinates. Required if data is not an sf object.
method	A string indicating the spatial weight construction method. Options are "contiguity", "distance", or "kernel".
contiguity	A string indicating the contiguity type. Options are "queen", "rook", or "bishop".
distance	A string indicating the distance-based type. Options are "knn", "inverse_distance", or "exponential".
k	An integer specifying the number of nearest neighbors for KNN methods. Default is 2.
dmax	A numeric specifying the maximum distance threshold for distance-based neighbors. The unit depends on lonlat (kilometers if TRUE, native coordinate units/meters if FALSE).
power	A numeric specifying the decay power for inverse distance weights. Default is 1.
alpha	A numeric specifying the decay parameter for exponential distance weights. Default is 1.
epsilon	A small numeric value to prevent division by zero in inverse distance calculation. Default is 1e-12.
kernel	A string indicating the type of spatial kernel. Options are "uniform", "gaussian", "triangular", "epanechnikov", or "quartic".
bandwidth	A numeric specifying the bandwidth (h) for kernel weights. Required if method = "kernel". The unit depends on lonlat (kilometers if TRUE, native coordinate units/meters if FALSE).
lonlat	Logical; if TRUE, coordinates are treated as Longitude/Latitude, spherical distances are calculated, and limits are in kilometers (km). If FALSE, coordinates are assumed to be planar (e.g., UTM), Euclidean distances are calculated, and limits are in the native unit of the coordinates (usually meters). Default is TRUE.
style	A character string specifying the spatial weights coding scheme ("W" for row-standardized or "B" for binary). Default is "W".
zero.policy	Logical; if TRUE, areas with no neighbors are allowed to have zero-weight rows. Default is TRUE.
fallback	A string indicating the fallback method for isolated areas (without neighbors) when using contiguity. Options are "knn", "distance", or "none". Default is "knn".
fallback_k	An integer specifying the number of neighbors for the fallback method. Default is 2.
fallback_dmax	A numeric specifying the maximum distance for the fallback method.
output	A string specifying the format of the output. Options are "all" (returns a comprehensive list), "matrix", "listw", or "nb". Default is "all".

Details

The function supports the following spatial weight construction methods:

• Contiguity: Queen, Rook, and Bishop.

• Distance-based: K-Nearest Neighbors (KNN), Inverse Distance, and Exponential.

• Kernel-based: Uniform, Gaussian, Triangular, Epanechnikov, and Quartic.

For distance and kernel methods, if lonlat = TRUE, spherical (great-circle) distances are calculated. For the kernel method specifically, distances are internally converted to kilometers.

Value

Depending on the output argument, this function returns:

• "matrix": An N \times N spatial weights matrix.

• "listw": A listw object compatible with spdep functions.

• "nb": An nb (neighborhood) object.

• "all": A list containing W (matrix), listw, nb, info (method details), and diag (diagnostic metrics for isolates and fallback).

Examples

# Generate random Longitude and Latitude coordinates for 10 areas
set.seed(123)
lon <- runif(10, min = 100, max = 140)
lat <- runif(10, min = -10, max = 10)
coords <- cbind(lon, lat)

# 1. Build KNN distance-based weights (k = 2) using spherical distance
W_knn <- build_w(
  data = NULL,
  coords = coords,
  method = "distance",
  distance = "knn",
  k = 2,
  lonlat = TRUE,
  output = "matrix"
)

# View the first few rows of the matrix
head(W_knn)

# 2. Build Gaussian Kernel weights using 500 km bandwidth
W_kernel <- build_w(
  data = NULL,
  coords = coords,
  method = "kernel",
  kernel = "gaussian",
  bandwidth = 500,
  lonlat = TRUE,
  output = "matrix"
)

# View the first few rows of the matrix
head(W_kernel)

saeHB.Spatial.Beta documentation built on July 1, 2026, 5:07 p.m.