Build a CAR adjacency graph

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)