Skip to contents

Build richer OD-level residual diagnostics for adjusted versus benchmark flows

Source: R/validate_flows.R
validate_flow_residuals.Rd

Extends validate_flow_pairs() with residual-style aliases, absolute and percentage residuals, improvement diagnostics, standard-deviation flags for large remaining adjusted residuals, and a convenience table of the worst remaining OD pairs after adjustment. This is useful when you want to move beyond method-level fit and inspect where the adjustment helped, did not help, or made residuals worse.

Usage

validate_flow_residuals(
  adj_df,
  benchmark_od_df,
  flow_col_mpd = "flow",
  flow_col_adj = "flow_adj",
  flow_col_bench = "flow",
  top_n = 10L,
  method_name = NA_character_
)

Arguments

adj_df

Data frame with at least origin, destination, an MPD flow column (default "flow"), and an adjusted flow column (default "flow_adj"). If present, mpd_source is carried through.

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".

top_n

Number of OD pairs to retain in the top_worst table, ranked by the absolute residual remaining after adjustment. Default 10.

method_name

Optional label for the adjustment method. Stored in the summary, data, and top_worst outputs.

Value

A list with:

  • summary: one-row tibble with mean/median residual magnitudes and signed and absolute residual-reduction summaries, shares improved, worsened, unchanged, and MPD versus adjusted residual shares above 1, 2, and 3 standard deviations,

  • data: OD-level tibble containing original and adjusted signed residuals using the package convention Y - X, signed residual movement, absolute residual reduction, percentage residuals, standard-deviation diagnostics for MPD and adjusted residuals, and an improvement_flag,

  • top_worst: the top_n OD pairs with the largest absolute residual remaining after adjustment.

Signed residuals use the shared comparison convention: adjusted_vs_benchmark is benchmark - adjusted, raw_vs_benchmark is benchmark - raw, and raw_vs_adjusted is adjusted - raw. The exact signed movement requested by the Stage 2 validation plan is stored as signed_residual_reduction; algebraically this equals adjusted - raw. For a direction-free "positive means less benchmark error" comparison, use abs_residual_reduction or improvement_flag.