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”.
- Install the released version:
install.packages("ggsignif"). - Load it after ggplot2:
library(ggplot2)thenlibrary(ggsignif). - 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.
- 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(). - 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. - 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). - To use a different test, name it:
geom_signif(comparisons = ..., test = "t.test"). Extra arguments for the test go intest.args, for exampletest.args = list(var.equal = TRUE). - For a horizontal plot, either use
coord_flip(), which the project site shows working, or setorientation = "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
- CRAN, ggsignif package page, version 0.6.4: cran.r-project.org/web/packages/ggsignif (read 2026-11-15).
- ggsignif reference manual: cran.r-project.org/web/packages/ggsignif/refman/ggsignif.html (read 2026-11-15).
- ggsignif project site: const-ae.github.io/ggsignif (read 2026-11-15).
- Vignette, Introduction to ‘ggsignif’ package: cran.r-project.org/web/packages/ggsignif/vignettes/intro.html (read 2026-11-15).
- ggpubr reference manual: cran.r-project.org/web/packages/ggpubr/refman/ggpubr.html (read 2026-11-15).
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.
| Argument | Default | What it controls |
|---|---|---|
| comparisons | NULL | List of length-two vectors naming the groups (or column indices) to compare |
| test | wilcox.test | Test function; a custom function must return a list with p.value |
| test.args | NULL | Extra arguments passed to the test |
| annotations | NULL | Text to print; if set, test is ignored |
| map_signif_level | FALSE | TRUE prints asterisks; a named numeric vector or function sets custom labels |
| margin_top | 0.05 | Clearance above the data before the first bracket |
| step_increase | 0 | Extra height fraction for each successive bracket |
| tip_length | 0.03 | Length of the tick marks at the bracket ends |
| extend_line | 0 | Extends the bracket line (geom_signif only) |
| size | 0.5 | Line width of the bracket |
| textsize | 3.88 | Label text size |
| manual | FALSE | TRUE draws brackets from a supplied data frame instead of running tests |
| na.rm | FALSE | If FALSE, missing values are removed with a warning |
Sources
- ggsignif reference manual (CRAN) (accessed 2026-11-15)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







