% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/add_cld.R
\name{add_cld}
\alias{add_cld}
\title{Compact Letter Display of All-Pairwise Comparisons}
\usage{
add_cld(test, p.col = NULL, threshold = 0.05, reversed = FALSE, ...)
}
\arguments{
\item{test}{an all-pairwise comparison result returned by an \code{rstatix}
function (e.g. \code{tukey_hsd()}, \code{dunn_test()}, a pairwise
\code{t_test()}/\code{wilcox_test()}, ...). Must contain the \code{group1}
and \code{group2} columns and a p-value column.}

\item{p.col}{character. The p-value column to threshold. If \code{NULL}
(default), \code{"p.adj"} is used when present, otherwise \code{"p"}.}

\item{threshold}{the significance threshold (default 0.05). Comparisons with a
p-value below \code{threshold} are treated as significant; comparisons with a
missing (\code{NA}) p-value are treated as non-significant.}

\item{reversed}{logical. If \code{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 \code{FALSE}.}

\item{...}{not used.}
}
\value{
a tibble with one row per group and the following columns: any grouping
 variables (for a grouped test), \code{.y.} (the outcome variable, when
 present), \code{group} (the group level) and \code{cld} (the compact letter
 display). Groups sharing a letter are not significantly different.
}
\description{
Adds the \strong{compact letter display} (CLD) to a pairwise
 comparison result. Groups that do \emph{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
 \code{\link{tukey_hsd}()}, \code{\link{dunn_test}()},
 \code{\link{games_howell_test}()}, \code{\link{conover_test}()},
 \code{\link{wilcox_test}()} or \code{\link{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
 \code{multcompView::multcompLetters()}).
}
\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()
}
\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.
}
\seealso{
\code{\link{tukey_hsd}}, \code{\link{dunn_test}},
 \code{\link{games_howell_test}}, \code{\link{add_significance}}
}
