grouped_ggbetweenstats: Violin plots for group or condition comparisons in...

In ggstatsplot: 'ggplot2' Based Plots with Statistical Details

Violin plots for group or condition comparisons in between-subjects designs repeated across all levels of a grouping variable

Description

Helper function for ggstatsplot::ggbetweenstats to apply this function across multiple levels of a given factor and combine the resulting plots using ggstatsplot::combine_plots.

Usage

grouped_ggbetweenstats(
  data,
  ...,
  grouping.var,
  plotgrid.args = list(),
  annotation.args = list()
)

Arguments

data	A data frame (or a tibble) from which variables specified are to be taken. Other data types (e.g., matrix, table, array, etc.) will not be accepted. Additionally, grouped data frames from {dplyr} should be ungrouped before they are entered as data.
...	Arguments passed on to ggbetweenstats xlab Label for x axis variable. If NULL (default), variable name for x will be used. ylab Label for y axis variable. If NULL (default), variable name for y will be used. p.adjust.method Adjustment method for p-values for multiple comparisons. Possible methods are: "holm" (default), "hochberg", "hommel", "bonferroni", "BH", "BY", "fdr", "none". pairwise.display Decides which pairwise comparisons to display. Available options are: "significant" (abbreviation accepted: "s") "non-significant" (abbreviation accepted: "ns") "all" "none" You can use this argument to make sure that your plot is not uber-cluttered when you have multiple groups being compared and scores of pairwise comparisons being displayed. Pairwise comparisons are carried out (and displayed) only when x has three or more levels. For type = "bayes", there are no p-values, so all comparisons are displayed unless this is "none". pairwise.alpha Numeric alpha threshold used to decide which pairwise comparisons are displayed when pairwise.display = "significant" or pairwise.display = "non-significant" (Default: 0.05). It is compared against p-values adjusted using p.adjust.method. bf.message Logical that decides whether to display Bayes Factor in favor of the null hypothesis. This argument is relevant only for parametric test (Default: TRUE). results.subtitle Decides whether the results of statistical tests are to be displayed as a subtitle (Default: TRUE). Setting this to FALSE also skips the automatic Bayes Factor caption. See the individual annotation arguments to control other plot details. subtitle The text for the plot subtitle. Will work only if results.subtitle = FALSE. caption The text for the plot caption. It will be replaced by the Bayes Factor caption whenever that is displayed (see bf.message). centrality.plotting Logical that decides whether central tendency measure is to be displayed as a point with a label (Default: TRUE). Function decides which central tendency measure to show depending on the type argument. mean for parametric statistics median for non-parametric statistics trimmed mean for robust statistics MAP estimator for Bayesian statistics If you want a different centrality parameter, you can specify this using centrality.type argument. centrality.type Decides which centrality parameter is to be displayed. The default is to choose the same as type argument. You can specify this to be: "parametric" (for mean) "nonparametric" (for median) "robust" (for trimmed mean) "bayes" (for MAP estimator) Just as type argument, abbreviations are also accepted. point.args A list of additional aesthetic arguments to be passed to the ggplot2::geom_point(). boxplot.args A list of additional aesthetic arguments passed on to ggplot2::geom_boxplot(). By default, the whiskers extend to 1.5 times the interquartile range (IQR) from the box (Tukey-style). To customize whisker length, you can use the coef parameter, e.g., boxplot.args = list(coef = 3) for whiskers extending to the most extreme observations within 3 * IQR of the hinges. violin.args A list of additional aesthetic arguments to be passed to the ggplot2::geom_violin(). ggplot.component A ggplot component to be added to the plot prepared by {ggstatsplot}. This argument is primarily helpful for grouped_ variants of all primary functions. Default is NULL. The argument should be entered as a {ggplot2} function or a list of {ggplot2} functions. 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. centrality.point.args,centrality.label.args A list of additional aesthetic arguments to be passed to ggplot2::geom_point() and ggrepel::geom_label_repel() geoms, which are involved in centrality plotting. ggsignif.args A list of additional aesthetic arguments to be passed to ggsignif::geom_signif(). 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. x The grouping (or independent) variable from data. y The response (or outcome or dependent) variable from data. type A character specifying the type of statistical approach: "parametric" "nonparametric" "robust" "bayes" You can specify just the initial letter (e.g. "np" or "bf"). Matching is on the initial lowercase letter only, so any other value (including capitalized values such as "Bayes") falls back to "parametric" without a warning. 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()). conf.level Scalar between 0 and 1 (default: ⁠95%⁠ confidence/credible intervals, 0.95). bf.prior A number between 0.5 and 2 (default 0.707), the prior width to use in calculating Bayes factors and posterior estimates. In addition to numeric arguments, several named values are also recognized: "medium", "wide", and "ultrawide", corresponding to r scale values of 1/2, sqrt(2)/2, and 1, respectively. In case of an ANOVA, this value corresponds to scale for fixed effects. tr Trim level for the mean when carrying out robust tests. In case of an error, try reducing the value of tr, which is by default set to 0.2. Lowering the value might help. alternative a character string specifying the alternative hypothesis, must be one of "two.sided" (default), "greater" or "less". You can specify just the initial letter.
grouping.var	A single grouping variable. A separate plot is created for each of its levels (in factor level order, or in order of appearance for character variables). Rows with a missing value in this variable are removed.
plotgrid.args	A list of additional arguments passed to patchwork::wrap_plots(), except for guides argument which is already separately specified here.
annotation.args	A list of additional arguments passed to patchwork::plot_annotation().

Value

A patchwork object combining one plot per level of grouping.var (see combine_plots()). Applying extract_stats() to it returns a list with the statistical details for each of these plots.

See Also

ggbetweenstats, ggwithinstats, grouped_ggwithinstats

Examples

# for reproducibility
set.seed(123)

library(dplyr, warn.conflicts = FALSE)
library(ggplot2)

grouped_ggbetweenstats(
  data = filter(ggplot2::mpg, drv != "4"),
  x = year,
  y = hwy,
  grouping.var = drv
)

# modifying individual plots using `ggplot.component` argument
grouped_ggbetweenstats(
  data = filter(
    movies_long,
    genre %in% c("Action", "Comedy"),
    mpaa %in% c("R", "PG")
  ),
  x = genre,
  y = rating,
  grouping.var = mpaa,
  ggplot.component = scale_y_continuous(
    breaks = seq(1, 9, 1),
    limits = (c(1, 9))
  ),
  annotation.args = list(title = "Ratings by genre for different MPAA ratings")
)

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