plot_heiss – ordbetareg

Heiss Plot for Predicted Proportions of Bounded Scale Components

Description

The Heiss plot, developed by the statistician Andrew Heiss, is a plot of the predicted proportions of components on a bounded scale that are grouped by the unique levels of a grouping variable or factor (such as a random effect) in the model. The plot excels at showing how the scale components–that is, the bottom, middle continuous, and top ends of the scale–vary with a discrete variable while also capturing posterior uncertainty. This plot was the winner of the 2023 ordbetareg Visualization Prize.

Usage

plot_heiss(
  object,
  grouping_fac = NULL,
  recode_group_labels = NULL,
  ndraws = NULL,
  show_category_perc_labels = TRUE,
  category_label_font_size = 3,
  category_label_accuracy = 1,
  strip_text_font = element_text(face = "plain", size = 9),
  plot_title = "Predicted Proportions of Bounded Scale Components",
  plot_subtitle = paste0("By Unique Values of ", grouping_fac),
  plot_caption =
    "Plot shows predicted proportions of the components of a bounded scale, i.e. the predicted (expected) probability of the top value of the scale, the intermediate continuous values, and the bottom value of the scale. The predictions are subset for unique values of a grouping factor. The predictions are shown for multiple posterior draws to indicate uncertainty. Labels on components indicate posterior quantiles for the probability of that component for each level of the grouping variable.",
  plot_caption_width = 70,
  calc_func = mean,
  lb = 0.05,
  upb = 0.95,
  plot_font_size = 11,
  plot_font = "",
  y_axis_label = "Predicted Proportions",
  legend_name = "Scale Components",
  component_colors = c("#ef8737", "#bb292c", "#62205f"),
  component_labels = c("0", "(0-1)", "1"),
  ...
)

Arguments

`object`	A fitted `ordbetareg()` model object.
`grouping_fac`	A character string indicating the name of the discrete column in the data used for grouping predictions. Must be a valid column name that was passed to `ordbetareg()`.
`recode_group_labels`	Optional. A character vector of new labels for the grouping factor levels. Must match the number and order of unique levels/values in `grouping_fac`.
`ndraws`	Optional. The number of posterior draws to use for predictions. If `NULL`, all available draws are used.
`show_category_perc_labels`	Logical. Whether to display category percentage labels on the plot. Defaults to `TRUE`.
`category_label_font_size`	The `ggplot2` font size for the labels on the scale components (if `show_category_perc_labels` is `TRUE`). Defaults to 3.
`category_label_accuracy`	The accuracy, or amount of rounding, for component label ranges on the plot (if `show_category_perc_labels` is `TRUE`). Default is 1. See `scales::label_percent()` for more info on meaning of `accuracy` parameter.
`strip_text_font`	A `ggplot2::element_text` object defining the font style for facet strip text. Defaults to `element_text(face = “plain”, size = 9)`.
`plot_title`	Title of the plot. Defaults to "Predicted Proportions of Bounded Scale Components".
`plot_subtitle`	Subtitle of the plot. Defaults to a message indicating the grouping variable.
`plot_caption`	Caption text for the plot. Defaults to a detailed description of the plot contents.
`plot_caption_width`	Width (in characters) at which the caption is wrapped. Defaults to 60.
`calc_func`	A function used to calculate the central tendency of predictions. Defaults to `mean`.
`lb`	Lower bound for uncertainty intervals. Defaults to 0.05 (5th percentile).
`upb`	Upper bound for uncertainty intervals. Defaults to 0.95 (95th percentile).
`plot_font_size`	Base font size for the plot. Defaults to 11.
`plot_font`	Base font family for the plot. Defaults to an empty string (uses system default).
`y_axis_label`	Label for the y-axis. Defaults to "Predicted Proportions".
`legend_name`	Legend title. Defaults to "Scale Components".
`component_colors`	A character vector of colors for the plot components (bottom, continuous, top). Defaults to `c(“#ef8737”, “#bb292c”, “#62205f”)`.
`component_labels`	A character vector of labels for the scale/outcome components (bottom, continuous, top). Defaults to `c(“0”, “(0-1)”, “1”)`.
`…`	Additional arguments passed to posterior_epred_ordbeta()).

Details

For more details of the plot, see:

Heiss, Andrew and Ye, Meng. "Enforcing Boundaries: China’s Overseas NGO Law and Operational Constraints for Global Civil Society." Working Paper, 2023. https://stats.andrewheiss.com/compassionate-clam/notebook/manuscript.html.

Value

A ggplot2 object representing the predicted proportions of the components.

Examples

library(ordbetareg)

# Load a fitted model object and create a plot for
# distinct values of the factor education
#
# data('ord_fit_mean')
#
# plot_heiss(ord_fit_mean,ndraws=100)
#
# See introductory package vignette for more information on function options