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

ggsignif: Add Significance Brackets to ggplot2 Plots

Install ggsignif, add p-value or asterisk brackets to ggplot2 boxplots, and check the defaults, notably wilcox.test as the default test.

Written and maintained by CASRAI Editorial Board

Published · Last updated

On this page

ggsignif is an R package that adds significance brackets, with a p-value or asterisk label, between groups on a ggplot2 plot. You install it with install.packages("ggsignif"), load it with library(ggsignif), and add a single geom_signif() layer that names the pairs of groups to compare. The package runs a test for each pair, wilcox.test by default, and draws the result on the figure.

This guide is for researchers who already have a ggplot2 boxplot, bar chart or violin plot and need to mark which group differences are significant. It covers installation, a worked boxplot example, the argument defaults that change what the figure says, how to supply your own p-values, and what to do when brackets overlap or are cut off. The version described is ggsignif 0.6.4 (published on CRAN 2022-10-13), read 2026-11-15.

What ggsignif is used for in research

The project describes ggsignif as a package that provides “an easy way to indicate if two groups are significantly different”. In practice it saves you from computing pairwise tests in one place and positioning brackets by hand in another. You declare the comparisons inside the plot code, and the bracket, tick marks and label are drawn at a height that clears the data.

The package is released under the GPL-3 licence and the maintainer is Constantin Ahlmann-Eltze. It imports ggplot2 (version 3.3.5 or later) and exposes one layer, geom_signif, plus a sibling stat_signif that behaves the same way with the stat fixed. If you are new to building the underlying plot first, see our guide to ggplots in R and the walkthrough on boxplots with ggplot2.

How to install or access it

The package is distributed through CRAN, the official R package archive. Its CRAN page lists a reference manual and a vignette titled “Introduction to ‘ggsignif’ package”.

  1. Install the released version: install.packages("ggsignif").
  2. Load it after ggplot2: library(ggplot2) then library(ggsignif).
  3. Optional, for the development version from the project repository: remotes::install_github("const-ae/ggsignif"). This needs the remotes package, and the development version can differ from the CRAN release described here.

Step-by-step: add significance brackets to a boxplot

The example below follows the project’s own boxplot of highway mileage (hwy) by vehicle class from the mpg data set that ships with ggplot2. Swap in your own data frame and grouping column.

  1. Build the base plot with the grouping variable on the x axis and the measured variable on the y axis: p = ggplot(mpg, aes(class, hwy)) + geom_boxplot().
  2. Add the layer and list each pair of groups as a length-two vector inside a list: p + geom_signif(comparisons = list(c("compact", "midsize"), c("minivan", "suv"))). The group names must match the factor levels on the axis exactly. You can also give column indices instead of names.
  3. To show asterisks instead of numeric p-values, set map_signif_level = TRUE: p + geom_signif(comparisons = list(c("compact", "midsize"), c("minivan", "suv")), map_signif_level = TRUE).
  4. To use a different test, name it: geom_signif(comparisons = ..., test = "t.test"). Extra arguments for the test go in test.args, for example test.args = list(var.equal = TRUE).
  5. For a horizontal plot, either use coord_flip(), which the project site shows working, or set orientation = "y" on the layer.

The package vignette uses the iris data in the same way: Sepal.Length by Species, comparing versicolor with virginica, with map_signif_level = TRUE.

Dodged groups and facets

The project site notes that for dodged layouts (position = "dodge") the automatic comparisons do not apply and you place the bracket manually, computing the p-value yourself, for example with t.test(...)$p.value formatted with formatC. The same applies to facets: pass a data frame with columns xmin, xmax, annotations and y_position (mapped through aes()) and set manual = TRUE. Manual mode is also the route when your p-values come from a model that ggsignif does not run.

Output and how to read it

Each comparison produces a horizontal bracket spanning the two groups, short tick marks at its ends (tip_length, default 0.03), and a text label centred above it. With the default settings the label is the p-value from the test; with map_signif_level = TRUE it is a significance symbol. If you pass a named numeric vector such as c("***" = 0.001, "**" = 0.01, "*" = 0.05), those names become the labels and the numbers are the cut-offs, and you can pass a function that turns a p-value into any string you like.

When several comparisons are listed, ggsignif stacks them; step_increase (default 0) is the fraction of the plot height added for each successive bracket, so raising it separates overlapping brackets. The bracket height starts above the data, and margin_top (default 0.05) controls that clearance.

The label reports a test result for that single pair. The reference manual documents the arguments and defaults; it does not describe any adjustment of p-values across comparisons, so you should not read the printed values as multiplicity-corrected. This is an editorial point rather than a package claim: with several pairwise tests on the same figure, report which test was used, and if your analysis plan requires a correction, compute the adjusted values yourself (our Bonferroni correction in R guide shows one way) and pass them in with annotations.

Defaults that change what the figure says

Many tutorials assume a t-test. The default is not a t-test: test = "wilcox.test". If your methods section says Student’s or Welch’s t-test, set test = "t.test" explicitly so the figure and the text agree. A custom test function is accepted if it returns a list containing p.value. The full defaults from the reference manual are in the data table below this guide.

Supplying your own p-values

If annotations is set, the test argument is ignored and your strings are printed instead. That makes it possible to show p-values from a mixed model, an ANOVA post-hoc procedure or any adjusted result: geom_signif(comparisons = list(c("compact", "midsize")), annotations = "adjusted p = 0.03", y_position = 45). Use y_position to set the bracket height (in data units) and xmin and xmax where you give positions directly. Keep a note of how each value was computed alongside the script, because the figure alone cannot show it.

Troubleshooting

Brackets overlap each other

Raise step_increase above its default of 0, for example 0.1, or set y_position to a vector of explicit heights.

A bracket is cut off at the top of the panel

Raise the upper limit of the y axis, for example with expand_limits(y = ...) or scale_y_continuous(expand = ...), or lower y_position.

Warning about missing values

na.rm defaults to FALSE, and the manual states that missing values are removed with a warning. Filter or impute deliberately before plotting if your analysis plan treats them in a particular way.

Group names not found

Names in comparisons must match the levels of the x variable exactly, including case. Check with levels(factor(mpg$class)) or your own column.

Label text or size

Use textsize (default 3.88), size for line width (default 0.5), vjust to nudge the label, family for the font, and parse = TRUE if the label is a plotmath expression.

Free alternatives

ggsignif is itself free and open source. The ggpubr package, which builds on ggplot2, offers a related function, stat_compare_means. The comparison below is limited to what the two packages’ CRAN reference manuals state.

Package Function How comparisons are named Licence
ggsignif 0.6.4 geom_signif(), stat_signif() comparisons as a list of length-two vectors; test defaults to "wilcox.test" GPL-3
ggpubr 1.0.0 stat_compare_means() comparisons argument, plus method, paired and hide.ns GPL-2 or GPL-3

For testing outside R, the Prism p-value on graph guide covers the equivalent bracket workflow.

Frequently asked questions

How do I install ggsignif?

Run install.packages("ggsignif") to get the CRAN release, then library(ggsignif). The development version is available with remotes::install_github("const-ae/ggsignif").

Which test does geom_signif use by default?

It uses wilcox.test. Set test = "t.test" or supply your own function that returns a list with a p.value element to change it.

Can I show asterisks instead of p-values?

Yes. Set map_signif_level = TRUE, or pass a named numeric vector of cut-offs or a function to control the symbols.

Does ggsignif correct for multiple comparisons?

The reference manual does not document any correction. If you need adjusted p-values, calculate them separately and pass them through annotations.

What is the difference between geom_signif and stat_signif?

Per the reference manual, geom_signif uses stat = "signif" by default and stat_signif is the same function with the stat fixed. Only geom_signif has the extend_line argument.

Sources

Data: ggsignif geom_signif() argument defaults (version 0.6.4)

Default values and meaning of the main geom_signif and stat_signif arguments in ggsignif 0.6.4, compiled from the package's CRAN reference manual.

Period covered: 2022.

ggsignif geom_signif() argument defaults (version 0.6.4)
ArgumentDefaultWhat it controls
comparisonsNULLList of length-two vectors naming the groups (or column indices) to compare
testwilcox.testTest function; a custom function must return a list with p.value
test.argsNULLExtra arguments passed to the test
annotationsNULLText to print; if set, test is ignored
map_signif_levelFALSETRUE prints asterisks; a named numeric vector or function sets custom labels
margin_top0.05Clearance above the data before the first bracket
step_increase0Extra height fraction for each successive bracket
tip_length0.03Length of the tick marks at the bracket ends
extend_line0Extends the bracket line (geom_signif only)
size0.5Line width of the bracket
textsize3.88Label text size
manualFALSETRUE draws brackets from a supplied data frame instead of running tests
na.rmFALSEIf FALSE, missing values are removed with a warning

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 ggsignif: Add Significance Brackets to ggplot2 Plots

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 →