Package 'ggtukey'

Create ggplot boxplot with compact letter display

Description

Performs pairwise comparisons using TukeyHSD and produces boxplots with compact letter display showing significance pairwise differences. Letters are produced by multcompLetters. Plots are produced by ggplot2. Raw data can also be overlaid in various ways according to the value of raw.

Usage

boxplot_letters(
  data,
  x,
  y,
  fill,
  group,
  test = c("tukey", "kruskalmc", "dunn"),
  type = c("two-way", "one-way"),
  where = c("box", "whisker", "mean", "median", "se", "sd", "cl_normal", "cl_boot"),
  raw = c("none", "points", "dots", "jitter"),
  pt_col = "slategray",
  hjust = 0,
  vjust = -0.2,
  lab_size = 4,
  na.rm = TRUE,
  threshold = 0.05,
  reversed = FALSE,
  Letters = letters,
  ...
)

Arguments

data	A data.frame in "long" format.
x	variable to plot on x axis.
y	variable to plot on y axis.
fill	column or color to fill boxplots
group	A grouping variable (to allow faceting).
test	Which test to run for pairwise comparisons. Either tukey (the default), kruskalmc, or dunn_test. Defaults to tukey.
type	If a grouping variable is provided, determines whether to run separate tests for each facet (one-way) or a single (two-way) test (with an interaction term between x and group). Defaults to two-way. This argument only applies if the Tukey test is selected, since there is no two-way Kruskal-Wallis test.
where	Where to put the letters. Either above the box (box) or upper whisker (whisker) of a boxplot; at the mean or median of the distribution; at the top of the error bars calculated from the standard error (se), standard deviation sd, or 95% confidence intervals returned by Hmisc::smean.cl.normal() (cl_normal), or Hmisc::smean.cl.boot() (cl_boot); or a fixed numeric y-position. A single number is recycled across all groups; a vector must have one value per group/facet, matching sorted group order.
raw	Whether to plot raw data and (if so), how. The current options are none, geom_point, geom_dotplot, or geom_jitter.
pt_col	Color of points, if raw data is plotted. geom_dotplot, or geom_jitter, according to the value of raw.
hjust	Horizontal adjustment of label. Argument to geom_text.
vjust	Vertical adjustment of label. Argument to geom_text.
lab_size	Label size. Argument to geom_text.
na.rm	Logical. Whether to remove observations with NAs for the provided factors (i.e. x and group) before plotting.
threshold	Statistical threshold for significance. Defaults to 0.05.
reversed	Logical. Argument to multcompLetters3. Determines whether order of letters should be reversed. Defaults to FALSE.
Letters	Character vector of symbols used to form the compact letter display. Defaults to letters (a, b, c, …). Pass LETTERS for uppercase, or any character vector for custom symbols.
...	Additional arguments to geom_point,

Details

Allows group variable for faceting

Value

Returns the specified plot as a ggplot object.

Note

Adapted from a helpful blog post by Justin Mathias.

Author(s)

Ethan Bass

Examples

set.seed(1)
data <- data.frame("Category" = c(rep("Low", 10), rep("Medium", 10), rep("High", 10)),
                   "Value" = c(rnorm(10, 5), rnorm(10, 5.5), rnorm(10, 10)),
                   "Size" = c("Big","Small"))
boxplot_letters(data, Category, Value)
boxplot_letters(data, x=Category, y=Value, group=Size)

---

Create Compact Letter Display Layer Groups with at least one letter in common are not significantly different.

Description

Create Compact Letter Display Layer Groups with at least one letter in common are not significantly different.

Usage

geom_tukey(
  test = c("tukey", "kruskalmc", "dunn"),
  type = c("two-way", "one-way"),
  threshold = 0.05,
  where = c("box", "whisker", "mean", "median", "se", "sd", "cl_normal", "cl_boot"),
  hjust = 0,
  vjust = -0.2,
  geom = "text",
  size = 4,
  color = "black",
  fill = "white",
  alpha = 1,
  na.rm = TRUE,
  reversed = FALSE,
  Letters = letters
)

Arguments

test	Which test to run for pairwise comparisons. Either tukey (the default), kruskalmc, or dunn_test.
type	If a grouping variable is provided, determines whether to run separate tests for each facet (one-way) or one (two-way) test with an interaction term between x and group. Defaults to two-way.
threshold	Statistical threshold for significance. Defaults to 0.05.
where	Where to put the letters. Either above the box (box) or upper whisker (whisker) of a boxplot; at the mean or median of the distribution; at the top of the error bars calculated from the standard error (se), standard deviation sd, or 95% confidence intervals returned by Hmisc::smean.cl.normal() (cl_normal), or Hmisc::smean.cl.boot() (cl_boot); or a fixed numeric y-position. A single number is recycled across all groups; a vector must have one value per group/facet, matching sorted group order.
hjust	Horizontal adjustment of the label. (Argument to geom_text).
vjust	Vertical adjustment of the label. (Argument to geom_text).
geom	Which geom to use to plot letters. Options are text and label.
size	Label size. Argument to geom_text.
color	Label color.
fill	Label fill (only applies if geom == "label").
alpha	Label transparency. Defaults to 1.
na.rm	Logical. Whether to remove observations with NAs for the provided factors (i.e. x and group) before plotting. Defaults to TRUE.
reversed	Logical. Argument to multcompLetters3. Determines whether order of letters should be reversed. Defaults to FALSE.
Letters	Character vector of symbols used to form the compact letter display. Defaults to letters (a, b, c, …). Pass LETTERS for uppercase, or any character vector for custom symbols (e.g. Greek letters or Unicode).

Note

Thank you to Hiroaki Yutani and Simon P. Couch for a couple of very helpful blog posts (1, 2) describing the ggplot_add syntax.

Author(s)

Ethan Bass

References

• Piepho, Hans-Peter. An Algorithm for a Letter-Based Representation of All-Pairwise Comparisons. Journal of Computational and Graphical Statistics 13, no. 2 (June 1, 2004): 456–66. doi:10.1198/1061860043515.

• Piepho, Hans-Peter. "Letters in Mean Comparisons: What They Do and Don't Mean." Agronomy Journal 110, no. 2 (2018): 431–34. doi:10.2134/agronj2017.10.0580

• Graves S, Piepho H, Dorai-Raj LSwhfS (2019). multcompView: Visualizations of Paired Comparisons. R package version 0.1-8. https://CRAN.R-project.org/package=multcompView

Examples

library(ggplot2)
set.seed(1)
data <- data.frame("Category" = c(rep("Low", 10), rep("Medium", 10), rep("High", 10)),
                  "Value" = c(rnorm(10, 5), rnorm(10, 5.5), rnorm(10, 10)),
                  "Size" = c("Big","Small"))
data |> ggplot(aes(x=Category, y=Value)) + geom_boxplot() + facet_wrap(~Size) + geom_tukey()
data |> ggplot(aes(x=Size, y=Value)) + geom_boxplot() + facet_wrap(~Category) + geom_tukey()

---

Check whether color specifications exists.

Description

Function to check whether all specified colors are actual colors.

Usage

is.color(x, return.colors = FALSE)

Arguments

x	Vector of any of the three kinds of R color specifications, i.e., either a color name (as listed by palettecolors()), a hexadecimal string of the form '#rrggbb' or '#rrggbbaa' (see rgb), or a positive integer i meaning palette()[i].
return.colors	Logical: logical values (FALSE, default) or returning colors (TRUE)

Value

Logical value (or colors)

Note

Adapted from plotfunctions packaage https://cran.r-project.org/web/packages/plotfunctions/index.html

Author(s)

Jacolien van Rij

Examples

# correct color definitions:
is.color(c('#FF0000FF', '#00FF00FF', '#0000FFFF'))
is.color(c('red', 'steelblue', 'green3'))
is.color(c(1,7,28))
# mixtures are possible too:
is.color(c('#FF0000FF', 'red', 1, '#FF0000', rgb(.1,0,0)))

# return colors:
# note that 28 is converted to 4...
is.color(c(1,7,28), return.colors=TRUE)
is.color(c('#FF0000CC', 'red', 1, '#FF0000'), return.colors=TRUE)

# 4 incorrect colors, 1 correct:
test <- c('#FH0000', 3, '#FF00991', 'lavendel', '#AABBCCFFF')
is.color(test)
is.color(test, return.colors=TRUE)

---

Get compact letter display from a fitted model via emmeans

Description

Generates a compact letter display (CLD) from any model type supported by emmeans and returns a plain data frame suitable for use with geom_text or geom_label. Unlike geom_tukey, model fitting is left entirely to the user, making this function suitable for mixed-effects models, GLMs, and other complex model types.

Usage

tukey_letters(
  model,
  spec,
  data = NULL,
  by = NULL,
  where = "emmean",
  adjust = "tukey",
  threshold = 0.05,
  reversed = FALSE,
  Letters = letters
)

Arguments

model	A fitted model object supported by emmeans (e.g. from lm, aov, lmer, glm).
spec	A one-sided formula specifying the factor to test, e.g. ~ species.
data	The data frame used to fit the model. Required when where is not "emmean".
by	Optional character vector of conditioning variables for faceted plots, passed to emmeans. E.g. by = "sex" runs separate comparisons within each level of sex.
where	Where to place the letters on the y axis. Either "emmean" (default — uses the estimated marginal mean from the model), a numeric value for a fixed position, or any placement option from geom_tukey: "box", "whisker", "mean", "median", "se", "sd", "cl_normal", "cl_boot" (the last two require Hmisc). All options other than "emmean" require data to be supplied.
adjust	P-value adjustment method passed to contrast. Defaults to "tukey".
threshold	Significance threshold. Defaults to 0.05.
reversed	Logical. Whether to reverse letter order so that the group with the smallest mean is assigned "a". Defaults to FALSE.
Letters	Character vector of symbols used to form the compact letter display. Defaults to letters (a, b, c, …). Pass LETTERS for uppercase, or any other character vector for custom symbols (e.g. Greek letters).

Value

A data frame with one row per group (or per group × by combination) containing the grouping columns, y (placement position), and letter (the compact letter display string).

See Also

geom_tukey, emmeans, cld

Examples

library(ggplot2)
set.seed(1)
data <- data.frame(
  Category = c(rep("Low", 10), rep("Medium", 10), rep("High", 10)),
  Value    = c(rnorm(10, 5), rnorm(10, 5.5), rnorm(10, 10))
)
mod <- lm(Value ~ Category, data = data)
if (requireNamespace("emmeans", quietly = TRUE)) {
  ldf <- tukey_letters(mod, ~ Category, data = data, where = "box")
  ggplot(data, aes(x = Category, y = Value)) +
    geom_boxplot() +
    geom_text(data = ldf, aes(x = Category, y = y, label = letter),
              vjust = -0.3)
}

---