Skip to contents

Lifecycle: lifecycle

The function ggbetweenstats is designed to facilitate data exploration, and for making highly customizable publication-ready plots, with relevant statistical details included in the plot itself if desired. We will see examples of how to use this function in this vignette.

To begin with, here are some instances where you would want to use ggbetweenstats-

  • to check if a continuous variable differs across multiple groups/conditions

  • to compare distributions visually

Comparisons between groups with ggbetweenstats

To illustrate how this function can be used, we will use the gapminder dataset throughout this vignette. This dataset provides values for life expectancy, GDP per capita, and population, at 5 year intervals, from 1952 to 2007, for each of 142 countries (courtesy Gapminder Foundation). Let’s have a look at the data-

library(gapminder)

dplyr::glimpse(gapminder::gapminder)
#> Rows: 1,704
#> Columns: 6
#> $ country   <fct> "Afghanistan", "Afghanistan", "Afghanistan", "Afghanistan", …
#> $ continent <fct> Asia, Asia, Asia, Asia, Asia, Asia, Asia, Asia, Asia, Asia, …
#> $ year      <int> 1952, 1957, 1962, 1967, 1972, 1977, 1982, 1987, 1992, 1997, …
#> $ lifeExp   <dbl> 28.801, 30.332, 31.997, 34.020, 36.088, 38.438, 39.854, 40.8…
#> $ pop       <int> 8425333, 9240934, 10267083, 11537966, 13079460, 14880372, 12…
#> $ gdpPercap <dbl> 779.4453, 820.8530, 853.1007, 836.1971, 739.9811, 786.1134, …

Note: For the remainder of the vignette, we’re going to exclude Oceania from the analysis simply because there are so few observations (countries).

Suppose the first thing we want to inspect is the distribution of life expectancy for the countries of a continent in 2007. We also want to know if the mean differences in life expectancy between the continents is statistically significant.

The simplest form of the function call is-

ggbetweenstats(
  data = dplyr::filter(gapminder::gapminder, year == 2007, continent != "Oceania"),
  x = continent,
  y = lifeExp
)

Note:

  • The function automatically decides whether an independent samples t-test (for 2 groups) or a one-way ANOVA (3 or more groups) is carried out, based on the number of levels in the grouping variable. By default, Welch’s versions of these tests are used, i.e., equal variances are not assumed.

  • The output of the function is a ggplot object which means that it can be further modified with ggplot2 functions.

For the default parametric analysis, the caption shows log⁡e(BF01)\log_{e}(BF_{01}); set bf.message = FALSE to hide it. See Interpretation of Bayes Factors for the sign convention and evidence scale.

We can make the output much more aesthetically pleasing as well as informative by making use of the many optional parameters in ggbetweenstats. We’ll add a title and caption, better x and y axis labels. We can and will change the overall theme as well as the color palette in use. This time, let’s also use a robust test.

ggbetweenstats(
  data = dplyr::filter(gapminder, year == 2007, continent != "Oceania"),
  x = continent, ## grouping/independent variable
  y = lifeExp, ## dependent variable
  type = "robust", ## type of statistics
  xlab = "Continent", ## label for the x-axis
  ylab = "Life expectancy", ## label for the y-axis
  ggtheme = ggplot2::theme_gray(), ## a different theme
  palette = "yarrr::info2", ## choosing a different color palette
  title = "Comparison of life expectancy across continents (Year: 2007)",
  caption = "Source: Gapminder Foundation"
) + ## modifying the plot further
  ggplot2::scale_y_continuous(
    limits = c(35, 85),
    breaks = seq(from = 35, to = 85, by = 5)
  )

As can be appreciated from the robust effect size (explanatory measure of effect size ξ\xi) of 0.96, there are large differences in the (trimmed) mean life expectancy across continents. Importantly, this plot also helps us appreciate the distributions within any given continent. For example, although Asian countries are doing much better than African countries, on average, Afghanistan has a particularly grim average for the Asian continent, possibly reflecting the war and the political turmoil.

Here are a few more options:

  • The type (of test) argument also accepts the following abbreviations: "p" (for parametric), "np" (for nonparametric), "r" (for robust), "bf" (for Bayes Factor).

  • Any of the plot components can be hidden via its *.args argument: e.g., violin.args = list(width = 0) removes the violin plot, boxplot.args = list(width = 0) removes the box plot, and point.args = list(alpha = 0) hides the raw data points.

  • The color palettes can be modified (palette takes a "package::palette" string from paletteer).

Let’s use the combine_plots function to make one plot from four separate plots that demonstrate all of these options. Let’s compare life expectancy for all countries between 1957 and 2007. We will generate the plots one by one and then use combine_plots to merge them into one plot with some common labeling. It is possible, but not necessarily recommended, to make each plot have different colors or themes.

For example,

df_year <- dplyr::filter(gapminder::gapminder, year %in% c(1957, 2007))

p1 <- ggbetweenstats(
  data = df_year,
  x = year,
  y = lifeExp,
  xlab = "Year",
  ylab = "Life expectancy",
  # to remove violin plot
  violin.args = list(width = 0),
  type = "p",
  conf.level = 0.99,
  title = "Parametric test",
  palette = "ggsci::nrc_npg"
)

p2 <- ggbetweenstats(
  data = df_year,
  x = year,
  y = lifeExp,
  xlab = "Year",
  ylab = "Life expectancy",
  # to remove box plot
  boxplot.args = list(width = 0),
  type = "np",
  conf.level = 0.99,
  title = "Non-parametric Test",
  palette = "ggsci::uniform_startrek"
)

p3 <- ggbetweenstats(
  data = df_year,
  x = year,
  y = lifeExp,
  xlab = "Year",
  ylab = "Life expectancy",
  type = "r",
  conf.level = 0.99,
  title = "Robust Test",
  tr = 0.005,
  palette = "wesanderson::Royal2",
  digits = 3
)

## Bayes Factor for parametric t-test, showing only centrality measures
p4 <- ggbetweenstats(
  data = df_year,
  x = year,
  y = lifeExp,
  xlab = "Year",
  ylab = "Life expectancy",
  type = "bayes",
  violin.args = list(width = 0),
  boxplot.args = list(width = 0),
  point.args = list(alpha = 0),
  title = "Bayesian Test",
  palette = "ggsci::nrc_npg"
)

## combining the individual plots into a single plot
combine_plots(
  list(p1, p2, p3, p4),
  plotgrid.args = list(nrow = 2L),
  annotation.args = list(
    title = "Comparison of life expectancy between 1957 and 2007",
    caption = "Source: Gapminder Foundation"
  )
)

Grouped analysis with grouped_ggbetweenstats

What if we want to analyze both by continent and between 1957 and 2007? A combination of our two previous efforts.

ggstatsplot provides a special helper function for such instances: grouped_ggbetweenstats. This is merely a wrapper function around combine_plots. It applies ggbetweenstats across all levels of a specified grouping variable and then combines list of individual plots into a single plot. Note that the grouping variable can be anything: conditions in a given study, groups in a study sample, different studies, etc.

Let’s focus on the same 4 continents for the following years: 1967, 1987, 2007. Also, let’s carry out pairwise comparisons to see if there are differences between every pair of continents.

## select part of the dataset and use it for plotting
gapminder::gapminder |>
  dplyr::filter(year %in% c(1967, 1987, 2007), continent != "Oceania") |>
  grouped_ggbetweenstats(
    ## arguments relevant for ggbetweenstats
    x = continent,
    y = lifeExp,
    grouping.var = year,
    xlab = "Continent",
    ylab = "Life expectancy",
    pairwise.display = "significant", ## display only significant pairwise comparisons
    pairwise.alpha = 0.01, ## use a stricter alpha threshold to reduce clutter
    p.adjust.method = "fdr", ## adjust p-values for multiple tests using this method
    palette = "ggsci::default_jco",
    ## arguments relevant for combine_plots
    annotation.args = list(title = "Changes in life expectancy across continents (1967-2007)"),
    plotgrid.args = list(nrow = 3)
  )

As seen from the plot, although the life expectancy has been improving steadily across all continents as we go from 1967 to 2007, this improvement has not been happening at the same rate for all continents. Additionally, irrespective of which year we look at, we still find significant differences in life expectancy across continents which have been surprisingly consistent across four decades (based on the observed effect sizes).

Grouped analysis with ggbetweenstats + {purrr}

For group-specific arguments or multiple grouping variables, see the programmatic plotting article. It explains how to split the data, customize each call, and combine the resulting plots.

Within-subjects designs

For repeated measures designs, ggwithinstats() function can be used: https://www.indrapatil.com/ggstatsplot/articles/web_only/ggwithinstats.html

Summary of graphics and tests

graphical element geom used argument for further modification
raw data ggplot2::geom_point() point.args
box plot ggplot2::geom_boxplot() boxplot.args
density plot ggplot2::geom_violin() violin.args
centrality measure point ggplot2::geom_point() centrality.point.args
centrality measure label ggrepel::geom_label_repel() centrality.label.args
pairwise comparisons ggsignif::geom_signif() ggsignif.args

The statistical tests and effect sizes carried out for each type are listed in the function documentation: https://www.indrapatil.com/ggstatsplot/reference/ggbetweenstats.html

Extracting statistical details

Use extract_stats() to retrieve the results as data frames; its reference page describes all returned components, including the lists returned for grouped_ plots.

p <- ggbetweenstats(mtcars, cyl, mpg)

extract_stats(p)$subtitle_data
#> # A tibble: 1 × 14
#>   statistic    df df.error    p.value
#>       <dbl> <dbl>    <dbl>      <dbl>
#> 1      31.6     2     18.0 0.00000127
#>   method                                                   effectsize estimate
#>   <chr>                                                    <chr>         <dbl>
#> 1 One-way analysis of means (not assuming equal variances) Omega2        0.744
#>   conf.level conf.low conf.high conf.method conf.distribution n.obs expression
#>        <dbl>    <dbl>     <dbl> <chr>       <chr>             <int> <list>    
#> 1       0.95    0.531         1 ncp         F                    32 <language>

extract_stats(p)$pairwise_comparisons_data
#> # A tibble: 3 × 9
#>   group1 group2 statistic   p.value alternative distribution p.adjust.method
#>   <chr>  <chr>      <dbl>     <dbl> <chr>       <chr>        <chr>          
#> 1 4      6          -6.67 0.00110   two.sided   q            Holm           
#> 2 4      8         -10.7  0.0000140 two.sided   q            Holm           
#> 3 6      8          -7.48 0.000257  two.sided   q            Holm           
#>   test         expression
#>   <chr>        <list>    
#> 1 Games-Howell <language>
#> 2 Games-Howell <language>
#> 3 Games-Howell <language>

Reporting

If you wish to include statistical analysis results in a publication/report, the ideal reporting practice will be a hybrid of two approaches:

  • the ggstatsplot approach, where the plot contains both the visual and numerical summaries about a statistical model, and

  • the standard narrative approach, which provides interpretive context for the reported statistics.

For example:

ggbetweenstats(ToothGrowth, supp, len)

The narrative context (assuming type = "parametric") can complement this plot either as a figure caption or in the main text-

Welch’s t-test revealed that, across 60 guinea pigs, although the tooth length was higher when the animal received vitamin C via orange juice as compared to via ascorbic acid, this effect was not statistically significant. The effect size (g=0.49)(g = 0.49) was medium, as per Cohen’s (1988) conventions. The Bayes Factor for the same analysis revealed that the data were 1.2 times more probable under the alternative hypothesis as compared to the null hypothesis. This can be considered weak evidence (Jeffreys, 1961) in favor of the alternative hypothesis.

Similar reporting style can be followed when the function performs one-way ANOVA instead of a t-test.

Suggestions

If you find any bugs or have any suggestions/remarks, please file an issue on GitHub: https://github.com/IndrajeetPatil/ggstatsplot/issues

Citation

You can cite this package/vignette as:

To cite package 'ggstatsplot' in publications use:

  Patil, I. (2021). Visualizations with statistical details: The
  'ggstatsplot' approach. Journal of Open Source Software, 6(61), 3167,
  doi:10.21105/joss.03167

A BibTeX entry for LaTeX users is

  @Article{,
    doi = {10.21105/joss.03167},
    url = {https://doi.org/10.21105/joss.03167},
    year = {2021},
    publisher = {{The Open Journal}},
    volume = {6},
    number = {61},
    pages = {3167},
    author = {Indrajeet Patil},
    title = {{Visualizations with statistical details: The {'ggstatsplot'} approach}},
    journal = {{Journal of Open Source Software}},
  }