Add a quantile-binned response summary layer

Adds the quantile layer: exposure is cut into quantile bins (see cut_exposure_quantile()) and, within each bin, the response is summarised with a point estimate and confidence interval.

Usage

er_plot_add_quantiles(
  object,
  style = NULL,
  keep_strata = NULL,
  conf_level = 0.95,
  n_bins = 4,
  ties = "upward",
  quantile_type = 7,
  labeller = NULL,
  ...
)

Arguments

object: Partially constructed plot, an er_plot object.
style: Style used to draw the quantile summary layer. Can either be a string corresponding to one of the registered style labels (e.g., "errorbar", the default), or a builder function used to compute the relevant plot object (see "Styles" below).
keep_strata: Logical; whether this layer should use stratification. Defaults to TRUE when a stratification variable has been specified, and FALSE otherwise.
conf_level: Confidence level for the interval. Defaults to 0.95.
n_bins: Number of exposure bins (not counting placebo). Defaults to 4.
ties, quantile_type, labeller: Passed straight through to cut_exposure_quantile() to control how the exposure variable is split into bins – see its documentation for what each controls.
...: Additional named arguments forwarded to the style builder function when the plot is built.

Value

The input object, with the quantile layer added.

Details

The type of confidence interval shown depends on the response_type set in er_plot():

"binary": Clopper-Pearson interval (see ci_clopper_pearson())
"continuous": Student t-interval (see ci_t())
"count": exact Poisson interval (see ci_poisson())

Note that count responses are not automatically detected as such: they default to "continuous" and are summarised the same way as any other continuous response unless response_type = "count" is declared explicitly in er_plot().

n_bins/ties/quantile_type/labeller are local to this layer – they aren't shared with er_plot_add_groups(), even when that layer groups by the same exposure variable. er_plot_build() warns (doesn't error) if the two disagree in that specific case; pass matching values to both calls to avoid the warning, or ignore it if the difference is intentional.

Styles

The following pre-defined styles are available for this layer. Please see the documentation for the corresponding builder function to see what customisation options are available:

Label	Builder	Description
`"errorbar"`	`er_style_quantile_errorbar()`	Point + error bar per bin (the default).
`"errorbar_vlines"`	`er_style_quantile_errorbar_vlines()`	`"errorbar"` plus a labelled vline at every bin boundary.
`"pointrange"`	`er_style_quantile_pointrange()`	Point + range per bin, via `ggplot2::geom_pointrange()`.
`"pointrange_vlines"`	`er_style_quantile_pointrange_vlines()`	`"pointrange"` plus a labelled vline at every bin boundary.

See er_style() for details on how style builder functions are defined for the exposure-response mini-grammar, should a custom style be required.

Examples

if (requireNamespace("erglm", quietly = TRUE)) {
library(erglm)
mod <- erglm_model(ae1 ~ aucss, erglm_data, family = binomial())
erglm_data |>
  er_plot(aucss, ae1) |>
  er_plot_add_model(mod) |>
  er_plot_add_quantiles() |>
  plot()

# continuous response: bin means/t-intervals instead of rates/
# Clopper-Pearson intervals, auto-detected from the response column
mod3 <- erglm_model(biomarker_change ~ aucss, erglm_data, family = gaussian())
erglm_data |>
  er_plot(aucss, biomarker_change) |>
  er_plot_add_model(mod3) |>
  er_plot_add_quantiles() |>
  plot()

# count response: declare response_type = "count" explicitly for an
# exact Poisson interval instead of the t-interval approximation used
# by the auto-detected ("continuous") default
mod4 <- erglm_model(ae_count ~ aucss, erglm_data, family = poisson())
erglm_data |>
  er_plot(aucss, ae_count, response_type = "count") |>
  er_plot_add_model(mod4) |>
  er_plot_add_quantiles() |>
  plot()

# a pointrange instead of the default errorbar
erglm_data |>
  er_plot(aucss, ae1) |>
  er_plot_add_model(mod) |>
  er_plot_add_quantiles(style = er_style_quantile_pointrange) |>
  plot()

# the default errorbar, with dotted lines marking the quantile-bin
# boundaries
erglm_data |>
  er_plot(aucss, ae1) |>
  er_plot_add_model(mod) |>
  er_plot_add_quantiles(style = er_style_quantile_errorbar_vlines) |>
  plot()

# plug in a fully custom builder; see `?er_style`
build_quantile_crossbar <- function(data, config, stratify, exposure,
                                     response, strata, theme, ...) {
  ggplot2::geom_crossbar(
    data = config$summary,
    mapping = ggplot2::aes(x = x_mid, y = y_mid, ymin = ci_lower, ymax = ci_upper),
    inherit.aes = FALSE
  )
}
erglm_data |>
  er_plot(aucss, ae1) |>
  er_plot_add_model(mod) |>
  er_plot_add_quantiles(style = build_quantile_crossbar) |>
  plot()
}