Plot predicted distributional-parameter surfaces — plot_parameter

plot_parameter_surface() is a small ggplot2 consumer for long tables returned by predict_parameters(). It does not fit a model, build a grid, compute predictions, compute confidence intervals, or choose an estimand. Build an explicit grid with prediction_grid() or another data-frame workflow first, then pass the resulting prediction table to this helper.

Usage

plot_parameter_surface(
  data,
  x,
  colour = NULL,
  group = NULL,
  facet = "dpar",
  dpar = NULL,
  type = NULL,
  line = TRUE,
  point = TRUE,
  interval = TRUE,
  ...
)

Arguments

data: A data frame returned by predict_parameters(), or a compatible long table with columns dpar, type, estimate, conf.status, and interval_source. If conf.low and conf.high are present, both must be numeric.
x: Character scalar naming the column to draw on the x-axis.
colour: Optional character scalar naming a column to map to colour.
group: Optional character scalar naming a column to group lines. If NULL, lines are grouped by dpar, colour, and facet columns when present.
facet: Optional character scalar naming a column to facet by. Use NULL to suppress faceting. The default facets by dpar.
dpar: Optional character vector of distributional parameters to keep.
type: Optional character vector of prediction scales to keep, such as "response" or "link".
line: Logical; draw lines through the estimates.
point: Logical; draw points at the estimates.
interval: Logical; draw finite conf.low/conf.high intervals when those columns are present and conf.status plus interval_source indicate that an interval was actually computed.
...: Reserved for future options.

Value

A ggplot object.

Details

The helper plots estimate against one supplied column. It expects the interval provenance columns created by predict_parameters(). When finite conf.low and conf.high columns are present and the provenance columns describe a real interval, it draws confidence bands for continuous x-values and interval bars for discrete x-values. Rows without finite supported bounds remain visible as point or line estimates only. When the filtered table contains a single distributional parameter, the y-axis label names that parameter and, when unique, the prediction scale.

Examples

x <- seq(-1, 1.5, length.out = 8)
pred <- rbind(
  data.frame(
    dpar = "mu",
    type = "response",
    estimate = 1 + 0.5 * x,
    conf.low = 0.85 + 0.5 * x,
    conf.high = 1.15 + 0.5 * x,
    conf.status = "wald",
    interval_source = "wald",
    x = x
  ),
  data.frame(
    dpar = "sigma",
    type = "response",
    estimate = 0.55 + 0.08 * x,
    conf.low = 0.47 + 0.08 * x,
    conf.high = 0.63 + 0.08 * x,
    conf.status = "wald",
    interval_source = "wald",
    x = x
  )
)
if (requireNamespace("ggplot2", quietly = TRUE)) {
  plot_parameter_surface(pred, x = "x", point = FALSE) +
    ggplot2::labs(
      title = "Predicted parameter surfaces",
      subtitle = "Ribbons are Wald intervals from the supplied table"
    ) +
    ggplot2::theme_minimal(base_size = 11)
}