Skip to main content
v2026.11,986 entries · CC-BY 4.0

ggstatsplot: Statistical Plots with Test Results in R

ggstatsplot draws ggplot2 charts with test results printed on them. Install it, pick the right function and read the subtitle and caption.

Written and maintained by CASRAI Editorial Board

Published

On this page

ggstatsplot is a free R package that draws ggplot2 charts with the statistical test results printed on the plot itself: the test statistic, degrees of freedom, p-value, effect size with its confidence interval and the sample size appear in the subtitle, and Bayesian results in the caption. One function call produces both the figure and the analysis, so what is plotted and what is reported always come from the same data. The current CRAN release is version 1.1.4 (published 2026-10-22, MIT licence, maintained by Indrajeet Patil), and it requires R 4.5.0 or later.

What ggstatsplot is used for in research

The package targets a common routine in empirical work: look at the data, run the matching test, and report both. ggstatsplot wraps that routine for continuous variables (violin plots, scatterplots, histograms, dot plots, dot-and-whisker plots) and categorical variables (pie and bar charts). It supports parametric, non-parametric, robust and Bayesian versions of t-tests and ANOVA, correlation analysis, contingency-table analysis, meta-analysis and regression, according to the CRAN description. The statistics themselves are computed by the companion package statsExpressions, which ggstatsplot calls internally.

Three situations suit it well. First, exploratory analysis, where a figure that already carries the test result saves a separate model-fitting step. Second, teaching and lab meetings, where the plot shows the evidence and the test at once. Third, reproducible reporting: the numbers printed on the figure can be pulled back out as data frames, so a manuscript table and the figure cannot drift apart. The package documentation is explicit about one limit: it runs the test you request and does not check that the test’s assumptions hold, so assumption checking is a separate step (the documentation points to the performance package for that).

Which function answers which research question

The data table below lists the nine main functions and the design each one serves. Each has a grouped_ variant (for example grouped_ggbetweenstats()) that repeats the plot for every level of a grouping variable, except ggcoefstats(), which has none.

How to install or access ggstatsplot

Install the stable release from CRAN, the official R package repository, then load the package. The CRAN page for version 1.1.4 lists R 4.5.0 or later as a dependency, so update R first if R.version.string reports an older release.

  1. Install the CRAN release: install.packages("ggstatsplot")
  2. Load it: library(ggstatsplot)
  3. Optional, to try the development version from GitHub: pak::pak("IndrajeetPatil/ggstatsplot") (this needs the pak package installed)

The package documentation site is indrapatil.com/ggstatsplot, the source code and issue tracker are on GitHub, and the CRAN record carries the DOI 10.32614/CRAN.package.ggstatsplot. Optional packages such as BayesFactor, WRS2 and metafor are listed under Suggests on CRAN; they supply the Bayesian, robust and meta-analytic back ends.

How to compare a measurement across groups step by step

The most frequent use in research is comparing a continuous outcome between groups, which is the job of ggbetweenstats(). The example uses the built-in mtcars data, which ships with R, so it runs without any file. Replace the data frame and columns with your own measurement and grouping variable.

  1. Load the package and fix the random seed so the plot is reproducible: library(ggstatsplot) then set.seed(123).
  2. Draw a two-group comparison: p = ggbetweenstats(mtcars, am, mpg). The arguments are the data, the grouping variable x and the outcome y. Print it with p.
  3. Choose the statistical approach with type. The accepted values are "parametric" (the default), "nonparametric", "robust" and "bayes"; matching uses only the first lowercase letter, so a misspelt or capitalised value such as "Bayes" silently falls back to parametric.
  4. For three or more groups, pairwise comparisons are drawn too: ggbetweenstats(mtcars, cyl, mpg, pairwise.display = "all"). By default only significant pairs are shown (pairwise.display = "significant"), adjusted with the Holm method at pairwise.alpha = 0.05.
  5. Extract the numbers behind the plot as data frames: extract_stats(p).
  6. Style it as needed, for example xlab, ylab, title, a ggplot2 theme through ggtheme, or a paletteer palette through palette = "package::palette".

For repeated measures, ggwithinstats() takes the same shape of call; set subject.id so that a participant with any missing condition is dropped as a whole. For two continuous variables use ggscatterstats(), for a correlation matrix ggcorrmat(), and for counts ggpiestats() or ggbarstats().

Choosing between parametric, non-parametric, robust and Bayesian output

The four values of type are not four colour schemes; each changes the test that is run. According to the package documentation, parametric two-group comparisons use Welch’s t-test with Hedges’ g as the effect size, and comparisons of three or more groups use the Welch one-way test with omega-squared. The robust option uses trimmed means, with the trim level set by tr (default 0.2). The Bayesian option reports Bayes factors, with the prior width set by bf.prior (default 0.707, allowed range 0.5 to 2). Two combinations do not exist: robust tests are not available for ggpiestats() and ggbarstats(), and non-parametric meta-analysis is not available in ggcoefstats(). The effect-size choices are not user-settable in these functions; the documentation tells users who need other settings to call statsExpressions directly.

How to read the output

A ggstatsplot figure has two text regions that carry the statistics. The subtitle holds the frequentist result: the test statistic, its degrees of freedom, the p-value, the effect size with its confidence interval, and the number of observations used. In the package’s own example, a Welch one-way test is reported with omega-squared. The caption holds the Bayesian result, a Bayes factor and a Bayesian R-squared with a credible interval, and it is controlled separately from the subtitle. Read the subtitle the way you would read a results sentence: the effect size and its interval say how large the difference is, and the p-value says only how compatible the data are with no difference. The dictionary entries for p-value, effect size and confidence interval give the definitions used in this site.

The sample size matters for interpretation. Rows with a missing value in the grouping or outcome variable are removed before plotting and analysis, and unused factor levels are dropped, so the n in the subtitle can be smaller than the number of rows in the data frame. The default confidence level is 0.95 (conf.level). The conf.level argument changes the interval width but does not change which pairwise brackets appear; that is controlled by pairwise.alpha and p.adjust.method.

Pulling the statistics out for a manuscript

Three helper functions make the printed statistics reusable. extract_stats() returns the underlying data frames, for example the pairwise comparison table. extract_subtitle() and extract_caption() return only the expressions drawn on the plot. The method column of the extract_stats() output names the test that was actually run, which is the quickest way to state it correctly in a methods section. ggcorrmat() does not keep these data frames, so for a correlation table use correlation::correlation() instead, as the package FAQ advises. A worked example of the full pipeline looks like this:

  1. set.seed(123)
  2. p = ggbetweenstats(mtcars, cyl, mpg, pairwise.display = "all")
  3. stats_list = extract_stats(p)
  4. stats_list$pairwise_comparisons_data to read the adjusted pairwise results.

Because the figure and the extracted data frames come from one call, the p-values in a table can be checked against the plot rather than retyped. For a plot with the significance brackets customised further, the package FAQ recommends turning the built-in brackets off with pairwise.display = "none" and adding specific ones with ggsignif::geom_signif(); the ggsignif guide covers that function, and the broader guide to ggplot2 plots in R covers the plotting grammar underneath ggstatsplot.

Troubleshooting ggstatsplot

The problems below are the ones the package documentation itself describes. Each pairs the symptom with the documented cause.

Installation fails or the package will not load

Check the R version first. Version 1.1.4 on CRAN depends on R 4.5.0 or later and on recent versions of ggplot2 (4.0.3 or later), so an older R installation cannot install the current release. Update R, then run install.packages("ggstatsplot") again.

The subtitle or caption is missing

ggstatsplot returns a NULL subtitle or caption without raising an error when the analysis fails; for example, a group whose outcome values are constant produces no statistics. To find the cause, run the underlying statsExpressions function directly, such as statsExpressions::two_sample_test(), which reports when the data are essentially constant. Hiding the subtitle on purpose is a different setting: results.subtitle = FALSE turns it off, bf.message = FALSE turns off the Bayes factor caption and centrality.plotting = FALSE removes the centrality annotations.

Significance brackets disappear after setting axis limits

Using scale_y_continuous(limits = ...) sets out-of-range data to NA, which drops the brackets. Zoom with coord_cartesian(ylim = ...) instead, which changes the view without altering the data.

An error appears with type = “robust”

The documentation for ggbetweenstats() suggests lowering the trim level tr (default 0.2) if a robust test errors.

A test you need is not offered

The FAQ describes building a custom expression with statsExpressions::add_expression_col(), using Kendall’s tau from correlation() as its example, and notes that this expression builder is not yet stable. Use the output with care and state the test in the manuscript text.

Missing values and grouped plots behave unexpectedly

Rows with NA are removed before analysis, and in grouped_ functions rows with a missing grouping value are dropped. There is no built-in alpha adjustment across the panels of a grouped plot, so apply your own correction if you interpret many panels together. Grouped outputs are patchwork objects: use ggplot.component to alter each sub-plot, or the ampersand (&) operator to apply a component to all of them.

Free alternatives to ggstatsplot

All the packages below are free R packages, and the ggstatsplot documentation points to each of them for a task where its own defaults are not enough. They are complements as much as substitutes: each covers one piece of what ggstatsplot does in a single call.

Package Use it when Source
statsExpressions You want the test results and formatted expressions without the plot, or need effect-size settings that ggstatsplot does not expose ggbetweenstats reference page
ggsignif You want to add or place individual significance brackets on any ggplot2 figure ggstatsplot FAQ
correlation You need a correlation table as data; ggcorrmat() does not retain the data frames ggstatsplot FAQ
performance You need to check model assumptions before choosing a test, which ggstatsplot does not do ggstatsplot FAQ

If the question is the choice of statistical environment rather than one package, the comparison of R and Stata for statistical analysis sets out the wider trade-offs.

Sources

Data: ggstatsplot main functions by research question

Compilation of the nine main plotting functions of the ggstatsplot R package (version 1.1.4), with the research question each addresses, its plot type and whether a grouped_ variant exists, compiled from the CRAN description and the package documentation.

Period covered: 2026.

ggstatsplot main functions by research question
FunctionResearch questionPlot typegrouped_ variant
ggbetweenstatsDoes a continuous outcome differ between independent groups?Violin plot with box plot and pointsYes
ggwithinstatsDoes a continuous outcome differ across repeated measurements on the same subjects?Violin plot with paired linesYes
gghistostatsWhat does the distribution of one continuous variable look like, with a test against a reference value?HistogramYes
ggdotplotstatsHow do values of one variable compare across labelled units?Dot plotYes
ggscatterstatsHow strongly are two continuous variables correlated?ScatterplotYes
ggcorrmatHow are many continuous variables correlated with each other?Correlation matrixYes
ggpiestatsDo category counts differ from expectation, or are two categorical variables associated?Pie chartYes
ggbarstatsDo category counts differ from expectation, or are two categorical variables associated?Bar chartYes
ggcoefstatsWhat are the estimates of a fitted regression or meta-analysis model?Dot-and-whisker plotNo

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about ggstatsplot: Statistical Plots with Test Results in R

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →