Skip to contents

Planned contrast test for tidy-format data using explicit sum-of-squares decomposition

Source: R/contrast_test_tidy.r
contrast_test_tidy.Rd

This function performs a planned contrast test on tidy-format data (participant × condition × response × contrast weight), by explicitly constructing sum-of-squares components.

Usage

contrast_test_tidy(
  dataset,
  paired = FALSE,
  alpha = 0.05,
  inc_allvar = FALSE,
  do_round = TRUE,
  autocorrect_unbalance = TRUE
)

Arguments

dataset

A data frame or tibble with exactly four columns, in the following order: (1) participant ID, (2) independent variable (condition), (3) dependent variable (response), (4) contrast weights.

paired

Logical. If TRUE, a within-participants (repeated-measures) contrast is performed. If FALSE, an independent-groups contrast is performed.

alpha

Significance level used for the sig column.

inc_allvar

Logical. If TRUE, return intermediate sums of squares and mean squares. If FALSE, return only commonly reported statistics.

do_round

Logical. If TRUE, round output values for compact display.

autocorrect_unbalance

Logical. If TRUE and paired = FALSE, contrast weights are automatically converted from condition-level coefficients to observation-level coefficients when group sizes are unbalanced, so that the tested contrast corresponds to the standard planned contrast on condition means.

Value

A data frame containing at least:

  • effect Contrast label.

  • df1, df2 Numerator and denominator degrees of freedom.

  • F F statistic.

  • p p-value.

  • sig Significance code ("*" or "ns").

  • eta2 Eta-squared.

  • peta2 Partial eta-squared.

  • cohens_f Cohen's f.

If inc_allvar = TRUE, sum-of-squares and mean squares are also returned.

Details

The implementation is intentionally written in a step-by-step decomposition style (grand mean, condition effects, residuals, contrast component, error component) so that students can directly inspect how a 1-degree-of-freedom contrast emerges as a regression on contrast weights and how its F statistic is constructed.

Although equivalent numerical results can be obtained by fitting a linear model, this function is designed for educational purposes to make the internal structure of contrast tests transparent.

The function assumes that contrast weights are constant within each condition. If their sum is not zero, weights are automatically centered.

Internally, the contrast is treated as a 1-degree-of-freedom regression on contrast weights, and the F statistic is constructed from explicit sum-of-squares decomposition rather than by calling lm().

In unbalanced designs, results may differ slightly from textbook planned contrasts based on condition means, because the contrast is implemented as a 1-df regression on observation-level contrast weights.

This design is intended to support teaching of contrast tests and ANOVA sum-of-squares structure.

Examples

# Example with independent groups
df <- data.frame(
  id = rep(1:30, each = 1),
  cond = rep(c("A","B","C"), each = 10),
  y = rnorm(30),
  w = rep(c(-1, 0, 1), each = 10)
)

contrast_test_tidy(df)
#>     effect df1 df2    F     p sig  eta2 peta2 cohens_f
#> 1 contrast   1  27 0.41 0.529  ns 0.015 0.015    0.123