Skip to contents

Frame a Sampling Distribution With Its Data Generating Process

Source: R/show_overlays.R
show_dgp.Rd

[Experimental]

Usage

show_dgp(plot, color = "#003d70", null_color = "#E60000", size = 4)

Arguments

plot

A plot of one distribution of estimates.

color

Color of the axes, equations and titles. Default "#003d70".

null_color

Color of the null hypothesis marker. Default "#E60000".

size

Size of the null hypothesis marker. Default 4.

Value

The plot, with tagged annotation layers added and its count axis raised to hold them.

Details

Frames a distribution of estimates with the process that generated them: the population model on a top axis labeled "Population Parameter (DGP)", the sample estimate below the plot, and a marker at the null hypothesis (\(\beta_1 = 0\)) on both – drawn only when zero is on the axis.

The band is drawn inside the panel, and the count axis is raised to hold it. It has to be: countable squares size the separator between them from the fraction of the panel they occupy, so a band hanging outside the panel would leave every square a different shape. A plot whose count axis is pinned with scale_y_continuous(limits = ) or coord_cartesian(ylim = ) is refused, because there is no room to raise without discarding the caller's chosen range; set a minimum height with expand_limits(y = ) instead. A faceted plot needs a shared count axis (the default): scales = "free_y" is refused, because the band's height is one number for every panel. A transformed count axis (scale_y_sqrt(), scale_y_log10()) is refused too: the sample estimate band is drawn in the margin below the panel, where a transformed scale has no value. show_mean() is unaffected by either restriction.

See also

The sampling distributions guide draws this figure inside a full shuffle-and-estimate workflow: https://coursekata.github.io/coursekata-r/articles/sampling-distributions.html

Examples

# with only ten shuffles the mean of the distribution can land well away
# from the null hypothesis marked on the top axis
set.seed(42)
shuffled <- data.frame(b1 = replicate(10, {
  b1(lm(base::sample(TipExperiment$Tip) ~ Condition, data = TipExperiment))
}))

# expand_limits() sets the count axis so two runs can be compared side by
# side; show_dgp() raises it further to make room for the population band
gf_histogram(~b1, data = shuffled, binwidth = 2) %>%
  gf_refine(ggplot2::expand_limits(y = 10)) %>%
  show_mean() %>%
  show_dgp()