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.
- Install the CRAN release:
install.packages("ggstatsplot") - Load it:
library(ggstatsplot) - 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.
- Load the package and fix the random seed so the plot is reproducible:
library(ggstatsplot)thenset.seed(123). - Draw a two-group comparison:
p = ggbetweenstats(mtcars, am, mpg). The arguments are the data, the grouping variablexand the outcomey. Print it withp. - 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. - 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 atpairwise.alpha = 0.05. - Extract the numbers behind the plot as data frames:
extract_stats(p). - Style it as needed, for example
xlab,ylab,title, a ggplot2 theme throughggtheme, or a paletteer palette throughpalette = "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:
set.seed(123)p = ggbetweenstats(mtcars, cyl, mpg, pairwise.display = "all")stats_list = extract_stats(p)stats_list$pairwise_comparisons_datato 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.
| Function | Research question | Plot type | grouped_ variant |
|---|---|---|---|
| ggbetweenstats | Does a continuous outcome differ between independent groups? | Violin plot with box plot and points | Yes |
| ggwithinstats | Does a continuous outcome differ across repeated measurements on the same subjects? | Violin plot with paired lines | Yes |
| gghistostats | What does the distribution of one continuous variable look like, with a test against a reference value? | Histogram | Yes |
| ggdotplotstats | How do values of one variable compare across labelled units? | Dot plot | Yes |
| ggscatterstats | How strongly are two continuous variables correlated? | Scatterplot | Yes |
| ggcorrmat | How are many continuous variables correlated with each other? | Correlation matrix | Yes |
| ggpiestats | Do category counts differ from expectation, or are two categorical variables associated? | Pie chart | Yes |
| ggbarstats | Do category counts differ from expectation, or are two categorical variables associated? | Bar chart | Yes |
| ggcoefstats | What are the estimates of a fitted regression or meta-analysis model? | Dot-and-whisker plot | No |
Sources
- CRAN: package ggstatsplot (accessed 2026-11-17)
- ggstatsplot documentation site (accessed 2026-11-17)
- ggstatsplot function reference index (accessed 2026-11-17)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







