gf_sd_ruler: Add a Standard Deviation Ruler to a Plot

In coursekata: Packages and Functions for 'CourseKata' Courses

Add a Standard Deviation Ruler to a Plot

Description

Usage

gf_sd_ruler(
  object = NULL,
  gformula = NULL,
  data = NULL,
  ...,
  where = "middle",
  na.rm = FALSE,
  xlab,
  ylab,
  title,
  subtitle,
  caption,
  geom = "segment",
  stat = coursekata::StatSdRuler,
  position = "identity",
  show.legend = NA,
  show.help = NULL,
  inherit = TRUE,
  environment = parent.frame()
)

Arguments

object	The plot or data to add the ruler to; typically a plot piped in from gf_point(), gf_jitter(), or gf_histogram().
gformula	A formula naming the outcome and, optionally, the x variable: y ~ x. Defaults to the plot's own mapping when the plot already names one.
data	Dataset. Defaults to the plot's data.
...	Additional arguments accepted by ggplot2::geom_segment(), including fixed color and linewidth values. Defaults come from the segment geom, as they do for stat_sd_ruler().
where	For a vertical ruler, where on the x-axis to place it: "middle" (midpoint of x range), "mean", or "median". Ignored for a horizontal ruler, which always starts at the mean.
na.rm	Should missing values be silently removed?
xlab, ylab, title, subtitle, caption	Axis and plot labels; see ggformula::gf_point().
geom, stat, position	Layer components; see ggformula::gf_point().
show.legend	Should this layer be included in the legends?
show.help	If TRUE, display some minimal help.
inherit	A logical indicating whether default attributes are inherited from a parent plot.
environment	An environment in which to evaluate the formula.

Details

Adds a segment showing one standard deviation of the outcome, anchored at its mean. The orientation depends on where the outcome variable lives: on a scatter or jitter plot (outcome on the y-axis) the ruler is a vertical segment placed at a chosen x position; on a histogram (outcome on the x-axis, no y aesthetic) it is a horizontal segment running from the mean to mean + SD along the baseline. The orientation is detected automatically from the plot's axis mappings.

Both the outcome and, where relevant, the placement are measured in the space the panel is drawn in: a faceted plot measures each panel's own subset, and a transformed axis or a computed mapping such as ~log(Thumb) is measured in the transformed or computed values, not the raw column.

gf_sd_ruler() draws one ruler per panel, so an aesthetic mapped on the call – gf_sd_ruler(color = ~Sex) – is refused; split the plot instead with y ~ x | group to get one ruler per group.

Value

A ggplot object with the SD ruler segment added.

See Also

stat_sd_ruler() provides the ggplot2 interface. The model visualization guide shows the ruler alongside residuals and compares groups with different spread: https://coursekata.github.io/coursekata-r/articles/model-visualization.html

Examples

# the ruler runs from the mean (the empty model) up by one standard
# deviation -- it looks like a residual because SD is a typical residual
gf_point(Thumb ~ Height, data = Fingers, alpha = .4) %>%
  gf_model(lm(Thumb ~ NULL, data = Fingers)) %>%
  gf_sd_ruler()

# `where` controls placement along the x-axis
gf_point(Thumb ~ Height, data = Fingers, alpha = .4) %>%
  gf_sd_ruler(where = "mean")

# categorical x works the same way
gf_jitter(Thumb ~ Sex, data = Fingers, width = .1, alpha = .4) %>%
  gf_sd_ruler(where = "median")

# on a histogram the outcome is on the x-axis, so the ruler is horizontal
# and runs along the baseline from the mean to one SD above it
gf_histogram(~Thumb, data = Fingers, binwidth = 5) %>%
  gf_sd_ruler(linewidth = 2)

# name the variable explicitly when the plot does not make it obvious
gf_point(Thumb ~ Height, data = Fingers, alpha = .4) %>%
  gf_sd_ruler(Thumb ~ Height)

# one ruler per panel
gf_sd_ruler(Thumb ~ Height | Sex, data = Fingers)

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