Plot validation flow-difference distributions as violins

Builds violin plots from validate_flow_residuals() data. Differences are aligned with the scatterplot convention used by plot_validation_scatter(): positive values mean the second named series is larger than the first named series. The default style uses translucent violins, jittered OD-pair points, and sample-size labels above each method.

Usage

plot_validation_residuals(
  residuals,
  residual = c("signed", "absolute", "percent"),
  comparisons = "adjusted_vs_benchmark",
  methods = NULL,
  method_col = "method",
  method_labels = NULL,
  palette = NULL,
  show_points = TRUE,
  show_counts = TRUE,
  point_alpha = 0.25,
  point_size = 0.6,
  jitter_width = 0.12,
  violin_alpha = 0.5,
  max_points = 5000,
  y_transform = c("pseudo_log", "identity")
)

plot_validate_flow_residual_violin(...)

Arguments

residuals

A data frame, one validate_flow_residuals() result, or a named list of validate_flow_residuals() results.

residual

Difference scale: "signed", "absolute", or "percent".

comparisons

Comparisons to plot. Defaults to "adjusted_vs_benchmark". Use a character vector to compare multiple flow-pair definitions. When "raw_vs_benchmark" is included, it is shown once as the unadjusted raw MPD baseline.

methods

Optional character vector of method identifiers or display labels to include, giving users control over which adjustment methods are compared. Default NULL includes all methods.

method_col

Column containing the method identifier. Default "method".

method_labels

Optional named character vector used to relabel methods.

palette

Optional character vector of colours. Defaults to a bright colour-blind-aware categorical palette inspired by the shared validation visual style.

show_points

Logical; show jittered OD-pair values over each violin. Default TRUE.

show_counts

Logical; show the number of plotted OD pairs above each violin. Default TRUE.

point_alpha

Point opacity. Default 0.25.

point_size

Point size. Default 0.6.

jitter_width

Horizontal jitter width for OD-pair points. Default 0.12.

violin_alpha

Violin fill opacity. Default 0.5.

max_points

Maximum number of OD-pair points to draw per method-comparison group. The violin density and count labels still use all rows. Use Inf to draw every point. Default 5000.

y_transform

Y-axis transformation. "pseudo_log" gives a log-like display that can still show zero and negative signed residuals. Use "identity" for the raw residual scale. Default "pseudo_log".

Value

A ggplot object.