gf_square_resid: Add Squared Residual Visualization to a Plot

In coursekata: Packages and Functions for 'CourseKata' Courses

Add Squared Residual Visualization to a Plot

Description

gf_squaresid() is a fully supported alias of gf_square_resid(). The name honors Tyler Haslam, the Utah high school teacher whose efforts shaped the residual and squared-residual visualizations and who requested this function by that name.

Usage

gf_square_resid(
  object = NULL,
  gformula = NULL,
  data = NULL,
  ...,
  model,
  aspect = 4/6,
  alpha = 0.1,
  xlab,
  ylab,
  title,
  subtitle,
  caption,
  geom = coursekata::GeomSquareResid,
  stat = coursekata::StatResid,
  position = "identity",
  show.legend = NA,
  show.help = NULL,
  inherit = FALSE,
  environment = parent.frame()
)

gf_squaresid(
  object = NULL,
  gformula = NULL,
  data = NULL,
  ...,
  model,
  aspect = 4/6,
  alpha = 0.1,
  xlab,
  ylab,
  title,
  subtitle,
  caption,
  geom = coursekata::GeomSquareResid,
  stat = coursekata::StatResid,
  position = "identity",
  show.legend = NA,
  show.help = NULL,
  inherit = FALSE,
  environment = parent.frame()
)

Arguments

object	A ggformula plot object, typically created with gf_point().
gformula	Not used. gf_square_resid() measures a model, not an aesthetic formula; a model given positionally lands here and is moved to model.
data	Not used. The residuals are measured over the data the plot was built from. Anything supplied here is left for ggformula and ggplot2 to answer, exactly as it is for any other gf_ layer.
...	Additional arguments. Typically these are (a) ggplot2 aesthetics to be set with attribute = value, such as color or fill, (b) ggplot2 aesthetics to be mapped with attribute = ~ expression, or (c) attributes of the layer as a whole.
model	A model already fit by lm() or aov(). The plot supplies the observations; the model supplies what it predicted for each of them. May be given positionally or as ⁠model =⁠.
aspect	The square's aspect ratio. Default is 4/6. Must be named.
alpha	The transparency of the square's fill. Default is 0.1. Must be named.
xlab, ylab, title, subtitle, caption	Labels for the plot.
geom, stat, position	Not set by the caller. A squared residual is drawn by its own geom and stat, and moved by the position the observations are already drawn with, so that a square stays on the point it belongs to.
show.legend	Whether this layer contributes to the legend.
show.help	Print the layer's own help instead of drawing.
inherit	Whether the layer inherits the plot's aesthetics. FALSE, where gf_resid() is TRUE: a square is a filled region drawn in the geom's own colors, so inheriting a plot's mapped color outlines every square in the color of the group it measures instead of leaving one neutral area per observation. The axes and the prediction are stated outright, so nothing the square needs is lost by not inheriting. Set it to TRUE to take the outline anyway.
environment	The environment mappings are resolved in.

Details

Draws squared residual polygons between observed points and the values a fitted model predicts for them, so squared error is an area you can see. The square is built on the residual itself and turns with it: a model of the variable the plot puts on x squares the horizontal distance. Its side is scaled to stay square on the page rather than in data units.

Value

A ggplot object with squared residual polygons added.

Examples

# squared residuals can be drawn on a full data set, but with hundreds of
# points the plot gets hard to read
flipper_model <- lm(body_mass_kg ~ flipper_length_m, data = penguins)
gf_point(body_mass_kg ~ flipper_length_m, data = penguins) %>%
  gf_model(flipper_model) %>%
  gf_square_resid(flipper_model)

# a small sample makes the squared residuals much easier to see
set.seed(1)
penguins_20 <- sample(penguins, 20)

# squared residuals from the empty model (in blue)
empty_model <- lm(body_mass_kg ~ NULL, data = penguins_20)
gf_point(body_mass_kg ~ flipper_length_m, data = penguins_20) %>%
  gf_model(empty_model) %>%
  gf_square_resid(empty_model, color = "blue")

# squared residuals from a two-group model on a jitter plot (in firebrick)
gentoo_model <- lm(body_mass_kg ~ gentoo, data = penguins_20)
gf_jitter(body_mass_kg ~ gentoo, data = penguins_20, width = .1) %>%
  gf_model(gentoo_model) %>%
  gf_square_resid(gentoo_model, color = "firebrick")

# squared residuals from a regression model (in firebrick)
sample_flipper_model <- lm(body_mass_kg ~ flipper_length_m, data = penguins_20)
gf_point(body_mass_kg ~ flipper_length_m, data = penguins_20) %>%
  gf_model(sample_flipper_model) %>%
  gf_square_resid(sample_flipper_model, color = "firebrick")

coursekata documentation built on Sept. 22, 2026, 1:08 a.m.