er_vpc: The exposure-response VPC mini-language

In erplots: Model-Agnostic Exposure-Response Plots

The exposure-response VPC mini-language

Description

Create an er_vpc specification for a visual predictive check. Build the plot by adding an observed layer and a simulated layer, and render with plot()/print() or er_vpc_build().

Usage

er_vpc(
  data,
  exposure,
  response,
  stratify_by = NULL,
  response_type = "auto",
  plot_by = NULL,
  n_bins = 4,
  ties = "upward",
  quantile_type = 7,
  labeller = NULL,
  conf_level = 0.95,
  probs = c(0.1, 0.5, 0.9),
  seed = NULL
)

Arguments

data	Data frame or tibble containing the observed data.
exposure	Exposure variable (one variable, unquoted).
response	Response variable (one variable, unquoted).
stratify_by	Optional variable (unquoted) splitting the VPC into one facet panel per level, via ggplot2::facet_wrap(), used as-is. Must be discrete – a numeric column errors; bin it yourself first with cut_quantile()/cut_exposure_quantile() and pass the resulting factor, for full control over bin count/tie-breaking/labels. Must resolve to a different variable than plot_by. Defaults to NULL (no faceting, a single panel, matching prior behaviour).
response_type	One of "auto" (the default), "binary", "continuous", or "count".
plot_by	Variable (unquoted) plotted on the x-axis and used to bin/group the observed vs. simulated comparison. Defaults to exposure. A numeric variable is split into n_bins quantile bins (placebo, i.e. 0, kept in its own bin when plot_by is the exposure variable itself); a categorical variable is used as-is, with no binning.
n_bins	Number of quantile bins, when plot_by is numeric. Defaults to 4.
ties, quantile_type, labeller	Control how a numeric plot_by is split into quantile bins – passed straight through to cut_exposure_quantile(), see its documentation for what each controls. Set here, on er_vpc() itself, rather than on er_vpc_add_observed()/er_vpc_add_simulated(), because the two layers must always agree on how plot_by is binned – er_vpc_add_simulated() reuses these exact settings (via cut_exposure_quantile()'s attributes on the observed layer's own binned column) rather than re-resolving them, so both sides always stay in sync.
conf_level	Confidence level for both the observed- and simulated-side intervals. Must be strictly between 0 and 1. Defaults to 0.95.
probs	Percentiles to compute for a percentile-based builder (e.g. er_style_vpc_observed_quantile_line()/er_style_vpc_simulated_quantile_ribbon()/ er_style_vpc_observed_quantile_errorbar()/er_style_vpc_simulated_quantile_errorbar(); ignored by the default adaptive mean/errorbar pair). Only computed for a continuous/count response. Defaults to c(0.1, 0.5, 0.9).
seed	Optional single number seeding the observed layer's random tie-break when ties is "split-even" (ignored otherwise). NULL (the default) draws from the ambient RNG stream. The simulated layer's own "split-even" tie-break is instead seeded by er_vpc_add_simulated()'s own seed argument – the two are independent random draws over different data (the observed rows vs. the, typically larger, simulated replicate pool), so each is seeded by the call that actually performs it.

Details

er_vpc_add_observed() bins the observed data and computes its response summary; er_vpc_add_simulated() must be added afterwards, since it reuses the observed layer's own binning decision so both sides share identical bin boundaries. Both layers are singletons (a second call replaces the previous one).

er_vpc()'s own stratification (stratify_by) is real, but simpler than er_plot()'s: a facet-only split via ggplot2::facet_wrap(), with no colour/facet precedence rule to reconcile (see stratify_by below). It's orthogonal to plot_by – see er_vpc_add_observed() for plot_by, the variable plotted on the x-axis and used to bin/group the comparison. Whether plot_by is "continuous" (numeric, quantile-binned) or "discrete" (used as-is) is auto-detected from the column's type and stored on object$group$type, mirroring how object$response$type records the response's type.

Value

An (empty) plot object of class er_vpc.

See Also

er_vpc_add_observed(), er_vpc_add_simulated(), er_vpc_build(), er_model_interface

Examples

if (requireNamespace("erglm", quietly = TRUE)) {
library(erglm)
mod <- erglm_model(ae2 ~ aucss + sex, erglm_data, family = binomial())

erglm_data |>
  er_vpc(aucss, ae2, plot_by = aucss) |>
  er_vpc_add_observed() |>
  er_vpc_add_simulated(model = mod, seed = 9984) |>
  plot()
}

erplots documentation built on Oct. 4, 2026, 5:06 p.m.