Add Residual Lines to a Plot — gf

Draws residual lines from observed points to the values a fitted model predicts for them. Each residual runs along whichever axis the plot puts the model's outcome on, so a model of the variable drawn on x is measured across x rather than down y.

Usage

gf_resid(
  object = NULL,
  gformula = NULL,
  data = NULL,
  ...,
  model,
  linewidth = 0.2,
  xlab,
  ylab,
  title,
  subtitle,
  caption,
  geom = coursekata::GeomResid,
  stat = coursekata::StatResid,
  position = "identity",
  show.legend = NA,
  show.help = NULL,
  inherit = TRUE,
  environment = parent.frame()
)

Arguments

object: A ggformula plot object, typically created with gf_point().
gformula: Not used. gf_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, alpha or linetype, (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 =.
linewidth: The width of the residual lines. Default is 0.2. Must be named.
xlab, ylab, title, subtitle, caption: Labels for the plot.
geom, stat, position: Not set by the caller. A residual is drawn by its own geom and stat, and moved by the position the observations are already drawn with, so that a segment 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. The axes and the prediction are stated outright; everything else – a mapped color, for instance – is inherited from the plot.
environment: The environment mappings are resolved in.

Value

A ggplot object with residual lines added.

Examples

# 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_resid(flipper_model)


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

# 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_resid(empty_model, color = "blue")


# 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_resid(gentoo_model, color = "firebrick")


# 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_resid(sample_flipper_model, color = "firebrick")