car_graph: Build a CAR adjacency graph

In stLMM: Bayesian Spatial and Space-Time Linear Mixed Models

Build a CAR adjacency graph

Description

Normalizes an areal adjacency structure for use in car(), dagar(), car_time(), and dagar_time() terms in stLMM formulas.

Usage

car_graph(graph, id = NULL, queen = TRUE, island = c("error", "nearest"),
  island_k = 1L)

## S3 method for class 'stLMM_car_graph'
plot(x, show_ids = FALSE, show_nodes = TRUE,
  show_bridges = TRUE, color_by_degree = FALSE, ...)

## S3 method for class 'stLMM_graph'
plot(x, show_ids = FALSE, show_nodes = TRUE,
  color_by_degree = FALSE, ...)

Arguments

graph	An sf polygon object or a square symmetric adjacency matrix.
x	A graph object returned by car_graph() or an internal stLMM_graph object stored in a fitted model backend.
id	For sf inputs, the polygon ID column used to match car(area_id, graph = ...), dagar(area_id, graph = ...), or dagar_time(area_id, time, graph = ...) values.
queen	For sf inputs, whether to use queen-style boundary touching. If FALSE, rook-style edge sharing is used.
island	Policy for disconnected polygon components. The default "error" reports disconnected or isolated areas. "nearest" adds nearest-neighbor bridge edges between disconnected sf polygon components.
island_k	Positive integer number of nearest bridge edges to add from the selected disconnected component at each connection step when island = "nearest".
show_ids	Logical; if TRUE, draw graph IDs at node locations.
show_nodes	Logical; if TRUE, draw representative node points.
show_bridges	Logical; if TRUE, bridge edges added by island = "nearest" are highlighted.
color_by_degree	Logical; if TRUE, color polygons or nodes by graph degree.
...	Additional arguments passed to the internal graph plotting helper.

Details

The graph stores binary adjacency, not a row-standardized matrix. The CAR implementation uses a degree-scaled proper CAR precision proportional to D - rho W, where D is the diagonal degree matrix and W is the symmetric binary adjacency matrix. This is equivalent to a CAR conditional specification with row-standardized neighbor averaging in the conditional mean, E(w_i \mid w_{-i}) = rho d_i^{-1}\sum_{j \sim i} w_j, with conditional variance sigma_sq / d_i. The process variance sigma_sq is supplied as the model term's variance parameter. Isolated areas currently error. Disconnected components also error by default.

For matrix input, row and column names define the graph IDs. If names are not present, integer IDs are used. Matrix input must be square, symmetric, and have no isolated rows. Nonzero off-diagonal entries are treated as adjacency indicators and are stored as binary edges. Nearest-neighbor island bridging is not available for matrix input because no polygon geometry is available.

For sf input, id names the polygon identifier column. The helper uses polygon boundary relationships to build a binary adjacency matrix. With queen = TRUE, polygons that touch at a point or along an edge are neighbors. With queen = FALSE, polygons must share an edge.

With island = "nearest", disconnected components are connected by artificial nearest-neighbor bridge edges based on polygon representative-point distances. These edges are stored in island_added_edges so the graph construction choice is auditable.

For teaching and auditability, a useful workflow is to first call car_graph() with the default island = "error" and then rerun with island = "nearest" only when disconnected island components are expected.

The plot() methods return ggplot2 objects. For sf-based graphs, polygons are drawn with graph edges overlaid. For matrix-based graphs, a deterministic circular node layout is used. Internal DAGAR graph objects are drawn with directed arrows from each parent node to its child node, making the ordering-induced directed graph visible.

Value

An object of class stLMM_car_graph. The object stores graph IDs, degree information, and lower-triangle edge pairs used by car(), dagar(), car_time(), and dagar_time(). Island-bridging metadata are stored in island_policy, island_k, island_components_initial, and island_added_edges.

See Also

stunitco, stLMM, stLMM-terms

Examples

adj <- matrix(
  c(
    0, 1, 0, 0,
    1, 0, 1, 0,
    0, 1, 0, 1,
    0, 0, 1, 0
  ),
  nrow = 4,
  byrow = TRUE,
  dimnames = list(paste0("a", 1:4), paste0("a", 1:4))
)
g <- car_graph(adj)

stLMM documentation built on Nov. 12, 2026, 1:07 a.m.