Ggstatsplot

<!-- README.md is generated from README.Rmd. Please edit that file -->

{ggstatsplot}: {ggplot2} Based Plots with Statistical Details

| Status | Usage | Miscellaneous | |----|----|----| | | | | | | | |

[!NOTE] This package supports R-devel, the current R release, and the previous R release.

Raison d’être <img src="man/figures/logo.png" alt="ggstatsplot package logo" align="right" width="360" />

“What is to be sought in designs for the display of information is the clear portrayal of complexity. Not the complication of the simple; rather … the revelation of the complex.” - Edward R. Tufte

{ggstatsplot} is an extension of {ggplot2} package for creating graphics with details from statistical tests included in the information-rich plots themselves. In a typical exploratory data analysis workflow, data visualization and statistical modeling are two different phases: visualization informs modeling, and modeling in its turn can suggest a different visualization method, and so on and so forth. The central idea of {ggstatsplot} is simple: combine these two phases into one in the form of graphics with statistical details, which makes data exploration simpler and faster.

Installation

| Type | Command | |:------------|:-----------------------------------------| | Release | install.packages("ggstatsplot") | | Development | pak::pak("IndrajeetPatil/ggstatsplot") |

Citation

If you want to cite this package in a scientific journal or in any other context, run the following code in your R console:

citation("ggstatsplot")
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}},
  }

Acknowledgments

I would like to thank all the contributors to {ggstatsplot} who pointed out bugs or requested features I hadn’t considered. I would especially like to thank other package developers (especially Daniel Lüdecke, Dominique Makowski, Mattan S. Ben-Shachar, Brenton Wiernik, Patrick Mair, Salvatore Mangiafico, etc.) who have patiently and diligently answered my relentless questions and supported feature requests in their projects. I also want to thank Chuck Powell for his initial contributions to the package.

The hexsticker was generously designed by Sarah Otterstetter (Max Planck Institute for Human Development, Berlin). This package has also benefited from the larger #rstats community on Twitter, LinkedIn, and StackOverflow.

Thanks are also due to my postdoc advisers (Mina Cikara and Fiery Cushman at Harvard University; Iyad Rahwan at Max Planck Institute for Human Development) who patiently supported me spending hundreds (?) of hours working on this package rather than what I was paid to do. 😁

Documentation and Examples

To see the detailed documentation for each function in the stable CRAN version of the package, see:

• Publication

• Presentation

• Vignettes

Summary of available plots

| Function | Plot | Description | |:---|:---|:---| | ggbetweenstats() | violin plots | for comparisons between groups/conditions | | ggwithinstats() | violin plots | for comparisons within groups/conditions | | gghistostats() | histograms | for distribution about numeric variable | | ggdotplotstats() | dot plots/charts | for distribution about labeled numeric variable | | ggscatterstats() | scatterplots | for correlation between two variables | | ggcorrmat() | correlation matrices | for correlations between multiple variables | | ggpiestats() | pie charts | for categorical data | | ggbarstats() | bar charts | for categorical data | | ggcoefstats() | dot-and-whisker plots | for regression models and meta-analysis |

In addition to these basic plots, {ggstatsplot} also provides grouped_ versions (see below) that makes it easy to repeat the same analysis for any grouping variable.

Summary of types of statistical analyses

The table below summarizes all the different types of analyses currently supported in this package-

| Functions | Description | Parametric | Non-parametric | Robust | Bayesian | |:---|:---|:---|:---|:---|:---| | ggbetweenstats() | Between group/condition comparisons | ✅ | ✅ | ✅ | ✅ | | ggwithinstats() | Within group/condition comparisons | ✅ | ✅ | ✅ | ✅ | | gghistostats(), ggdotplotstats() | Distribution of a numeric variable | ✅ | ✅ | ✅ | ✅ | | ggcorrmat | Correlation matrix | ✅ | ✅ | ✅ | ✅ | | ggscatterstats() | Correlation between two variables | ✅ | ✅ | ✅ | ✅ | | ggpiestats(), ggbarstats() | Association between categorical variables | ✅ | ✅ | ❌ | ✅ | | ggpiestats(), ggbarstats() | Equal proportions for categorical variable levels | ✅ | ✅ | ❌ | ✅ | | ggcoefstats() | Regression model coefficients | ✅ | ✅ | ✅ | ✅ | | ggcoefstats() | Random-effects meta-analysis | ✅ | ❌ | ✅ | ✅ |

Summary of Bayesian analysis

| Analysis | Hypothesis testing | Estimation | |:-----------------------------|:-------------------|:-----------| | (one/two-sample) t-test | ✅ | ✅ | | one-way ANOVA | ✅ | ✅ | | correlation | ✅ | ✅ | | (unpaired) contingency table | ✅ | ✅ | | (paired) contingency table | ✅ | ❌ | | random-effects meta-analysis | ✅ | ✅ |

Statistical reporting

For all statistical tests reported in the plots, the default template abides by the gold standard for statistical reporting. For example, here are results from Yuen’s test for trimmed means (robust t-test):

<img src="man/figures/stats_reporting_format.png" alt="Example of statistical reporting format showing Yuen's test results with test statistic, degrees of freedom, p-value, effect size, and confidence interval" align="center" />

Summary of statistical tests and effect sizes

Statistical analysis is carried out by {statsExpressions} package, and thus a summary table of all the statistical tests currently supported across various functions can be found in article for that package: https://www.indrapatil.com/statsExpressions/articles/stats_details.html

Primary functions

ggbetweenstats()

This function creates either a violin plot, a box plot, or a mix of two for between-group or between-condition comparisons with results from statistical tests in the subtitle. The simplest function call looks like this-

set.seed(123)

ggbetweenstats(
  data  = iris,
  x     = Species,
  y     = Sepal.Length,
  title = "Distribution of sepal length across Iris species"
)

<img src="man/figures/README-ggbetweenstats1-1.png" alt="Violin plot with boxplot overlay showing distribution of sepal length across three Iris species with statistical test results" width="100%" />

Defaults return<br>

✅ raw data + distributions <br> ✅ descriptive statistics <br> ✅ inferential statistics <br> ✅ effect size + CIs <br> ✅ pairwise comparisons <br> ✅ Bayesian hypothesis-testing <br> ✅ Bayesian estimation <br>

A number of other arguments can be specified to make this plot even more informative or change some of the default options. Additionally, there is also a grouped_ variant of this function that makes it easy to repeat the same operation across a single grouping variable:

set.seed(123)

grouped_ggbetweenstats(
  data             = dplyr::filter(movies_long, genre %in% c("Action", "Comedy")),
  x                = mpaa,
  y                = length,
  grouping.var     = genre,
  ggsignif.args    = list(textsize = 4, tip_length = 0.01),
  p.adjust.method  = "bonferroni",
  palette          = "ggsci::default_jama",
  plotgrid.args    = list(nrow = 1),
  annotation.args  = list(title = "Differences in movie length by mpaa ratings for different genres")
)

<img src="man/figures/README-ggbetweenstats2-1.png" alt="Grouped violin plots comparing movie length by MPAA rating for Action and Comedy genres with statistical annotations" width="100%" />

Details about underlying functions used to create graphics and statistical tests carried out can be found in the function documentation: https://www.indrapatil.com/ggstatsplot/reference/ggbetweenstats.html

For more, also read the following vi