plot_means: Barplot of means

In statuser: Statistical Tools Designed for End Users

Barplot of means

Description

Plots means, with confidence intervals, and (optionally) p-values for differences of means and interactions

Usage

plot_means(
  formula,
  data = NULL,
  cluster = NULL,
  tests = "auto",
  quiet = FALSE,
  order = NULL,
  legend.title = NULL,
  col = NULL,
  col.text = NULL,
  values.cex = 1,
  values.align = "top",
  values.round = 1,
  pvalue.cex = 0.9,
  pvalue.col = "gray50",
  ci.level = 95,
  buffer.top = "auto",
  ...
)

Arguments

formula	A formula, e.g., y ~ x1+x2, where x1 & x2 are grouping variables (e.g., condition indicators in a 2x2 experiment). The formula can include up to three grouping variables. The plot will show contiguous bars for x1, and sets of bars for x2 and x3
data	Optional data frame containing variables in the formula.
cluster	Optional clustering variable when there are repeated observations per cluster e.g., cluster="participant_ID". When provided, inference for reported tests is based on regressions with clustered standard errors (via lm2(..., clusters=...)).
tests	specifies which comparisons of means to report. Syntax involves putting column numbers in a character string, with a - to symbolize a comparison and a + symbolizing combination. For example tests="1-2" reports t-test comparing columns 1 and 2. tests="1-2,3-4" t-tests comparing columns 1 & 2 and another 3 & 4. To run an interaction use parentheses: tests="(4-3)-(2-1)" and can also be combined with simple tests. Main effects can be specified using '+', for example (1+2)-(3+4) compares all observations in the first two columns with all observations in the next two columns.
quiet	Logical. When TRUE, suppresses console messages from plot_means().
order	Controls the order of x1 groups (bar order and colors). Use -1 to reverse the default order (e.g., if plot shows 'male' first and 'female' second, order=-1 will flip that).
legend.title	Character string. Title for the legend. If NULL, no title is shown.
col	Color(s) for x1 bars. If NULL, colors are chosen automatically.
col.text	Color for confidence intervals and other non-bar annotations. If NULL, defaults to a dark gray.
values.cex	Numeric scalar controlling text size for mean value labels (and related annotations).
values.align	Where within the bars to put the mean value labels: "top", "middle", "bottom", or "none".
values.round	Non-negative integer. Number of decimal places for mean value labels.
pvalue.cex	Numeric scalar controlling p-value label size.
pvalue.col	Color for p-value brackets/labels.
ci.level	Confidence interval level for ciL/ciH in $means. Default is 95. You can also pass a proportion (e.g., 0.95).
buffer.top	Either "auto" (default) or a numeric value. Extra vertical headroom (as a fraction of the data y-range) added above the maximum y value to make room for annotations. When "auto", uses 0.35 when an interaction p-value is shown (scenario 2) and 0.25 otherwise.
...	Additional arguments passed to plot() (e.g., main, ylim, ylab).

Details

When tests="auto", the function reports a small default set of differences-of-means tests (when applicable) and, in 2x2 designs, an interaction test:

Differences in means

If cluster is NULL, these are Welch two-sample t-tests computed with t.test(..., var.equal=FALSE). If cluster is provided, these comparisons are computed from a regression using lm2() with clustered standard errors.

Interaction

The interaction is tested using a linear regression fit with lm2(), even when cluster is NULL; when cluster is provided, the interaction test uses clustered standard errors.

The regression-based tests use heteroskedasticity-robust inference (HC3) when cluster is NULL. HC3 is a common small-sample adjustment to White-type robust standard errors and is used to reduce sensitivity to heteroskedasticity. When cluster is provided, plot_means() instead uses clustered standard errors (robust to within-cluster correlation).

In the returned $means table, ciL and ciH are the lower and upper bounds of a ci.level% confidence interval for the mean (when available). The same confidence level is used for the confidence-interval whiskers drawn in the figure.

Value

A minimal list returned invisibly with two elements:

means

A data frame of means (and, when available, confidence intervals) aligned to the plotting grid.

tests

A data frame of comparisons used for p-value annotation (or NULL if not applicable).

Examples

df <- data.frame(y = rnorm(100), group = rep(c("A", "B"), 50))
plot_means(y ~ group, data = df)

df2 <- data.frame(
  y = rnorm(200),
  x1 = rep(c("A", "B"), 100),
  x2 = rep(c("X", "Y"), each = 100)
)
plot_means(y ~ x1 + x2, data = df2)

df3 <- data.frame(
  y = rnorm(600),
  x1 = rep(c("control", "treatment"), times = 300),
  x2 = rep(rep(c("low", "high"), each = 150), times = 2),
  x3 = rep(c("online", "lab"), each = 300)
)
plot_means(y ~ x1 + x2 + x3, data = df3)

statuser documentation built on April 25, 2026, 5:06 p.m.