Skip to contents

Validate residual structure and randomness diagnostics

Source: R/validate_flows.R
validate_flow_residual_structure.Rd

Builds residual-structure diagnostics for adjusted OD flows against benchmark OD flows. The helper reports residual correlation with benchmark flow, aggregates residuals to origin or destination areas for map-ready output, optionally computes global Moran's I from a user-supplied neighbour table, and optionally relates area-level residuals to a selected covariate.

Usage

validate_flow_residual_structure(
  adj_df,
  benchmark_od_df,
  flow_col_mpd = "flow",
  flow_col_adj = "flow_adj",
  flow_col_bench = "flow",
  method_name = NA_character_,
  residual_type = c("adjusted", "mpd"),
  spatial_role = c("origin", "destination"),
  residual_aggregation = c("mean", "sum"),
  area_neighbors = NULL,
  area_col = "area",
  neighbor_col = "neighbor",
  weight_col = NULL,
  local_moran = FALSE,
  local_moran_nsim = 999,
  local_moran_alpha = 0.05,
  local_moran_p_adjust = "BH",
  local_moran_seed = NULL,
  covariate_df = NULL,
  covariate_col = NULL,
  covariate_area_col = "area",
  geometry_df = NULL,
  geometry_area_col = "area",
  x_col = NULL,
  y_col = NULL,
  make_plots = FALSE
)

Arguments

adj_df

Data frame with at least origin, destination, an MPD flow column (default "flow"), and an adjusted flow column (default "flow_adj").

benchmark_od_df

Data frame with at least origin, destination, and a benchmark flow column (default "flow").

flow_col_mpd

Name of MPD flow column in adj_df. Default "flow".

flow_col_adj

Name of adjusted flow column in adj_df. Default "flow_adj".

flow_col_bench

Name of benchmark flow column in benchmark_od_df. Default "flow".

method_name

Optional label for the adjustment method. Stored in outputs.

residual_type

Residual series to diagnose: "adjusted" uses adjusted-minus-benchmark residuals, while "mpd" uses MPD-minus-benchmark residuals.

spatial_role

Area role used for area-level residual summaries: "origin" or "destination".

residual_aggregation

How OD residuals are aggregated to area level: "mean" or "sum".

area_neighbors

Optional neighbour table for Moran's I.

area_col

Column in area_neighbors identifying the focal area. Default "area".

neighbor_col

Column in area_neighbors identifying the neighbouring area. Default "neighbor".

weight_col

Optional positive numeric weight column in area_neighbors. If NULL, all neighbour links receive weight 1.

local_moran

Logical. If TRUE, compute Local Moran's I and LISA cluster classes from the selected area-level residuals and area_neighbors. Default FALSE.

local_moran_nsim

Positive whole number of random permutations used for Local Moran pseudo p-values. Default 999.

local_moran_alpha

Significance threshold used to classify LISA clusters after p-value adjustment. Default 0.05.

local_moran_p_adjust

P-value adjustment method passed to stats::p.adjust(). Default "BH".

local_moran_seed

Optional random seed for Local Moran permutation p-values. Default NULL.

covariate_df

Optional area-level covariate table.

covariate_col

Optional covariate column to correlate with area-level residuals. Requires covariate_df.

covariate_area_col

Area key in covariate_df. Default "area".

geometry_df

Optional area table with coordinates or geometry-like columns to join onto map_data.

geometry_area_col

Area key in geometry_df. Default "area".

x_col

Optional x-coordinate column in map_data, used only when make_plots = TRUE.

y_col

Optional y-coordinate column in map_data, used only when make_plots = TRUE.

make_plots

Logical. If TRUE, return ggplot objects for residual reduction distribution, residual-versus-benchmark scatter, optional residual-versus-covariate scatter, and optional coordinate residual map. Requires ggplot2.

Value

A list with:

  • summary: one-row tibble with flow correlation, Moran's I when available, and covariate correlation when requested,

  • flow_correlation: Pearson correlation between selected OD residuals and benchmark OD flows,

  • moran_i: Moran's I summary from the neighbour table, or NA when no neighbour table is supplied,

  • local_moran: optional Local Moran's I and LISA cluster table when local_moran = TRUE,

  • covariate_correlation: optional Pearson correlation between area-level residuals and the selected covariate,

  • od_level: OD-level residual table,

  • area_level: area-level residual table,

  • map_data: area-level residual table joined to geometry_df when supplied,

  • plots: optional ggplot objects when make_plots = TRUE.