Package {statsExpressions}

Type:	Package
Title:	Tidy Dataframes and Expressions with Statistical Details
Version:	2.1.2
Maintainer:	Indrajeet Patil <patilindrajeet.science@gmail.com>
Description:	Utilities for producing dataframes with rich details for the most common types of statistical approaches and tests: parametric, nonparametric, robust, and Bayesian t-test, one-way ANOVA, correlation analyses, contingency table analyses, and meta-analyses. The functions are pipe-friendly and provide a consistent syntax to work with tidy data. These dataframes additionally contain expressions with statistical details, and can be used in graphing packages. This package also forms the statistical processing backend for 'ggstatsplot'. References: Patil (2021) <doi:10.21105/joss.03236>.
License:	MIT + file LICENSE
URL:	https://www.indrapatil.com/statsExpressions/, https://github.com/IndrajeetPatil/statsExpressions
BugReports:	https://github.com/IndrajeetPatil/statsExpressions/issues
Depends:	R (≥ 4.5.0), stats
Imports:	afex (≥ 1.5-1), BayesFactor (≥ 0.9.12-4.8), bayestestR (≥ 0.19.0), correlation (≥ 0.8.8), datawizard (≥ 1.4.0), dplyr (≥ 1.2.1), effectsize (≥ 1.0.3), glue (≥ 1.8.1), insight (≥ 1.5.4), parameters (≥ 0.29.3), performance (≥ 0.18.2), PMCMRplus (≥ 1.9.12), purrr (≥ 1.2.2), rlang (≥ 1.3.0), rstantools (≥ 2.7.1), tidyr (≥ 1.3.2), withr (≥ 3.0.3), WRS2 (≥ 1.1-7)
Suggests:	ggplot2 (≥ 4.0.3), knitr (≥ 1.52), metaBMA (≥ 0.6.9), metafor (≥ 5.2-1), metaplus (≥ 1.0-10), patrick (≥ 0.3.1), rmarkdown (≥ 2.32), survival, testthat (≥ 3.3.2), utils
VignetteBuilder:	knitr
Config/Needs/check:	anthonynorth/roxyglobals, any::patrick
Config/roxygen2/version:	8.1.1
Config/roxyglobals/unique:	TRUE
Config/testthat/edition:	3
Config/testthat/parallel:	true
Encoding:	UTF-8
Language:	en-US
LazyData:	true
NeedsCompilation:	no
Packaged:	2026-10-09 09:02:42 UTC; runner
Author:	Indrajeet Patil [cre, aut, cph]
Repository:	CRAN
Date/Publication:	2026-10-09 10:10:02 UTC

statsExpressions: Tidy Dataframes and Expressions with Statistical Details

Description

The {statsExpressions} package has two key aims:

• to provide a consistent syntax to do statistical analysis with tidy data (in pipe-friendly manner),

• to provide statistical expressions (pre-formatted in-text statistical results) for plotting functions.

Statistical packages exhibit substantial diversity in terms of their syntax and expected input type. This can make it difficult to switch from one statistical approach to another. For example, some functions expect vectors as inputs, while others expect dataframes. Depending on whether it is a repeated measures design or not, different functions might expect data to be in wide or long format. Some functions can internally omit missing values, while other functions error in their presence. Furthermore, if someone wishes to utilize the objects returned by these packages downstream in their workflow, this is not straightforward either because even functions from the same package can return a list, a matrix, an array, a dataframe, etc., depending on the function.

This is where {statsExpressions} comes in: It can be thought of as a unified portal through which most of the functionality in these underlying packages can be accessed, with a simpler interface and no requirement to change data format.

This package forms the statistical processing backend for ggstatsplot package.

For more documentation, see the dedicated website.

Details

statsExpressions

Author(s)

Maintainer: Indrajeet Patil patilindrajeet.science@gmail.com (ORCID) [copyright holder]

Authors:

• Indrajeet Patil patilindrajeet.science@gmail.com (ORCID) [copyright holder]

See Also

Useful links:

• https://www.indrapatil.com/statsExpressions/

• https://github.com/IndrajeetPatil/statsExpressions

• Report bugs at https://github.com/IndrajeetPatil/statsExpressions/issues

Template for expressions with statistical details

Description

Creates an expression from a data frame containing statistical details. Ideally, this data frame would come from having run tidy_model_parameters() on your model object.

This function is currently not stable and should not be used outside of this package context.

Usage

add_expression_col(
  data,
  paired = FALSE,
  statistic.text = NULL,
  effsize.text = NULL,
  prior.type = NULL,
  n = NULL,
  n.text = ifelse(paired, list(quote(italic("n")["pairs"])),
    list(quote(italic("n")["obs"]))),
  digits = 2L,
  digits.df = 0L,
  digits.df.error = digits.df,
  ...
)

Arguments

Citation

Patil, I., (2021). statsExpressions: R Package for Tidy Dataframes and Expressions with Statistical Details. Journal of Open Source Software, 6(61), 3236, https://doi.org/10.21105/joss.03236

Examples

set.seed(123)

# creating a data frame with stats results
stats_df <- cbind.data.frame(
  statistic  = 5.494,
  df         = 29.234,
  p.value    = 0.00001,
  estimate   = -1.980,
  conf.level = 0.95,
  conf.low   = -2.873,
  conf.high  = -1.088,
  method     = "Student's t-test"
)

# expression for *t*-statistic with Cohen's *d* as effect size
# note that the plotmath expressions need to be quoted
add_expression_col(
  data           = stats_df,
  statistic.text = list(quote(italic("t"))),
  effsize.text   = list(quote(italic("d"))),
  n              = 32L,
  n.text         = list(quote(italic("n")["no.obs"])),
  digits         = 3L,
  digits.df      = 3L
)

Tidy version of the "Bugs" dataset.

Description

Tidy version of the "Bugs" dataset.

Usage

bugs_long

Format

A data frame with 372 rows and 6 variables

• subject. Dummy identity number for each participant.

• gender. Participant's gender (Female, Male).

• region. Region of the world the participant was from.

• education. Level of education.

• condition. Condition of the experiment the participant gave rating for (LDLF: low disgustingness and low frighteningness; LDHF: low disgustingness and high frighteningness; HDLF: high disgustingness and low frighteningness; HDHF: high disgustingness and high frighteningness).

• desire. The desire to kill an arthropod was indicated on a scale from 0 to 10.

Details

This data set, "Bugs", provides the extent to which men and women want to kill arthropods that vary in frighteningness (low, high) and disgustingness (low, high). Each participant rates their attitudes towards all arthropods. Subset of the data reported by Ryan et al. (2013).

References

Ryan, R. S., Wilde, M., & Crist, S. (2013). Compared to a small, supervised lab experiment, a large, unsupervised web-based experiment on a previously unknown effect has benefits that outweigh its potential costs. Computers in Human Behavior, 29(4), 1295-1301.

Examples

dim(bugs_long)
head(bugs_long)
dplyr::glimpse(bugs_long)

Data frame and expression for distribution properties

Description

Parametric, non-parametric, robust, and Bayesian measures of centrality.

Usage

centrality_description(
  data,
  x,
  y,
  type = "parametric",
  conf.level = 0.95,
  tr = 0.2,
  digits = 2L,
  ...
)

Arguments

Details

This function describes a distribution for y variable for each level of the grouping variable in x by a set of indices (e.g., measures of centrality, dispersion, range, skewness, kurtosis, etc.). It additionally returns an expression containing a specified centrality measure. The function internally relies on datawizard::describe_distribution() function.

Value

The returned object is a tibble data frame with the additional class "statsExpressions". Unlike the hypothesis-testing functions, this one returns one row per level of the grouping variable x, describing the distribution of y within that level. The columns are:

• the grouping variable (named after x, e.g. Species)

• the requested centrality estimate (named after y, e.g. Sepal.Length): the mean (type = "parametric"), median ("nonparametric"), trimmed mean ("robust"), or MAP estimate ("bayes")

• std.dev: standard deviation (for "parametric" and "robust")

• mad: median absolute deviation (for "nonparametric")

• iqr: interquartile range

• conf.low, conf.high: bounds of the confidence/credible interval for the centrality estimate

• min, max: minimum and maximum values

• skewness, kurtosis: shape statistics of the distribution

• n.obs: number of non-missing observations

• missing.obs: number of missing observations

• expression: a list-column of pre-formatted plotmath expressions (each element is a language object, not a character string) containing the centrality estimate, ready to be used in {ggplot2}

• n.expression: a label combining the group name and its sample size (e.g. "setosa\n(n = 50)"), useful as an axis or facet label

The exact dispersion column depends on the type of analysis (std.dev vs mad; neither is returned for "bayes"), and datawizard::describe_distribution() is used internally to compute these indices.

For more examples, see the data frame output vignette and the Return value schema article.

Centrality measures

The table below provides summary about:

• statistical test carried out for inferential statistics

• type of effect size estimate and a measure of uncertainty for this estimate

• functions used internally to compute these details

Citation

Patil, I., (2021). statsExpressions: R Package for Tidy Dataframes and Expressions with Statistical Details. Journal of Open Source Software, 6(61), 3236, https://doi.org/10.21105/joss.03236

Examples

# for reproducibility
set.seed(123)

# ----------------------- parametric -----------------------

centrality_description(iris, Species, Sepal.Length, type = "parametric")

# ----------------------- non-parametric -------------------

centrality_description(mtcars, am, wt, type = "nonparametric")

# ----------------------- robust ---------------------------

centrality_description(ToothGrowth, supp, len, type = "robust")

# ----------------------- Bayesian -------------------------

centrality_description(sleep, group, extra, type = "bayes")

Contingency table analyses

Description

Parametric and Bayesian one-way and two-way contingency table analyses.

Usage

contingency_table(
  data,
  x,
  y = NULL,
  paired = FALSE,
  type = "parametric",
  counts = NULL,
  ratio = NULL,
  alternative = "two.sided",
  digits = 2L,
  conf.level = 0.95,
  sampling.plan = "indepMulti",
  fixed.margin = "rows",
  prior.concentration = 1,
  ...
)

Arguments

Value

The returned object is a tibble data frame with the additional class "statsExpressions". The exact set of columns depends on the test and, for functions that accept a type argument, on the chosen analysis (parametric, non-parametric, robust, or Bayesian). Any given call therefore returns some (not all) of the columns below.

Hypothesis testing

• statistic: the numeric value of a statistic

• df: the numeric value of a parameter being modeled (often degrees of freedom for the test)

• df.error and df: relevant only if the statistic in question has two degrees of freedom (e.g. anova)

• p.value: the p-value associated with the observed statistic (two-sided unless a one-sided alternative is requested, where supported)

• method: the name of the inferential statistical test

Effect size estimation

• effectsize: the name of the effect size

• estimate: estimated value of the effect size

• conf.level: the coverage level of the confidence/credible interval (e.g. 0.95); the interval itself spans conf.low to conf.high

• conf.low: lower bound for the effect size estimate

• conf.high: upper bound for the effect size estimate

• conf.method: method used to compute the confidence/credible interval

• conf.distribution: statistical distribution for the effect

Bayesian analysis (only when type = "bayes")

• bf10: Bayes factor for the alternative hypothesis relative to the null

• log_e_bf10: natural logarithm of the Bayes factor (present for most, but not all, Bayesian analyses)

• prior.distribution, prior.scale, prior.location: prior specification used to compute the Bayes factor and posterior estimates

Pairwise comparisons (for pairwise_comparisons() and pairwise_contingency_table())

• group1, group2: the two levels being compared

• p.adjust.method: the adjustment method used for multiple comparisons

• p.value.adj: the adjusted p-value; returned by pairwise_contingency_table(). Note that pairwise_comparisons() instead folds the adjusted value into p.value (and does not return a separate p.value.adj column)

Common columns

• n.obs: number of observations

• expression: a list-column of pre-formatted plotmath expressions; each element is a language object (not a character string) containing the statistical details, ready to be used in {ggplot2} (e.g. in labs() or annotate())

For a per-function, column-by-column breakdown of the output (and an explanation of the internal add_expression_col() engine that builds the expression column), see the Return value schema article. For more examples, see the data frame output vignette.

Contingency table analyses

The table below provides summary about:

• statistical test carried out for inferential statistics

• type of effect size estimate and a measure of uncertainty for this estimate

• functions used internally to compute these details

There are no dedicated non-parametric or robust contingency table analyses. type = "nonparametric" and type = "robust" are accepted, but run the same frequentist tests as type = "parametric" (the "Parametric/Non-parametric" rows below).

two-way table

Hypothesis testing

Effect size estimation

Paired Bayesian analysis is not supported: for a two-way table with type = "bayes", the paired argument is ignored and the unpaired Bayesian test is run instead.

one-way table

Hypothesis testing

Effect size estimation

Examples

#### -------------------- association test ------------------------ ####

# ------------------------ frequentist ---------------------------------

# unpaired

set.seed(123)
contingency_table(
  data = mtcars,
  x = am,
  y = vs,
  paired = FALSE
)

# paired

paired_data <- dplyr::tibble(
  response_before = structure(
    c(1L, 2L, 1L, 2L),
    levels = c("no", "yes"),
    class = "factor"
  ),
  response_after = structure(
    c(1L, 1L, 2L, 2L),
    levels = c("no", "yes"),
    class = "factor"
  ),
  Freq = c(65L, 25L, 5L, 5L)
)

set.seed(123)
contingency_table(
  data = paired_data,
  x = response_before,
  y = response_after,
  paired = TRUE,
  counts = Freq
)

# ------------------------ Bayesian -------------------------------------

# unpaired

set.seed(123)
contingency_table(
  data = mtcars,
  x = am,
  y = vs,
  paired = FALSE,
  type = "bayes"
)

# paired

set.seed(123)
contingency_table(
  data = paired_data,
  x = response_before,
  y = response_after,
  paired = TRUE,
  counts = Freq,
  type = "bayes"
)

#### -------------------- goodness-of-fit test -------------------- ####

# ------------------------ frequentist ---------------------------------

set.seed(123)
contingency_table(
  data = as.data.frame(HairEyeColor),
  x = Eye,
  counts = Freq
)

# ------------------------ Bayesian -------------------------------------

set.seed(123)
contingency_table(
  data = as.data.frame(HairEyeColor),
  x = Eye,
  counts = Freq,
  ratio = c(0.2, 0.2, 0.3, 0.3),
  type = "bayes"
)

Correlation analyses

Description

Parametric, non-parametric, robust, and Bayesian correlation test.

Usage

corr_test(
  data,
  x,
  y,
  type = "parametric",
  digits = 2L,
  conf.level = 0.95,
  tr = 0.2,
  bf.prior = 0.707,
  ...
)

Arguments

Value

The returned object is a tibble data frame with the additional class "statsExpressions". The exact set of columns depends on the test and, for functions that accept a type argument, on the chosen analysis (parametric, non-parametric, robust, or Bayesian). Any given call therefore returns some (not all) of the columns below.

Hypothesis testing

• statistic: the numeric value of a statistic

• df: the numeric value of a parameter being modeled (often degrees of freedom for the test)

• df.error and df: relevant only if the statistic in question has two degrees of freedom (e.g. anova)

• p.value: the p-value associated with the observed statistic (two-sided unless a one-sided alternative is requested, where supported)

• method: the name of the inferential statistical test

Effect size estimation

• effectsize: the name of the effect size

• estimate: estimated value of the effect size

• conf.level: the coverage level of the confidence/credible interval (e.g. 0.95); the interval itself spans conf.low to conf.high

• conf.low: lower bound for the effect size estimate

• conf.high: upper bound for the effect size estimate

• conf.method: method used to compute the confidence/credible interval

• conf.distribution: statistical distribution for the effect

Bayesian analysis (only when type = "bayes")

• bf10: Bayes factor for the alternative hypothesis relative to the null

• log_e_bf10: natural logarithm of the Bayes factor (present for most, but not all, Bayesian analyses)

• prior.distribution, prior.scale, prior.location: prior specification used to compute the Bayes factor and posterior estimates

Pairwise comparisons (for pairwise_comparisons() and pairwise_contingency_table())

• group1, group2: the two levels being compared

• p.adjust.method: the adjustment method used for multiple comparisons

• p.value.adj: the adjusted p-value; returned by pairwise_contingency_table(). Note that pairwise_comparisons() instead folds the adjusted value into p.value (and does not return a separate p.value.adj column)

Common columns

• n.obs: number of observations

• expression: a list-column of pre-formatted plotmath expressions; each element is a language object (not a character string) containing the statistical details, ready to be used in {ggplot2} (e.g. in labs() or annotate())

For a per-function, column-by-column breakdown of the output (and an explanation of the internal add_expression_col() engine that builds the expression column), see the Return value schema article. For more examples, see the data frame output vignette.

Correlation analyses

The table below provides summary about:

• statistical test carried out for inferential statistics

• type of effect size estimate and a measure of uncertainty for this estimate

• functions used internally to compute these details

Hypothesis testing and Effect size estimation

Citation

Patil, I., (2021). statsExpressions: R Package for Tidy Dataframes and Expressions with Statistical Details. Journal of Open Source Software, 6(61), 3236, https://doi.org/10.21105/joss.03236

Examples

# for reproducibility
set.seed(123)

# ----------------------- parametric -----------------------

corr_test(mtcars, wt, mpg, type = "parametric")

# ----------------------- non-parametric -------------------

corr_test(mtcars, wt, mpg, type = "nonparametric")

# ----------------------- robust ---------------------------

corr_test(mtcars, wt, mpg, type = "robust")

# ----------------------- Bayesian -------------------------

corr_test(mtcars, wt, mpg, type = "bayes")

Switch the type of statistics.

Description

Relevant mostly for {ggstatsplot} and {statsExpressions} packages, where different statistical approaches are supported via this argument: parametric, non-parametric, robust, and Bayesian. This switch function converts strings entered by users to a common pattern for convenience.

stats_type_switch() is an alias of extract_stats_type().

Usage

extract_stats_type(type)

stats_type_switch(type)

Arguments

Value

A character vector of the same length as type, with values "parametric", "nonparametric", "robust", or "bayes".

Examples

extract_stats_type("p")
extract_stats_type("bf")
extract_stats_type(c("np", "robust", "Bayes"))

Edgar Anderson's Iris Data in long format.

Description

Edgar Anderson's Iris Data in long format.

Usage

iris_long

Format

A data frame with 600 rows and 6 variables

• id. Dummy identity number for each flower (150 flowers in total).

• Species. The species are Iris setosa, versicolor, and virginica.

• condition. Factor giving a detailed description of the attribute (Four levels: "Petal.Length", "Petal.Width", "Sepal.Length", "Sepal.Width").

• attribute. What attribute is being measured ("Sepal" or "Petal").

• measure. What aspect of the attribute is being measured ("Length" or "Width").

• value. Value of the measurement.

Details

This famous (Fisher's or Anderson's) iris data set gives the measurements in centimeters of the variables sepal length and width and petal length and width, respectively, for 50 flowers from each of 3 species of iris. The species are Iris setosa, versicolor, and virginica.

This is a modified dataset from {datasets} package.

Examples

dim(iris_long)
head(iris_long)
dplyr::glimpse(iris_long)

Convert long/tidy data frame to wide format

Description

This conversion is helpful mostly for repeated measures design, where removing NAs by participant can be a bit tedious.

Usage

long_to_wide_converter(
  data,
  x,
  y,
  subject.id = NULL,
  paired = TRUE,
  spread = TRUE,
  ...
)

Arguments

Value

A tibble with NAs removed while respecting the between-or-within-subjects nature of the dataset: for paired designs, a subject with a missing value in any condition is removed entirely, while for unpaired designs only the rows with missing values are removed. Rows are grouped by subject.id whenever it is supplied, so with paired = FALSE and a subject.id, a missing value still removes every row of that subject. The .rowid column contains the subject identifier (or an internal row identifier).

Citation

Patil, I., (2021). statsExpressions: R Package for Tidy Dataframes and Expressions with Statistical Details. Journal of Open Source Software, 6(61), 3236, https://doi.org/10.21105/joss.03236

Examples

# for reproducibility
library(statsExpressions)
set.seed(123)

# repeated measures design
long_to_wide_converter(
  bugs_long,
  condition,
  desire,
  subject.id = subject,
  paired = TRUE
)

# independent measures design
long_to_wide_converter(mtcars, cyl, wt, paired = FALSE)

Random-effects meta-analysis

Description

Parametric, robust, and Bayesian random-effects meta-analysis.

A non-parametric meta-analysis is not available, so type = "nonparametric" is not supported.

Usage

meta_analysis(
  data,
  type = "parametric",
  random = "mixture",
  digits = 2L,
  conf.level = 0.95,
  ...
)

Arguments

Value

The returned object is a tibble data frame with the additional class "statsExpressions". The exact set of columns depends on the test and, for functions that accept a type argument, on the chosen analysis (parametric, non-parametric, robust, or Bayesian). Any given call therefore returns some (not all) of the columns below.

Hypothesis testing

• statistic: the numeric value of a statistic

• df: the numeric value of a parameter being modeled (often degrees of freedom for the test)

• df.error and df: relevant only if the statistic in question has two degrees of freedom (e.g. anova)

• p.value: the p-value associated with the observed statistic (two-sided unless a one-sided alternative is requested, where supported)

• method: the name of the inferential statistical test

Effect size estimation

• effectsize: the name of the effect size

• estimate: estimated value of the effect size

• conf.level: the coverage level of the confidence/credible interval (e.g. 0.95); the interval itself spans conf.low to conf.high

• conf.low: lower bound for the effect size estimate

• conf.high: upper bound for the effect size estimate

• conf.method: method used to compute the confidence/credible interval

• conf.distribution: statistical distribution for the effect

Bayesian analysis (only when type = "bayes")

• bf10: Bayes factor for the alternative hypothesis relative to the null

• log_e_bf10: natural logarithm of the Bayes factor (present for most, but not all, Bayesian analyses)

• prior.distribution, prior.scale, prior.location: prior specification used to compute the Bayes factor and posterior estimates

Pairwise comparisons (for pairwise_comparisons() and pairwise_contingency_table())

• group1, group2: the two levels being compared

• p.adjust.method: the adjustment method used for multiple comparisons

• p.value.adj: the adjusted p-value; returned by pairwise_contingency_table(). Note that pairwise_comparisons() instead folds the adjusted value into p.value (and does not return a separate p.value.adj column)

Common columns

• n.obs: number of observations

• expression: a list-column of pre-formatted plotmath expressions; each element is a language object (not a character string) containing the statistical details, ready to be used in {ggplot2} (e.g. in labs() or annotate())

For a per-function, column-by-column breakdown of the output (and an explanation of the internal add_expression_col() engine that builds the expression column), see the Return value schema article. For more examples, see the data frame output vignette.

Random-effects meta-analysis

The table below provides summary about:

• statistical test carried out for inferential statistics

• type of effect size estimate and a measure of uncertainty for this estimate

• functions used internally to compute these details

Hypothesis testing and Effect size estimation

Citation

Patil, I., (2021). statsExpressions: R Package for Tidy Dataframes and Expressions with Statistical Details. Journal of Open Source Software, 6(61), 3236, https://doi.org/10.21105/joss.03236

Note

Important: The function assumes that you have already downloaded the needed package ({metafor}, {metaplus}, or {metaBMA}) for meta-analysis. If they are not available, you will be asked to install them.

Examples

set.seed(123)
library(statsExpressions)

# let's use `mag` dataset from `{metaplus}`
data(mag, package = "metaplus")
dat <- dplyr::rename(mag, estimate = yi, std.error = sei)

# ----------------------- parametric ----------------------------------------



meta_analysis(dat)



# ----------------------- robust --------------------------------------------

meta_analysis(dat, type = "robust", random = "normal")



# ----------------------- Bayesian ------------------------------------------

meta_analysis(dat, type = "bayes")

Movie information and user ratings from IMDB.

Description

Movie information and user ratings from IMDB.

Usage

movies_long

Format

A data frame with 1,579 rows and 8 variables

• title. Title of the movie.

• year. Year of release.

• budget. Total budget (if known) in US dollars

• length. Length in minutes.

• rating. Average IMDB user rating.

• votes. Number of IMDB users who rated this movie.

• mpaa. MPAA rating.

• genre. Genre of the movie ("Action", "Action Comedy", "Action Drama", "Animated", "Comedy", "Comedy Drama", "Drama", "Romance Drama", "RomCom").

Details

Modified dataset from {ggplot2movies} package.

Source

https://CRAN.R-project.org/package=ggplot2movies

Examples

dim(movies_long)
head(movies_long)
dplyr::glimpse(movies_long)

One-sample tests

Description

Parametric, non-parametric, robust, and Bayesian one-sample tests.

Usage

one_sample_test(
  data,
  x,
  type = "parametric",
  test.value = 0,
  alternative = "two.sided",
  digits = 2L,
  conf.level = 0.95,
  tr = 0.2,
  bf.prior = 0.707,
  effsize.type = "g",
  exact = FALSE,
  ...
)

Arguments

Value

The returned object is a tibble data frame with the additional class "statsExpressions". The exact set of columns depends on the test and, for functions that accept a type argument, on the chosen analysis (parametric, non-parametric, robust, or Bayesian). Any given call therefore returns some (not all) of the columns below.

Hypothesis testing

• statistic: the numeric value of a statistic

• df: the numeric value of a parameter being modeled (often degrees of freedom for the test)

• df.error and df: relevant only if the statistic in question has two degrees of freedom (e.g. anova)

• p.value: the p-value associated with the observed statistic (two-sided unless a one-sided alternative is requested, where supported)

• method: the name of the inferential statistical test

Effect size estimation

• effectsize: the name of the effect size

• estimate: estimated value of the effect size

• conf.level: the coverage level of the confidence/credible interval (e.g. 0.95); the interval itself spans conf.low to conf.high

• conf.low: lower bound for the effect size estimate

• conf.high: upper bound for the effect size estimate

• conf.method: method used to compute the confidence/credible interval

• conf.distribution: statistical distribution for the effect

Bayesian analysis (only when type = "bayes")

• bf10: Bayes factor for the alternative hypothesis relative to the null

• log_e_bf10: natural logarithm of the Bayes factor (present for most, but not all, Bayesian analyses)

• prior.distribution, prior.scale, prior.location: prior specification used to compute the Bayes factor and posterior estimates

Pairwise comparisons (for pairwise_comparisons() and pairwise_contingency_table())

• group1, group2: the two levels being compared

• p.adjust.method: the adjustment method used for multiple comparisons

• p.value.adj: the adjusted p-value; returned by pairwise_contingency_table(). Note that pairwise_comparisons() instead folds the adjusted value into p.value (and does not return a separate p.value.adj column)

Common columns

• n.obs: number of observations

• expression: a list-column of pre-formatted plotmath expressions; each element is a language object (not a character string) containing the statistical details, ready to be used in {ggplot2} (e.g. in labs() or annotate())

For a per-function, column-by-column breakdown of the output (and an explanation of the internal add_expression_col() engine that builds the expression column), see the Return value schema article. For more examples, see the data frame output vignette.

One-sample tests

The table below provides summary about:

• statistical test carried out for inferential statistics

• type of effect size estimate and a measure of uncertainty for this estimate

• functions used internally to compute these details

Hypothesis testing

Effect size estimation

Citation

Patil, I., (2021). statsExpressions: R Package for Tidy Dataframes and Expressions with Statistical Details. Journal of Open Source Software, 6(61), 3236, https://doi.org/10.21105/joss.03236

Examples

# for reproducibility
set.seed(123)

# ----------------------- parametric -----------------------

one_sample_test(mtcars, wt, test.value = 3)

# biased (Cohen's d) effect size
one_sample_test(mtcars, wt, test.value = 3, effsize.type = "d")

# ----------------------- non-parametric -------------------

one_sample_test(mtcars, wt, test.value = 3, type = "nonparametric")

# ----------------------- robust ---------------------------

one_sample_test(mtcars, wt, test.value = 3, type = "robust")

# ----------------------- Bayesian -------------------------

one_sample_test(mtcars, wt, test.value = 3, type = "bayes")

One-way analysis of variance (ANOVA)

Description

Parametric, non-parametric, robust, and Bayesian one-way ANOVA.

Usage

oneway_anova(
  data,
  x,
  y,
  subject.id = NULL,
  type = "parametric",
  paired = FALSE,
  digits = 2L,
  conf.level = 0.95,
  effsize.type = "omega",
  var.equal = FALSE,
  bf.prior = 0.707,
  tr = 0.2,
  nboot = 100L,
  ...
)

Arguments

Value

The returned object is a tibble data frame with the additional class "statsExpressions". The exact set of columns depends on the test and, for functions that accept a type argument, on the chosen analysis (parametric, non-parametric, robust, or Bayesian). Any given call therefore returns some (not all) of the columns below.

Hypothesis testing

• statistic: the numeric value of a statistic

• df: the numeric value of a parameter being modeled (often degrees of freedom for the test)

• df.error and df: relevant only if the statistic in question has two degrees of freedom (e.g. anova)

• p.value: the p-value associated with the observed statistic (two-sided unless a one-sided alternative is requested, where supported)

• method: the name of the inferential statistical test

Effect size estimation

• effectsize: the name of the effect size

• estimate: estimated value of the effect size

• conf.level: the coverage level of the confidence/credible interval (e.g. 0.95); the interval itself spans conf.low to conf.high

• conf.low: lower bound for the effect size estimate

• conf.high: upper bound for the effect size estimate

• conf.method: method used to compute the confidence/credible interval

• conf.distribution: statistical distribution for the effect

Bayesian analysis (only when type = "bayes")

• bf10: Bayes factor for the alternative hypothesis relative to the null

• log_e_bf10: natural logarithm of the Bayes factor (present for most, but not all, Bayesian analyses)

• prior.distribution, prior.scale, prior.location: prior specification used to compute the Bayes factor and posterior estimates

Pairwise comparisons (for pairwise_comparisons() and pairwise_contingency_table())

• group1, group2: the two levels being compared

• p.adjust.method: the adjustment method used for multiple comparisons

• p.value.adj: the adjusted p-value; returned by pairwise_contingency_table(). Note that pairwise_comparisons() instead folds the adjusted value into p.value (and does not return a separate p.value.adj column)

Common columns

• n.obs: number of observations

• expression: a list-column of pre-formatted plotmath expressions; each element is a language object (not a character string) containing the statistical details, ready to be used in {ggplot2} (e.g. in labs() or annotate())

For a per-function, column-by-column breakdown of the output (and an explanation of the internal add_expression_col() engine that builds the expression column), see the Return value schema article. For more examples, see the data frame output vignette.

One-way ANOVA

The table below provides summary about:

• statistical test carried out for inferential statistics

• type of effect size estimate and a measure of uncertainty for this estimate

• functions used internally to compute these details

between-subjects

Hypothesis testing

Effect size estimation

within-subjects

Data requirement: Repeated measures tests assume a complete design with exactly one observation per subject per condition. If your data has multiple trials per cell, aggregate first (e.g., take the mean). Verify with table(data$subject, data$condition) — every cell should equal 1.

Hypothesis testing

Effect size estimation

Citation

Patil, I., (2021). statsExpressions: R Package for Tidy Dataframes and Expressions with Statistical Details. Journal of Open Source Software, 6(61), 3236, https://doi.org/10.21105/joss.03236

Examples

# for reproducibility
set.seed(123)
library(statsExpressions)

# ----------------------- parametric -------------------------------------

# between-subjects
oneway_anova(
  data = mtcars,
  x    = cyl,
  y    = wt
)

# biased (partial eta-squared) effect size
oneway_anova(
  data         = mtcars,
  x            = cyl,
  y            = wt,
  effsize.type = "eta"
)

# within-subjects design
oneway_anova(
  data       = iris_long,
  x          = condition,
  y          = value,
  subject.id = id,
  paired     = TRUE
)

# ----------------------- non-parametric ----------------------------------

# between-subjects
oneway_anova(
  data = mtcars,
  x    = cyl,
  y    = wt,
  type = "np"
)

# within-subjects design
oneway_anova(
  data       = iris_long,
  x          = condition,
  y          = value,
  subject.id = id,
  paired     = TRUE,
  type       = "np"
)

# ----------------------- robust -------------------------------------

# between-subjects
oneway_anova(
  data = mtcars,
  x    = cyl,
  y    = wt,
  type = "r"
)

# within-subjects design
oneway_anova(
  data       = iris_long,
  x          = condition,
  y          = value,
  subject.id = id,
  paired     = TRUE,
  type       = "r"
)



# ----------------------- Bayesian -------------------------------------

# between-subjects
oneway_anova(
  data = mtcars,
  x    = cyl,
  y    = wt,
  type = "bayes"
)

# within-subjects design
oneway_anova(
  data       = iris_long,
  x          = condition,
  y          = value,
  subject.id = id,
  paired     = TRUE,
  type       = "bayes"
)

Multiple pairwise comparison for one-way design

Description

Calculate parametric, non-parametric, robust, and Bayes Factor pairwise comparisons between group levels with corrections for multiple testing.

Usage

pairwise_comparisons(
  data,
  x,
  y,
  subject.id = NULL,
  type = "parametric",
  paired = FALSE,
  var.equal = FALSE,
  tr = 0.2,
  bf.prior = 0.707,
  p.adjust.method = "holm",
  digits = 2L,
  exact = FALSE,
  ...
)

Arguments

Value

The returned object is a tibble data frame with the additional class "statsExpressions". The exact set of columns depends on the test and, for functions that accept a type argument, on the chosen analysis (parametric, non-parametric, robust, or Bayesian). Any given call therefore returns some (not all) of the columns below.

Hypothesis testing

• statistic: the numeric value of a statistic

• df: the numeric value of a parameter being modeled (often degrees of freedom for the test)

• df.error and df: relevant only if the statistic in question has two degrees of freedom (e.g. anova)

• p.value: the p-value associated with the observed statistic (two-sided unless a one-sided alternative is requested, where supported)

• method: the name of the inferential statistical test

Effect size estimation

• effectsize: the name of the effect size

• estimate: estimated value of the effect size

• conf.level: the coverage level of the confidence/credible interval (e.g. 0.95); the interval itself spans conf.low to conf.high

• conf.low: lower bound for the effect size estimate

• conf.high: upper bound for the effect size estimate

• conf.method: method used to compute the confidence/credible interval

• conf.distribution: statistical distribution for the effect

Bayesian analysis (only when type = "bayes")

• bf10: Bayes factor for the alternative hypothesis relative to the null

• log_e_bf10: natural logarithm of the Bayes factor (present for most, but not all, Bayesian analyses)

• prior.distribution, prior.scale, prior.location: prior specification used to compute the Bayes factor and posterior estimates

Pairwise comparisons (for pairwise_comparisons() and pairwise_contingency_table())

• group1, group2: the two levels being compared

• p.adjust.method: the adjustment method used for multiple comparisons

• p.value.adj: the adjusted p-value; returned by pairwise_contingency_table(). Note that pairwise_comparisons() instead folds the adjusted value into p.value (and does not return a separate p.value.adj column)

Common columns

• n.obs: number of observations

• expression: a list-column of pre-formatted plotmath expressions; each element is a language object (not a character string) containing the statistical details, ready to be used in {ggplot2} (e.g. in labs() or annotate())

For a per-function, column-by-column breakdown of the output (and an explanation of the internal add_expression_col() engine that builds the expression column), see the Return value schema article. For more examples, see the data frame output vignette.

Pairwise comparison tests

The table below provides summary about:

• statistical test carried out for inferential statistics

• type of effect size estimate and a measure of uncertainty for this estimate

• functions used internally to compute these details

between-subjects

Hypothesis testing

Effect size estimation

Not supported.

within-subjects

Data requirement: Paired pairwise tests assume exactly one observation per subject per condition. If your data has multiple trials per cell, aggregate first (e.g., take the mean).

Hypothesis testing

Effect size estimation

Not supported.

Citation

Patil, I., (2021). statsExpressions: R Package for Tidy Dataframes and Expressions with Statistical Details. Journal of Open Source Software, 6(61), 3236, https://doi.org/10.21105/joss.03236

References

For more, see: https://www.indrapatil.com/ggstatsplot/articles/web_only/pairwise.html

Examples

# for reproducibility
set.seed(123)
library(statsExpressions)

#------------------- between-subjects design ----------------------------

# parametric
# if `var.equal = TRUE`, then Student's t-test will be run
pairwise_comparisons(
  data            = mtcars,
  x               = cyl,
  y               = wt,
  type            = "parametric",
  var.equal       = TRUE,
  paired          = FALSE,
  p.adjust.method = "none"
)

# if `var.equal = FALSE`, then Games-Howell test will be run
pairwise_comparisons(
  data            = mtcars,
  x               = cyl,
  y               = wt,
  type            = "parametric",
  var.equal       = FALSE,
  paired          = FALSE,
  p.adjust.method = "bonferroni"
)

# non-parametric (Dunn test)
pairwise_comparisons(
  data            = mtcars,
  x               = cyl,
  y               = wt,
  type            = "nonparametric",
  paired          = FALSE,
  p.adjust.method = "none"
)

# robust (Yuen's trimmed means *t*-test)
pairwise_comparisons(
  data            = mtcars,
  x               = cyl,
  y               = wt,
  type            = "robust",
  paired          = FALSE,
  p.adjust.method = "fdr"
)

# Bayes Factor (Student's *t*-test)
pairwise_comparisons(
  data   = mtcars,
  x      = cyl,
  y      = wt,
  type   = "bayes",
  paired = FALSE
)

#------------------- within-subjects design ----------------------------

# parametric (Student's *t*-test)
pairwise_comparisons(
  data            = bugs_long,
  x               = condition,
  y               = desire,
  subject.id      = subject,
  type            = "parametric",
  paired          = TRUE,
  p.adjust.method = "BH"
)

# non-parametric (Durbin-Conover test)
pairwise_comparisons(
  data            = bugs_long,
  x               = condition,
  y               = desire,
  subject.id      = subject,
  type            = "nonparametric",
  paired          = TRUE,
  p.adjust.method = "BY"
)

# robust (Yuen's trimmed means t-test)
pairwise_comparisons(
  data            = bugs_long,
  x               = condition,
  y               = desire,
  subject.id      = subject,
  type            = "robust",
  paired          = TRUE,
  p.adjust.method = "hommel"
)

# Bayes Factor (Student's *t*-test)
pairwise_comparisons(
  data       = bugs_long,
  x          = condition,
  y          = desire,
  subject.id = subject,
  type       = "bayes",
  paired     = TRUE
)

Pairwise contingency table analyses

Description

Pairwise Fisher's exact tests as post hoc tests for contingency table analyses, with effect sizes (Cramer's V) and p-value adjustment for multiple comparisons.

Usage

pairwise_contingency_table(
  data,
  x,
  y,
  counts = NULL,
  p.adjust.method = "holm",
  digits = 2L,
  conf.level = 0.95,
  alternative = "two.sided",
  ...
)

Arguments

Value

The returned object is a tibble data frame with the additional class "statsExpressions". The exact set of columns depends on the test and, for functions that accept a type argument, on the chosen analysis (parametric, non-parametric, robust, or Bayesian). Any given call therefore returns some (not all) of the columns below.

Hypothesis testing

• statistic: the numeric value of a statistic

• df: the numeric value of a parameter being modeled (often degrees of freedom for the test)

• df.error and df: relevant only if the statistic in question has two degrees of freedom (e.g. anova)

• p.value: the p-value associated with the observed statistic (two-sided unless a one-sided alternative is requested, where supported)

• method: the name of the inferential statistical test

Effect size estimation

• effectsize: the name of the effect size

• estimate: estimated value of the effect size

• conf.level: the coverage level of the confidence/credible interval (e.g. 0.95); the interval itself spans conf.low to conf.high

• conf.low: lower bound for the effect size estimate

• conf.high: upper bound for the effect size estimate

• conf.method: method used to compute the confidence/credible interval

• conf.distribution: statistical distribution for the effect

Bayesian analysis (only when type = "bayes")

• bf10: Bayes factor for the alternative hypothesis relative to the null

• log_e_bf10: natural logarithm of the Bayes factor (present for most, but not all, Bayesian analyses)

• prior.distribution, prior.scale, prior.location: prior specification used to compute the Bayes factor and posterior estimates

Pairwise comparisons (for pairwise_comparisons() and pairwise_contingency_table())

• group1, group2: the two levels being compared

• p.adjust.method: the adjustment method used for multiple comparisons

• p.value.adj: the adjusted p-value; returned by pairwise_contingency_table(). Note that pairwise_comparisons() instead folds the adjusted value into p.value (and does not return a separate p.value.adj column)

Common columns

• n.obs: number of observations

• expression: a list-column of pre-formatted plotmath expressions; each element is a language object (not a character string) containing the statistical details, ready to be used in {ggplot2} (e.g. in labs() or annotate())

For a per-function, column-by-column breakdown of the output (and an explanation of the internal add_expression_col() engine that builds the expression column), see the Return value schema article. For more examples, see the data frame output vignette.

Pairwise contingency table tests

The table below provides summary about:

• statistical test carried out for inferential statistics

• type of effect size estimate and a measure of uncertainty for this estimate

• functions used internally to compute these details

Hypothesis testing

Effect size estimation

Citation

Patil, I., (2021). statsExpressions: R Package for Tidy Dataframes and Expressions with Statistical Details. Journal of Open Source Software, 6(61), 3236, https://doi.org/10.21105/joss.03236

Examples

# for reproducibility
set.seed(123)
library(statsExpressions)

# pairwise Fisher's exact tests with Holm adjustment
pairwise_contingency_table(
  data = mtcars,
  x = cyl,
  y = am,
  p.adjust.method = "holm"
)

# with counts data and Bonferroni adjustment
pairwise_contingency_table(
  data = as.data.frame(Titanic),
  x = Class,
  y = Survived,
  counts = Freq,
  p.adjust.method = "bonferroni"
)

# no p-value adjustment
pairwise_contingency_table(
  data = mtcars,
  x = cyl,
  y = am,
  p.adjust.method = "none"
)

Expressions with statistics for tidy regression data frames

Description

Expressions with statistics for tidy regression data frames

Usage

tidy_model_expressions(
  data,
  statistic = NULL,
  digits = 2L,
  effsize.type = "omega",
  ...
)

Arguments

Details

When any of the necessary numeric column values (estimate, statistic, p.value) are missing, for these rows, a NULL is returned instead of an expression with empty strings.

Value

The input data frame (as a tibble) with an additional expression list-column.

Citation

Patil, I., (2021). statsExpressions: R Package for Tidy Dataframes and Expressions with Statistical Details. Journal of Open Source Software, 6(61), 3236, https://doi.org/10.21105/joss.03236

Examples

# setup
set.seed(123)
library(statsExpressions)

# extract a tidy data frame
df <- tidy_model_parameters(lm(wt ~ am * cyl, mtcars))

# create a column containing expression; the expression will depend on `statistic`
tidy_model_expressions(df, statistic = "t")
tidy_model_expressions(df, statistic = "z")
tidy_model_expressions(df, statistic = "chi")

# f-statistic (requires a data frame with `df`, `df.error`, and effect-size columns)
df_f <- tidy_model_parameters(
  aov(wt ~ cyl, mtcars),
  es_type = "omega",
  table_wide = TRUE
)
tidy_model_expressions(df_f, statistic = "f")
df_f_eta <- tidy_model_parameters(
  aov(wt ~ cyl, mtcars),
  es_type = "eta",
  table_wide = TRUE
)
tidy_model_expressions(df_f_eta, statistic = "f", effsize.type = "eta")

Convert {parameters} package output to {tidyverse} conventions

Description

Runs parameters::model_parameters() on a model object and standardizes the result to {broom}-style column names (e.g. estimate, std.error, conf.low, conf.high, statistic, df.error, p.value). Bayes factors are returned in a bf10 column, along with their natural logarithm in log_e_bf10. For Bayesian ANOVA designs ({BayesFactor} linear models), the estimate is replaced by the Bayesian R-squared.

Usage

tidy_model_parameters(model, ...)

Arguments

Value

A tibble with one row per parameter.

Citation

Patil, I., (2021). statsExpressions: R Package for Tidy Dataframes and Expressions with Statistical Details. Journal of Open Source Software, 6(61), 3236, https://doi.org/10.21105/joss.03236

Examples

model <- lm(mpg ~ wt + cyl, data = mtcars)
tidy_model_parameters(model)

Two-sample tests

Description

Parametric, non-parametric, robust, and Bayesian two-sample tests.

Usage

two_sample_test(
  data,
  x,
  y,
  subject.id = NULL,
  type = "parametric",
  paired = FALSE,
  alternative = "two.sided",
  digits = 2L,
  conf.level = 0.95,
  effsize.type = "g",
  var.equal = FALSE,
  bf.prior = 0.707,
  tr = 0.2,
  nboot = 100L,
  exact = FALSE,
  ...
)

Arguments

Value

The returned object is a tibble data frame with the additional class "statsExpressions". The exact set of columns depends on the test and, for functions that accept a type argument, on the chosen analysis (parametric, non-parametric, robust, or Bayesian). Any given call therefore returns some (not all) of the columns below.

Hypothesis testing

• statistic: the numeric value of a statistic

• df: the numeric value of a parameter being modeled (often degrees of freedom for the test)

• df.error and df: relevant only if the statistic in question has two degrees of freedom (e.g. anova)

• p.value: the p-value associated with the observed statistic (two-sided unless a one-sided alternative is requested, where supported)

• method: the name of the inferential statistical test

Effect size estimation

• effectsize: the name of the effect size

• estimate: estimated value of the effect size

• conf.level: the coverage level of the confidence/credible interval (e.g. 0.95); the interval itself spans conf.low to conf.high

• conf.low: lower bound for the effect size estimate

• conf.high: upper bound for the effect size estimate

• conf.method: method used to compute the confidence/credible interval

• conf.distribution: statistical distribution for the effect

Bayesian analysis (only when type = "bayes")

• bf10: Bayes factor for the alternative hypothesis relative to the null

• log_e_bf10: natural logarithm of the Bayes factor (present for most, but not all, Bayesian analyses)

• prior.distribution, prior.scale, prior.location: prior specification used to compute the Bayes factor and posterior estimates

Pairwise comparisons (for pairwise_comparisons() and pairwise_contingency_table())

• group1, group2: the two levels being compared

• p.adjust.method: the adjustment method used for multiple comparisons

• p.value.adj: the adjusted p-value; returned by pairwise_contingency_table(). Note that pairwise_comparisons() instead folds the adjusted value into p.value (and does not return a separate p.value.adj column)

Common columns

• n.obs: number of observations

• expression: a list-column of pre-formatted plotmath expressions; each element is a language object (not a character string) containing the statistical details, ready to be used in {ggplot2} (e.g. in labs() or annotate())

For a per-function, column-by-column breakdown of the output (and an explanation of the internal add_expression_col() engine that builds the expression column), see the Return value schema article. For more examples, see the data frame output vignette.

Two-sample tests

The table below provides summary about:

• statistical test carried out for inferential statistics

• type of effect size estimate and a measure of uncertainty for this estimate

• functions used internally to compute these details

between-subjects

Hypothesis testing

Effect size estimation

within-subjects

Data requirement: Paired tests assume exactly one observation per subject per condition. If your data has multiple trials per cell, aggregate first (e.g., take the mean).

Hypothesis testing

Effect size estimation

Citation

Patil, I., (2021). statsExpressions: R Package for Tidy Dataframes and Expressions with Statistical Details. Journal of Open Source Software, 6(61), 3236, https://doi.org/10.21105/joss.03236

Examples

# ----------------------- within-subjects -------------------------------------

# data
df <- dplyr::filter(bugs_long, condition %in% c("LDLF", "LDHF"))

# for reproducibility
set.seed(123)

# ----------------------- parametric ---------------------------------------

two_sample_test(
  df,
  condition,
  desire,
  subject.id = subject,
  paired = TRUE,
  type = "parametric"
)

# ----------------------- non-parametric -----------------------------------

two_sample_test(
  df,
  condition,
  desire,
  subject.id = subject,
  paired = TRUE,
  type = "nonparametric"
)

# ----------------------- robust --------------------------------------------

two_sample_test(
  df,
  condition,
  desire,
  subject.id = subject,
  paired = TRUE,
  type = "robust"
)

# ----------------------- Bayesian ---------------------------------------

two_sample_test(
  df,
  condition,
  desire,
  subject.id = subject,
  paired = TRUE,
  type = "bayes"
)

# ----------------------- between-subjects -------------------------------------

# for reproducibility
set.seed(123)

# ----------------------- parametric ---------------------------------------

# unequal variance
two_sample_test(ToothGrowth, supp, len, type = "parametric")

# equal variance
two_sample_test(ToothGrowth, supp, len, type = "parametric", var.equal = TRUE)

# biased (Cohen's d) effect size
two_sample_test(ToothGrowth, supp, len, type = "parametric", effsize.type = "d")

# ----------------------- non-parametric -----------------------------------

two_sample_test(ToothGrowth, supp, len, type = "nonparametric")

# ----------------------- robust --------------------------------------------

two_sample_test(ToothGrowth, supp, len, type = "robust")

# ----------------------- Bayesian ---------------------------------------

two_sample_test(ToothGrowth, supp, len, type = "bayes")