gf_square_reduce: Add Squared Reduction Visualization to a Plot

In coursekata: Packages and Functions for 'CourseKata' Courses

Add Squared Reduction Visualization to a Plot

Description

gf_squareduce() is a fully supported alias of gf_square_reduce(), named the way the classroom that asked for it says it.

Usage

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

gf_squareduce(
  object = NULL,
  gformula = NULL,
  data = NULL,
  ...,
  model,
  aspect = 4/6,
  alpha = 0.1,
  xlab,
  ylab,
  title,
  subtitle,
  caption,
  geom = coursekata::GeomSquareResid,
  stat = coursekata::StatReduce,
  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_reduce() measures a model, not an aesthetic formula; a model given positionally lands here and is moved to model.
data	Not used. The reductions 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' position on the other axis; the model supplies what it predicted for each of them. May be given positionally or as ⁠model =⁠. A fit without an intercept, or one fit with weights or an offset, is refused. For an unweighted least-squares fit with an intercept, the sum of squared total deviations equals the sum of squared residuals plus the sum of squared reductions. That identity need not hold without an intercept. Weighted least squares instead guarantees a weighted identity based on a weighted mean, which the plot's plain areas do not represent. gf_resid() can measure either fit because it does not rely on the decomposition.
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 reduction is drawn by its own geom and stat, with a jitter that holds the outcome axis still so its squares start at the grand mean without floating off it, while jittering the other axis exactly the points layer's own jitter did.
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_reduce() is TRUE – see gf_square_resid() for why: a square is a filled region drawn in the geom's own colors, and inheriting a plot's mapped color would outline every square in the color of the group it measures instead of leaving one neutral area per observation. Set it to TRUE to take the outline anyway.
environment	The environment mappings are resolved in.

Details

Draws squared reduction polygons between the grand mean and the values a fitted model predicts. Each polygon shows one observation's squared reduction; together, their areas represent the model sum of squares. The square is built on the reduction 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.

Use the same aspect for all three square layers. Across observations, the reduction areas and residual areas sum to the total areas. The equality is between those sums, not between the three squares for any one observation. gf_square_resid(), gf_square_reduce(), and any squared total drawn beside them must use the same aspect for their areas to share a scale.

Value

A ggplot object with squared reduction polygons added.

Examples

set.seed(1)
penguins_20 <- sample(penguins, 20)

# two collections of squares in one sample-level decomposition: squared
# residuals (firebrick) and squared reductions (blue), drawn at one aspect
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(flipper_model) %>%
  gf_square_resid(flipper_model, color = "firebrick") %>%
  gf_square_reduce(flipper_model, color = "blue")

# and for a two-group model on a jitter plot
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_reduce(gentoo_model, color = "blue")

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