Plot pairwise distributional allocation divergences — plot_validation_distribution

Builds an intuitive method-by-comparison divergence chart from validate_flow_distribution() summary rows. Lower values indicate closer allocation fidelity. A full reference-by-comparison matrix is also available with plot_type = "heatmap"; for JSD, this matrix can mirror supplied off-diagonal entries because JSD is symmetric. KL entries remain directional.

Usage

plot_validation_distribution_pairwise(
  distribution_results,
  metric = c("jsd", "kl"),
  value = c("mean", "weighted_mean", "median"),
  comparisons = "adjusted_vs_benchmark",
  methods = NULL,
  method_col = "method",
  method_labels = NULL,
  plot_type = c("comparison", "heatmap"),
  sort = c("none", "ascending", "descending"),
  mirror_jsd = TRUE
)

plot_validate_flow_distribution_pairwise_heatmap(..., plot_type = "heatmap")

Arguments

distribution_results: A data frame, one validate_flow_distribution() result, or a named list of results.
metric: Divergence metric to plot: "jsd" or "kl".
value: Summary statistic to plot: "mean", "weighted_mean", or "median".
comparisons: Flow comparison(s) to plot. Defaults to "adjusted_vs_benchmark". Use "all" to include all comparison rows present in distribution_results; with plot_type = "heatmap" this produces the full pairwise matrix. When "raw_vs_benchmark" is included in comparison plots, it is shown as a single unadjusted raw MPD baseline row.
methods: Optional character vector of method identifiers or display labels to include. Default NULL includes all methods.
method_col: Column containing the method identifier. Default "method".
method_labels: Optional named character vector used to relabel methods.
plot_type: Plot type to return: "comparison" for a horizontal benchmark-comparison chart or "heatmap" for the full pairwise matrix.
sort: Sort order for the comparison chart. Use "none" to keep method order, "ascending" for smallest-to-largest divergence, or "descending" for largest-to-smallest divergence. Adjusted methods are sorted; the raw MPD baseline remains at the edge as a reference row. Default "none".
mirror_jsd: Logical. If TRUE, mirror JSD values to show a symmetric matrix. Default TRUE.

Value

A ggplot object.