% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_means.R
\name{plot_means}
\alias{plot_means}
\title{Barplot of means}
\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{
\item{formula}{A formula, e.g., \code{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}

\item{data}{Optional data frame containing variables in the formula.}

\item{cluster}{Optional clustering variable when there are repeated 
observations per cluster 
e.g., \code{cluster="participant_ID"}. 
When provided, inference for reported tests is based on regressions with
clustered standard errors (via \code{lm2(..., clusters=...)}).}

\item{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=\code{"(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.}

\item{quiet}{Logical. When \code{TRUE}, suppresses console messages from \code{plot_means()}.}

\item{order}{Controls the order of \code{x1} groups (bar order and colors).
Use \code{-1} to reverse the default order (e.g., if plot shows 'male' first and 'female' second, order=-1 will flip that).}

\item{legend.title}{Character string. Title for the legend. If \code{NULL},
no title is shown.}

\item{col}{Color(s) for \code{x1} bars. If \code{NULL}, colors are chosen
automatically.}

\item{col.text}{Color for confidence intervals and other non-bar annotations.
If \code{NULL}, defaults to a dark gray.}

\item{values.cex}{Numeric scalar controlling text size for mean value labels
(and related annotations).}

\item{values.align}{Where within the bars to put the mean value labels: \code{"top"}, \code{"middle"},
\code{"bottom"}, or \code{"none"}.}

\item{values.round}{Non-negative integer. Number of decimal places for mean
value labels.}

\item{pvalue.cex}{Numeric scalar controlling p-value label size.}

\item{pvalue.col}{Color for p-value brackets/labels.}

\item{ci.level}{Confidence interval level for \code{ciL}/\code{ciH} in \code{$means}.
Default is \code{95}. You can also pass a proportion (e.g., \code{0.95}).}

\item{buffer.top}{Either \code{"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 \code{"auto"}, uses 0.35
when an interaction p-value is shown (scenario 2) and 0.25 otherwise.}

\item{...}{Additional arguments passed to \code{plot()} (e.g., \code{main},
\code{ylim}, \code{ylab}).}
}
\value{
A minimal list returned invisibly with two elements:
\describe{
  \item{\code{means}}{A data frame of means (and, when available, confidence intervals)
    aligned to the plotting grid.}
  \item{\code{tests}}{A data frame of comparisons used for p-value
    annotation (or \code{NULL} if not applicable).}
}
}
\description{
Plots means, with confidence intervals, and (optionally) p-values for differences of means and interactions
}
\details{
When \code{tests="auto"}, the function reports a small default set of
differences-of-means tests (when applicable) and, in 2x2 designs, an
interaction test:
\describe{
  \item{Differences in means}{If \code{cluster} is \code{NULL}, these are Welch
    two-sample t-tests computed with \code{t.test(..., var.equal=FALSE)}. If
    \code{cluster} is provided, these comparisons are computed from a
    regression using \code{lm2()} with clustered standard errors.}
  \item{Interaction}{The interaction is tested using a linear regression fit
    with \code{lm2()}, even when \code{cluster} is \code{NULL}; when
    \code{cluster} is provided, the interaction test uses clustered standard
    errors.}
}
The regression-based tests use heteroskedasticity-robust inference (HC3) when
\code{cluster} is \code{NULL}. HC3 is a common small-sample adjustment to
White-type robust standard errors and is used to reduce sensitivity to
heteroskedasticity. When \code{cluster} is provided, \code{plot_means()}
instead uses clustered standard errors (robust to within-cluster correlation).

In the returned \code{$means} table, \code{ciL} and \code{ciH} are the lower and
upper bounds of a \code{ci.level}\% confidence interval for the mean (when
available). The same confidence level is used for the confidence-interval
whiskers drawn in the figure.
}
\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)

}
