ggcoefstats: Dot-and-whisker plots for regression analyses

In ggstatsplot: 'ggplot2' Based Plots with Statistical Details

Dot-and-whisker plots for regression analyses

Description

Plot with the regression coefficients' point estimates as dots with confidence interval whiskers and other statistical details included as labels.

Although the statistical models displayed in the plot may differ based on the class of models being investigated, there are a few aspects of the plot that will be invariant across models:

• The dot-whisker plot contains a dot representing the estimate and their confidence intervals (⁠95%⁠ is the default). The estimate can either be effect sizes (for tests that depend on the F-statistic) or regression coefficients (for tests with t-, chi^2-, and z-statistic), etc. The function will, by default, display a helpful x-axis label that should clear up what estimates are being displayed. The confidence intervals can sometimes be asymmetric if bootstrapping was used.

• The label attached to each dot will provide more details from the statistical test carried out and it will typically contain estimate, statistic, and p-value.

• The caption will contain diagnostic information, if available, about models that can be useful for model selection: The smaller the Akaike's Information Criterion (AIC) and the Bayesian Information Criterion (BIC) values, the "better" the model is.

• The output of this function will be a {ggplot2} object and, thus, it can be further modified (e.g. change themes) with {ggplot2}.

Usage

ggcoefstats(
  x,
  statistic = NULL,
  conf.int = TRUE,
  conf.level = 0.95,
  digits = 2L,
  exclude.intercept = FALSE,
  effectsize.type = "omega",
  meta.analytic.effect = FALSE,
  meta.type = "parametric",
  bf.message = TRUE,
  sort = "none",
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  only.significant = FALSE,
  point.args = list(size = 3, color = "blue", na.rm = TRUE),
  errorbar.args = list(width = 0, na.rm = TRUE),
  vline = TRUE,
  vline.args = list(linewidth = 1, linetype = "dashed"),
  stats.labels = TRUE,
  stats.label.color = NULL,
  stats.label.args = list(size = 3, direction = "y", min.segment.length = 0, na.rm =
    TRUE),
  palette = "ggthemes::gdoc",
  ggtheme = ggstatsplot::theme_ggstatsplot(),
  ...
)

Arguments

x	A model object to be tidied, or a tidy data frame from a regression model. Function internally uses parameters::model_parameters() to get a tidy data frame. If a data frame, it must contain a column named estimate (estimates of coefficients or other quantities of interest). A term column (names of predictors) is recommended; if absent, terms are named term_1, term_2, etc. Columns conf.low and conf.high are needed for error bars, statistic and p.value for labels, and std.error for meta-analysis.
statistic	Relevant statistic for the model ("t", "f", "z", or "chi") in the label. Relevant only if x is a data frame; if it is NULL (default), no labels are shown for data frames.
conf.int	Logical. Decides whether to display confidence intervals as error bars (Default: TRUE).
conf.level	Numeric deciding level of confidence or credible intervals (Default: 0.95).
digits	Number of digits for rounding or significant figures. May also be "signif" to return significant figures or "scientific" to return scientific notation. Control the number of digits by adding the value as suffix, e.g. digits = "scientific4" to have scientific notation with 4 decimal places, or digits = "signif5" for 5 significant figures (see also signif()).
exclude.intercept	Logical that decides whether the intercept should be excluded from the plot (Default: FALSE).
effectsize.type	This is the same as es_type argument of parameters::model_parameters(). Defaults to "omega" (the unbiased estimator), and relevant for ANOVA-like objects.
meta.analytic.effect	Logical that decides whether to display a subtitle with results from a meta-analysis via linear (mixed-effects) models (default: FALSE). If TRUE, input to argument subtitle will be ignored. This will be mostly relevant if a data frame with estimates and their standard errors is entered.
meta.type	Type of statistics used to carry out random-effects meta-analysis. If "parametric" (default), metafor::rma() will be used. If "robust", metaplus::metaplus() will be used. If "bayes", metaBMA::meta_random() will be used.
bf.message	Logical that decides whether results from running a Bayesian meta-analysis assuming that the effect size d varies across studies with standard deviation t (i.e., a random-effects analysis) should be displayed in caption. Relevant only if meta.analytic.effect = TRUE and meta.type = "parametric". Defaults to TRUE.
sort	If "none" (default) do not sort, "ascending" sort by increasing coefficient value, or "descending" sort by decreasing coefficient value.
xlab	Label for x axis. If NULL (default), "estimate" is used.
ylab	Label for y axis. If NULL (default), "term" is used.
title	The text for the plot title.
subtitle	The text for the plot subtitle. The input to this argument will be ignored if meta.analytic.effect is set to TRUE.
caption	The text for the plot caption. It will be replaced by model fit indices (AIC and BIC), if available, or by the Bayesian meta-analysis results (see bf.message).
only.significant	If TRUE, only stats labels for significant effects (p < 0.05) are shown (Default: FALSE). This can be helpful when a large number of regression coefficients are to be displayed in a single plot.
point.args	A list of additional aesthetic arguments to be passed to the ggplot2::geom_point().
errorbar.args	Additional arguments that will be passed to ggplot2::geom_errorbar() geom. Please see documentation for that function to know more about these arguments.
vline	Decides whether to display a vertical line at 0 (Default: TRUE).
vline.args	Additional arguments that will be passed to ggplot2::geom_vline() geom. Please see documentation for that function to know more about these arguments.
stats.labels	Logical. Decides whether the statistic and p-values for each coefficient are to be attached to each dot as a text label using {ggrepel} (Default: TRUE).
stats.label.color	Color for the labels: either a single color or a vector with one color per term. If set to NULL (default), colors will be chosen from the specified palette.
stats.label.args	Additional arguments that will be passed to ggrepel::geom_label_repel().
palette	Name of the discrete palette in "package::palette" format to be used for coloring (via {paletteer}). Run View(paletteer::palettes_d_names) to see all available options.
ggtheme	A {ggplot2} theme. Default value is theme_ggstatsplot(). Any of the {ggplot2} themes (e.g., ggplot2::theme_bw()), or themes from extension packages are allowed (e.g., ggthemes::theme_fivethirtyeight(), hrbrthemes::theme_ipsum_ps(), etc.). But note that sometimes these themes will remove some of the details that {ggstatsplot} plots typically contain. For example, if relevant, ggbetweenstats() shows details about multiple comparison test as a label on the secondary Y-axis. Some themes (e.g. ggthemes::theme_fivethirtyeight()) will remove the secondary Y-axis and thus the details as well.
...	Additional arguments to tidying method. For more, see parameters::model_parameters().

Details

For details, see: https://www.indrapatil.com/ggstatsplot/articles/web_only/ggcoefstats.html

Value

A ggplot object, which can be further modified with {ggplot2} functions. Use extract_stats() to get the statistical details shown in the plot as data frames.

Summary of graphics

graphical element	geom used	argument for further modification
regression estimate	ggplot2::geom_point()	point.args
error bars	ggplot2::geom_errorbar()	errorbar.args
vertical line	ggplot2::geom_vline()	vline.args
label with statistical details	ggrepel::geom_label_repel()	stats.label.args

Random-effects meta-analysis

The table below provides summary about:

• statistical test carried out for inferential statistics

• type of effect size estimate and a measure of uncertainty for this estimate

• functions used internally to compute these details

Hypothesis testing and effect size estimation

Type	Test	Effect size	CI available?	Function used
Parametric	Meta-analysis via random-effects models	beta	Yes	metafor::rma()
Robust	Meta-analysis via robust random-effects models	beta	Yes	metaplus::metaplus()
Bayesian	Meta-analysis via Bayesian random-effects models	beta	Yes	metaBMA::meta_random()

Note

1. In case you want to carry out meta-analysis, you will be asked to install the needed packages ({metafor}, {metaplus}, or {metaBMA}) if they are unavailable.

2. Rows with a missing estimate are always removed. If labels are requested, rows where statistic, std.error, or p.value is missing are kept but get no label.

3. Given the rapid pace at which new methods are added to these packages, it is recommended that you install development versions of {easystats} packages using the install_latest() function from {easystats}.

Examples

# for reproducibility
set.seed(123)

# model object
mod <- lm(formula = mpg ~ cyl * am, data = mtcars)

# creating a plot
p <- ggcoefstats(mod)

# looking at the plot
p

# extracting details from statistical tests
extract_stats(p)

# exclude intercept from the plot
ggcoefstats(mod, exclude.intercept = TRUE)

# only show significant labels
ggcoefstats(mod, only.significant = TRUE)

# ANOVA model (F-statistic)
ggcoefstats(aov(mpg ~ cyl * am, data = mtcars))

# a tidy data frame can also be passed directly (model-free use)
ggcoefstats(data.frame(term = c("a", "b", "c"), estimate = c(0.5, -0.2, 1.1)))

# without a `term` column (auto-generated)
ggcoefstats(data.frame(estimate = c(0.5, -0.2, 1.1)))

# tidy data frames can also include stats-label inputs directly
df_tidy <- parameters::model_parameters(stats::lm(wt ~ am * cyl, mtcars), ci = 0.95)
names(df_tidy) <- c(
  "term", "estimate", "std.error", "conf.level", "conf.low",
  "conf.high", "statistic", "df.error", "p.value"
)
df_tidy$p.value[2L] <- 0.42

ggcoefstats(
  df_tidy,
  statistic = "t",
  only.significant = TRUE,
  stats.label.color = c("firebrick", "grey50", "forestgreen", "navy")
)


# further arguments can be passed to `parameters::model_parameters()`
library(lme4)
ggcoefstats(lmer(Reaction ~ Days + (Days | Subject), sleepstudy), effects = "fixed")

ggstatsplot documentation built on Oct. 18, 2026, 1:07 a.m.