Helper function for `ggstatsplot::ggbarstats`

to apply this function across
multiple levels of a given factor and combining the resulting plots using
`ggstatsplot::combine_plots`

.

## Arguments

- data
A dataframe (or a tibble) from which variables specified are to be taken. Other data types (e.g., matrix,table, array, etc.) will

**not**be accepted.- ...
Arguments passed on to

`ggbarstats`

`xlab`

Custom text for the

`x`

axis label (Default:`NULL`

, which will cause the`x`

axis label to be the`x`

variable).`ylab`

Custom text for the

`y`

axis label (Default:`NULL`

).`x`

The variable to use as the

**rows**in the contingency table. Please note that if there are empty factor levels in your variable, they will be dropped.`y`

The variable to use as the

**columns**in the contingency table. Please note that if there are empty factor levels in your variable, they will be dropped. Default is`NULL`

. If`NULL`

, one-sample proportion test (a goodness of fit test) will be run for the`x`

variable. Otherwise an appropriate association test will be run. This argument can not be`NULL`

for`ggbarstats`

function.`counts`

A string naming a variable in data containing counts, or

`NULL`

if each row represents a single observation.`type`

A character specifying the type of statistical approach:

`"parametric"`

`"nonparametric"`

`"robust"`

`"bayes"`

You can specify just the initial letter.

`paired`

Logical indicating whether data came from a within-subjects or repeated measures design study (Default:

`FALSE`

). If`TRUE`

, McNemar's test expression will be returned. If`FALSE`

, Pearson's chi-square test will be returned.`results.subtitle`

Decides whether the results of statistical tests are to be displayed as a subtitle (Default:

`TRUE`

). If set to`FALSE`

, only the plot will be returned.`label`

Character decides what information needs to be displayed on the label in each pie slice. Possible options are

`"percentage"`

(default),`"counts"`

,`"both"`

.`label.args`

Additional aesthetic arguments that will be passed to

`geom_label`

.`k`

Number of digits after decimal point (should be an integer) (Default:

`k = 2L`

).`proportion.test`

Decides whether proportion test for

`x`

variable is to be carried out for each level of`y`

. Defaults to`results.subtitle`

. In`ggbarstats`

, only*p*-values from this test will be displayed.`perc.k`

Numeric that decides number of decimal places for percentage labels (Default:

`0L`

).`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`

).`ratio`

A vector of proportions: the expected proportions for the proportion test (should sum to 1). Default is

`NULL`

, which means the null is equal theoretical proportions across the levels of the nominal variable. This means if there are two levels this will be`ratio = c(0.5,0.5)`

or if there are four levels this will be`ratio = c(0.25,0.25,0.25,0.25)`

, etc.`conf.level`

Scalar between

`0`

and`1`

. If unspecified, the defaults return`95%`

confidence/credible intervals (`0.95`

).`sampling.plan`

Character describing the sampling plan. Possible options are

`"indepMulti"`

(independent multinomial; default),`"poisson"`

,`"jointMulti"`

(joint multinomial),`"hypergeom"`

(hypergeometric). For more, see`?BayesFactor::contingencyTableBF()`

.`fixed.margin`

For the independent multinomial sampling plan, which margin is fixed (

`"rows"`

or`"cols"`

). Defaults to`"rows"`

.`prior.concentration`

Specifies the prior concentration parameter, set to

`1`

by default. It indexes the expected deviation from the null hypothesis under the alternative, and corresponds to Gunel and Dickey's (1974)`"a"`

parameter.`subtitle`

The text for the plot subtitle. Will work only if

`results.subtitle = FALSE`

.`caption`

The text for the plot caption.

`legend.title`

Title text for the legend.

`ggtheme`

A

`{ggplot2}`

theme. Default value is`ggstatsplot::theme_ggstatsplot()`

. Any of the`{ggplot2}`

themes (e.g.,`theme_bw()`

), or themes from extension packages are allowed (e.g.,`ggthemes::theme_fivethirtyeight()`

,`hrbrthemes::theme_ipsum_ps()`

, etc.).`package`

Name of the package from which the given palette is to be extracted. The available palettes and packages can be checked by running

`View(paletteer::palettes_d_names)`

.`palette`

Name of the package from which the given palette is to be extracted. The available palettes and packages can be checked by running

`View(paletteer::palettes_d_names)`

.`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.

- grouping.var
A single grouping variable.

- output
Character that describes what is to be returned: can be

`"plot"`

(default) or`"subtitle"`

or`"caption"`

. Setting this to`"subtitle"`

will return the expression containing statistical results. If you have set`results.subtitle = FALSE`

, then this will return a`NULL`

. Setting this to`"caption"`

will return the expression containing details about Bayes Factor analysis, but valid only when`type = "parametric"`

and`bf.message = TRUE`

, otherwise this will return a`NULL`

.- 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`

.

## Details

For details, see: https://indrajeetpatil.github.io/ggstatsplot/articles/web_only/ggpiestats.html

## Examples

```
# \donttest{
# for reproducibility
set.seed(123)
library(ggstatsplot)
library(dplyr, warn.conflicts = FALSE)
# let's create a smaller dataframe
diamonds_short <- ggplot2::diamonds %>%
filter(cut %in% c("Very Good", "Ideal")) %>%
filter(clarity %in% c("SI1", "SI2", "VS1", "VS2")) %>%
sample_frac(size = 0.05)
# plot
grouped_ggbarstats(
data = diamonds_short,
x = color,
y = clarity,
grouping.var = cut,
plotgrid.args = list(nrow = 2)
)
# }
```