Plot Partial Eta-Squared

Creates consonance plots (confidence curves and/or consonance density functions) for partial eta-squared values from ANOVA models, allowing visualization of uncertainty around effect size estimates.

Usage

plot_pes(
  Fstat,
  df1,
  df2,
  type = c("c", "cd"),
  levels = c(0.68, 0.9, 0.95, 0.999)
)

Arguments

Fstat

The F-statistic from the F-test.

df1

Degrees of freedom for the numerator (effect degrees of freedom).

df2

Degrees of freedom for the denominator (error degrees of freedom).

type

Choose which plot(s) to create:

"c": consonance function only (p-values across potential parameter values)
"cd": consonance density function only (distribution of plausible parameter values)
c("c", "cd"): both plots together (default)

levels

Numeric vector of confidence levels to display (default: c(.68, .9, .95, .999)). These correspond to the confidence intervals shown on the plot.

Value

A ggplot2 object or plot grid from cowplot.

Details

Consonance plots provide a graphical representation of the full range of confidence intervals for partial eta-squared values at different confidence levels. These plots help visualize the uncertainty around effect size estimates and go beyond the traditional approach of reporting only a single confidence interval (typically 95%).

Partial eta-squared (\(\eta^2\)) is a measure of effect size commonly used in ANOVA, representing the proportion of variance in the dependent variable attributed to a specific factor, while controlling for other factors in the model. Values range from 0 to 1, with larger values indicating stronger effects.

The function creates two types of visualizations:

Consonance function ("c"): Shows how p-values change across different possible values of partial eta-squared. The x-axis represents possible parameter values, and the y-axis represents the corresponding p-values from two-sided hypothesis tests.
Consonance density ("cd"): Shows the distribution of plausible values for the partial eta-squared. This can be interpreted as showing where the "weight of evidence" is concentrated.

These plots are particularly useful for:

Visualizing uncertainty around effect size estimates
Understanding the precision of effect size estimates
Comparing the relative plausibility of different effect sizes
Going beyond the binary "significant vs. non-significant" interpretation

The required inputs (F-statistic, df1, df2) can typically be extracted from standard ANOVA output in R, such as from aov(), Anova(), or afex_aov() functions.

These types of plots are discussed by Schweder & Hjort (2016) and Rafi & Greenland (2020).

References

Schweder, T., & Hjort, N. L. (2016). Confidence, likelihood, probability: Statistical inference with confidence distributions. Cambridge University Press. ISBN: 9781316445051

Rafi, Z., & Greenland, S. (2020). Semantic and cognitive tools to aid statistical science: Replace confidence and significance by compatibility and surprise. BMC Medical Research Methodology, 20, 244. doi:10.1186/s12874-020-01105-9

Examples

# Example 1: Basic consonance plot for partial eta-squared
# For an F-statistic of 4.5 with df1 = 2, df2 = 60
plot_pes(Fstat = 4.5, df1 = 2, df2 = 60)


# Example 2: Consonance function only (p-value curve)
plot_pes(Fstat = 3.2, df1 = 1, df2 = 45, type = "c")


# Example 3: Consonance density only
plot_pes(Fstat = 6.8, df1 = 3, df2 = 80, type = "cd")


# Example 4: Custom confidence levels
plot_pes(Fstat = 5.1, df1 = 2, df2 = 50, levels = c(0.5, 0.8, 0.95))


# Example 5: Using with actual ANOVA results
# aov_result <- aov(DV ~ IV, data = your_data)
# aov_summary <- summary(aov_result)[[1]]
# F_value <- aov_summary$"F value"[1]
# df1 <- aov_summary$Df[1]
# df2 <- aov_summary$Df[2]
# plot_pes(Fstat = F_value, df1 = df1, df2 = df2)

# Example 6: Saving and further customizing the plot
library(ggplot2)
p <- plot_pes(Fstat = 4.5, df1 = 2, df2 = 60)
p + theme_minimal() +
  labs(title = "Consonance Plot for Partial Eta-Squared",
       subtitle = "F(2, 60) = 4.5")