add_cld: Compact Letter Display of All-Pairwise Comparisons

In rstatix: Pipe-Friendly Framework for Basic Statistical Tests

Compact Letter Display of All-Pairwise Comparisons

Description

Adds the compact letter display (CLD) to a pairwise comparison result. Groups that do not share a letter are significantly different. This is a convenient way to annotate plots (e.g. one letter per box/bar) after an all-pairwise post-hoc test such as tukey_hsd(), dunn_test(), games_howell_test(), conover_test(), wilcox_test() or t_test().

The letters are computed with the insert-and-absorb algorithm (Piepho, 2004) using base R only, so no additional package is required (the results match multcompView::multcompLetters()).

Usage

add_cld(test, p.col = NULL, threshold = 0.05, reversed = FALSE, ...)

Arguments

test	an all-pairwise comparison result returned by an rstatix function (e.g. tukey_hsd(), dunn_test(), a pairwise t_test()/wilcox_test(), ...). Must contain the group1 and group2 columns and a p-value column.
p.col	character. The p-value column to threshold. If NULL (default), "p.adj" is used when present, otherwise "p".
threshold	the significance threshold (default 0.05). Comparisons with a p-value below threshold are treated as significant; comparisons with a missing (NA) p-value are treated as non-significant.
reversed	logical. If TRUE, reverses the order in which the letters are assigned (so that, with groups ordered by increasing level, the later groups receive the earlier letters). Default is FALSE.
...	not used.

Value

a tibble with one row per group and the following columns: any grouping variables (for a grouped test), .y. (the outcome variable, when present), group (the group level) and cld (the compact letter display). Groups sharing a letter are not significantly different.

References

Piepho, H.-P. (2004) An Algorithm for a Letter-Based Representation of All-Pairwise Comparisons. Journal of Computational and Graphical Statistics, 13(2), 456-466.

See Also

tukey_hsd, dunn_test, games_howell_test, add_significance

Examples

# Tukey HSD post-hoc, then compact letter display
res <- ToothGrowth %>%
  mutate(dose = factor(dose)) %>%
  tukey_hsd(len ~ dose)
res %>% add_cld()

# Works on rank-based post-hocs too
ToothGrowth %>% dunn_test(len ~ dose) %>% add_cld()

# Grouped pairwise test -> one CLD per group
ToothGrowth %>%
  mutate(dose = factor(dose)) %>%
  group_by(supp) %>%
  tukey_hsd(len ~ dose) %>%
  add_cld()

rstatix documentation built on July 24, 2026, 1:06 a.m.