Return value schema

In statsExpressions: Tidy Dataframes and Expressions with Statistical Details

#| label = "setup",
#| message = FALSE,
#| warning = FALSE,
#| include = FALSE,
#| echo = FALSE
source("../setup.R")

Introduction

Every exported analysis function in {statsExpressions} returns a tidy tibble (with the additional class "statsExpressions") rather than a model object. This means the output is immediately pipe-friendly and ready for downstream use in data wrangling or graphing pipelines.

Two design principles are worth keeping in mind while reading this article:

1. The exact columns depend on the analysis. All functions follow the same tidy/{broom}-style naming conventions, but the precise set of columns returned depends on the test and, for functions that accept a type argument, on the chosen analysis ("parametric", "nonparametric", "robust", or "bayes"). For example, most Bayesian analyses return Bayes-factor columns (bf10, and usually log_e_bf10) that frequentist analyses do not.

2. The expression column is the core deliverable. Regardless of the test, almost every function returns a pre-formatted expression column intended for annotating plots. This is what powers the statistical details you see in {ggstatsplot} plots.

This article explains the expression column and lists representative output columns for each analysis function. For worked examples, see Data frame outputs; for the meaning of the tests and effect sizes, see Test and effect size details.

The expression column

The expression column is a list-column: each element is a plotmath language object (not a character string), which is why it can render mathematical notation (subscripts, Greek letters, italicized statistics) when used as a plot label. Extract a single element with [[ before using it.

#| label = "expression-class"
set.seed(123)
res <- two_sample_test(ToothGrowth, supp, len)

# the column is a list; each element is a `language` object, not a string
class(res$expression)
class(res$expression[[1]])

Because each element is a language object, it can be dropped directly into any {ggplot2} layer that accepts a plotmath expression, such as labs(), annotate(), or ggtitle():

#| label = "expression-usage",
#| eval = FALSE
library(ggplot2)

ggplot(ToothGrowth, aes(supp, len)) +
  geom_boxplot() +
  labs(subtitle = res$expression[[1]])

The add_expression_col() engine

Most of the expression columns are produced by a single internal engine: add_expression_col(). It is the main path for the hypothesis-testing functions (one_sample_test(), two_sample_test(), oneway_anova(), corr_test(), contingency_table(), meta_analysis()). The one exception is the Bayesian one-way (goodness-of-fit) contingency_table() analysis, which builds its own minimal expression. Understanding it helps clarify why the output looks the way it does.

The engine works as follows:

• It consumes a tidy data frame of statistical details -- ideally the output of tidy_model_parameters(), which standardizes the results from the various modeling backends ({effectsize}, {parameters}, {BayesFactor}, etc.) into consistent column names.

• It inspects the available columns to decide which expression template to use. The key branch points are:

  • whether the analysis is Bayesian (detected via the presence of a bf10 column), and

  • the number of degrees-of-freedom parameters present (0, 1, or 2), which determines whether the statistic is displayed as, e.g., t = ..., t(df) = ..., or F(df1, df2) = ....

• It then formats the numeric values (respecting the digits, digits.df, and digits.df.error arguments), assembles the plotmath string via {glue}, converts it to a language object, and appends it as the expression column.

Not every function routes through this engine. centrality_description(), pairwise_comparisons(), and pairwise_contingency_table() build their own {glue} templates and call the shared .glue_to_expression() helper directly to attach the expression column. The end result is the same kind of list-column of plotmath expressions, but the assembly path is specialized rather than going through add_expression_col().

Note: add_expression_col() is exported so that its behavior is documented and can be inspected, but it is not stable and is intended for internal use only. Its signature and behavior may change without a deprecation cycle. Build downstream code against the output columns documented here rather than by calling this function directly.

Per-function schema

The tables list representative columns, with type-specific differences noted below each table. Use names(result) or dplyr::glimpse(result) to inspect the exact columns returned by a particular call and package version. conf.* and prior.* below abbreviate the available interval and prior columns.

one_sample_test()

| Column | Description | | :------------------------------------------------------------------------ | :------------------------------------------------------------------- | | mu | the null value the mean is tested against (test.value) | | statistic, df.error, p.value | test statistic, its degrees of freedom, and p-value (non-Bayesian) | | effectsize, estimate | name and value of the effect size (e.g. Hedges' g) | | conf.level, conf.low, conf.high, conf.method, conf.distribution | interval details for the effect size | | bf10, log_e_bf10, prior.* | Bayes factor, its log, and the prior (Bayesian only) | | n.obs | number of observations | | expression | plotmath expression with the test details |

The Bayesian variant (type = "bayes") replaces statistic/df.error/p.value with term, pd, bf10, log_e_bf10, and the prior.* columns.

two_sample_test()

| Column | Description | | :----------------------------------- | :---------------------------------------------------- | | parameter1, parameter2 | the outcome and grouping variable names | | mean.parameter1, mean.parameter2 | group means (parametric between-subjects) | | statistic, df.error, p.value | test statistic, its degrees of freedom, and p-value | | effectsize, estimate, conf.* | effect size and its interval | | n.obs, expression | sample size and the plotmath expression |

As with one_sample_test(), the Bayesian variant returns term, pd, bf10, log_e_bf10, and prior.* in place of the frequentist test statistic and p-value.

oneway_anova()

| Column | Description | | :--------------------------------------- | :----------------------------------------------------------- | | statistic, df, df.error, p.value | F-statistic with its two degrees of freedom, and p-value | | effectsize, estimate, conf.* | effect size (e.g. omega-squared) and its interval | | n.obs, expression | sample size and the plotmath expression |

For a two-degrees-of-freedom statistic like ANOVA, note that both df and df.error are present. The non-parametric variant (type = "np") instead returns a single-parameter statistic with parameter1/parameter2 and a conf.iterations column (the number of bootstrap iterations), while the Bayesian variant returns the usual bf10/log_e_bf10/prior.* columns.

corr_test()

| Column | Description | | :--------------------------------------------------- | :----------------------------------------------------- | | parameter1, parameter2 | the two correlated variable names | | effectsize, estimate | name (e.g. Pearson's r) and value of the correlation | | conf.level, conf.low, conf.high, conf.method | interval details | | statistic, df.error, p.value | test statistic, degrees of freedom, and p-value | | n.obs, expression | sample size and the plotmath expression |

The Bayesian variant returns bf10, pd, rope.percentage, and the prior.* columns in place of statistic, df.error, and p.value. Unlike the Bayesian t-tests, it does not return log_e_bf10.

contingency_table()

| Column | Description | | :--------------------------------- | :----------------------------------------------------------- | | statistic, df, p.value | chi-squared statistic, its degrees of freedom, and p-value | | effectsize, estimate, conf.* | effect size (e.g. Cramer's V) and its interval | | bf10, prior.scale | Bayes factor and prior (Bayesian only) | | n.obs, expression | sample size and the plotmath expression |

The two Bayesian paths differ in their columns. The two-way Bayesian analysis returns the full set of Bayesian columns (term, bf10, log_e_bf10, prior.distribution/prior.location/prior.scale, plus the effect-size interval). The one-way (goodness-of-fit) Bayesian analysis is more minimal, returning only bf10, prior.scale, method, and expression -- in particular it does not include a log_e_bf10 column.

pairwise_comparisons()

| Column | Description | | :------------------------ | :------------------------------------------------------ | | group1, group2 | the two levels being compared | | statistic, p.value | test statistic and the (adjusted) p-value | | p.adjust.method, test | multiple-comparison adjustment method and the test used | | expression | plotmath expression with the (adjusted) p-value |

Unlike the single-test functions, this returns one row per pairwise comparison. Note that the adjusted p-value is folded directly into the p.value column here (there is no separate p.value.adj column, unlike in pairwise_contingency_table()). The Bayesian variant returns posterior estimates, intervals, bf10, log_e_bf10, and prior.* columns instead of statistic, p.value, and p.adjust.method; no p-value adjustment is applied to Bayes factors.

pairwise_contingency_table()

| Column | Description | | :-------------------------------------- | :----------------------------------------------- | | group1, group2 | the two levels being compared | | p.value, p.value.adj | unadjusted and multiplicity-adjusted p-values | | effectsize, estimate, conf.* | Cramer's V effect size and its interval | | p.adjust.method, test, expression | adjustment method, test, and plotmath expression |

meta_analysis()

| Column | Description | | :--------------------------------------------------- | :---------------------------------------------------- | | term, effectsize | the summary term and effect-size label | | estimate, std.error | meta-analytic summary estimate and its standard error | | conf.level, conf.low, conf.high, conf.method | interval details | | statistic, p.value, weight | test statistic, p-value, and summary weight (may be NA) | | n.obs, expression | number of studies and the plotmath expression |

The Bayesian variant additionally returns MCMC diagnostics and Bayes-factor columns: bf10, log_e_bf10, rhat, ess, component, and the prior.* columns.

centrality_description()

| Column | Description | | :------------------------------------------------------------ | :--------------------------------------------------------------------------------- | | <x> (e.g. Species) | the grouping variable | | <y> (e.g. Sepal.Length) | the requested centrality measure (mean/median/trimmed mean/MAP) | | std.dev or mad, iqr, min, max, skewness, kurtosis | dispersion and shape statistics | | conf.low, conf.high | interval for the centrality estimate | | n.obs, missing.obs | retained observations and missing values after filtering (see below) | | expression | plotmath expression with the centrality estimate | | n.expression | a label combining the group name and its sample size (handy as a facet/axis label) |

The dispersion column depends on type: std.dev for "parametric" and "robust", mad (median absolute deviation) for "nonparametric", and neither for "bayes". Rows with missing x or y are removed before the summaries are computed, so missing.obs is 0 rather than the number of missing values in the original input. This is the only function that returns an n.expression column.

Suggestions

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

Citation

citation("statsExpressions")

statsExpressions documentation built on Oct. 17, 2026, 9:06 a.m.