Countable-Rectangle Histogram

Usage

gf_squareplot(
  object = NULL,
  gformula = NULL,
  data = NULL,
  ...,
  binwidth = NULL,
  bins = NULL,
  center = NULL,
  boundary = NULL,
  closed = NULL,
  breaks = NULL,
  bars = "none",
  na.rm = TRUE,
  xlab,
  ylab,
  title,
  subtitle,
  caption,
  geom = coursekata::GeomSquareplot,
  stat = coursekata::StatSquareplot,
  position = "identity",
  show.legend = NA,
  show.help = NULL,
  inherit = TRUE,
  environment = parent.frame()
)

Arguments

object: A ggplot object, a data frame, or a formula. When a plot, the squares are added to it.
gformula: A formula with shape ~x, optionally faceted as ~ x | z.
data: A data frame holding the variable in gformula.
...: Aesthetics such as fill or alpha, either set to a value or mapped with a one-sided formula (fill = ~group). color sets the color of the separators between squares and may be mapped; bar_color sets the bar's own color, and bar_linewidth its width. Also takes ggplot2::stat_bin()'s pad, which adds an empty bin on either end of the range.
binwidth: Width of the bins, for a continuous x. Chosen from the data when unset: 1 for whole-number data spanning 50 or less, so every value gets a column of its own, and a thirtieth of the range otherwise. Has no effect on a discrete x, which is counted instead.
bins: How many bins to divide the range into, used when binwidth is unset.
center, boundary: The center of one bin, or an edge of one. Either places the whole grid; give one or the other, not both.
closed: Which end of a bin holds a value that lands exactly on it, "right" or "left". For whole-number data, boundary = 0.5 puts every value in the column it is labeled with, whichever end is closed.
breaks: The bin edges themselves, which need not be evenly spaced.
bars: Display style: "none" (squares only), "outline" (squares inside the bar they add up to) or "solid" (that bar alone).
na.rm: Must be TRUE. A missing value has no square to draw.
xlab, ylab, title, subtitle, caption: Labels.
geom, stat, position: The layer's geom, stat and position.
show.legend: Whether to show a legend, or NA to decide per aesthetic.
show.help: Print the function's own help instead of drawing.
inherit: Whether to inherit the plot's aesthetics.
environment: Where to evaluate the formula.

Value

A ggplot object.

Details

Creates histograms where each observation is drawn as its own square, stacked into columns, so a bin's height can be counted as well as read off the axis: n = 47 is 47 squares. Designed for teaching statistical concepts like sampling distributions and hypothesis testing.

Sensible defaults are chosen based on the data:

For integer-valued data with a small range, the binwidth defaults to 1 so that each integer gets its own column. Everything else about the bins is stat_bin()'s: bins, center, boundary, closed, breaks and pad put a squareplot's columns exactly where a gf_histogram()'s bars would be.
A factor keeps its levels, so a level nobody landed in still holds its place on the axis. Knowing a value never occurred is the point.
A discrete x – a factor, character or logical vector – is counted, one column per level, positioned the way gf_bar() positions its bars. The binning arguments (bins, binwidth, center, boundary, closed, breaks, pad) belong to a continuous x; supplying one alongside a discrete x warns rather than changing the plot.
The white separator between two squares is capped at a quarter of a square's smaller side, so as a bin fills and its squares shrink the separator thins with them and the squares stay countable.
The y axis is a count, so its breaks are whole numbers.

The bins are a histogram's bins: binwidth, bins, center, boundary, closed and breaks mean what they mean on ggformula::gf_histogram(), and the same arguments give the same bin edges and the same counts, so squares laid over bars land inside them.

Everything that is not the squares is a layer or a scale: %>% show_mean(), %>% show_dgp(), %>% gf_lims(x = ), %>% gf_refine(ggplot2::expand_limits(y = )). Each of these was an argument here once, and passing the old name is refused with the replacement named, so a call written against the old signature says what to write rather than drawing a plot with the mark missing.

Examples

# each observation is a countable square
gf_squareplot(~Thumb, data = Fingers)


# `bars` controls the display: "none" (default), "outline", or "solid"
gf_squareplot(~Thumb, data = Fingers, bars = "outline")


# the bins are a histogram's bins, so squares laid over bars land inside them --
# name the grid on both layers, because a layer never reads its neighbor's
gf_histogram(~Thumb, data = Fingers, bins = 8) %>% gf_squareplot(bins = 8)


# customize fill color, binwidth, and axis limits
gf_squareplot(~Thumb, data = Fingers, fill = "coral", binwidth = 5) %>%
  gf_lims(x = c(30, 90))


# integer data with a small range gets one column per integer
int_data <- data.frame(rolls = sample(1:6, 30, replace = TRUE))
gf_squareplot(~rolls, data = int_data)


# the plot is a real ggformula layer, so it facets and takes mapped aesthetics
gf_squareplot(~ Thumb | Sex, data = Fingers)

gf_squareplot(~Thumb, data = Fingers, fill = ~Sex)


# with 2000 observations the squares shrink, and their separators thin to fit
set.seed(24)
large_data <- data.frame(x = rnorm(2000, mean = 50, sd = 10))
gf_squareplot(~x, data = large_data)


# show a dashed line at the sample mean
gf_squareplot(~Thumb, data = Fingers) %>% show_mean()


# frame a sampling distribution with its data generating process: with only
# 10 shuffles, the mean of the distribution can land far from the null.
# The limits come before the overlays: show_dgp() reads the top of the count
# axis to decide how much room its band needs.
shuffled_b1 <- function(n) {
  data.frame(b1 = replicate(n, {
    shuffled_tip <- base::sample(TipExperiment$Tip)
    b1(lm(shuffled_tip ~ Condition, data = TipExperiment))
  }))
}

set.seed(42)
gf_squareplot(~b1, data = shuffled_b1(10), binwidth = 2) %>%
  gf_lims(x = c(-30, 30)) %>%
  gf_refine(ggplot2::expand_limits(y = 10)) %>%
  show_mean() %>%
  show_dgp()


# a factor keeps every level, including the ones nothing landed in
ratings <- data.frame(rating = factor(
  base::sample(1:5, 20, replace = TRUE, prob = c(1, 2, 4, 2, 1)),
  levels = 1:5
))
gf_squareplot(~rating, data = ratings)

Usage

Arguments

Value

Details

See also

Examples