Introduction to gghighlight

Bar

gghighlight() can highlight bars.

p <- ggplot(iris, aes(Sepal.Length, fill = Species)) +
  geom_histogram() +
  gghighlight()
#> label_key: Species

p
#> `stat_bin()` using `bins = 30`. Pick better value with `binwidth`.
#> `stat_bin()` using `bins = 30`. Pick better value with `binwidth`.

Are you wondering if this is really highlighted? Yes, it is. But, the unhighlighted bars are all overwritten by the highlighted bars. This seems not so useful, until you see the facetted version:

p + facet_wrap(~ Species)
#> `stat_bin()` using `bins = 30`. Pick better value with `binwidth`.
#> `stat_bin()` using `bins = 30`. Pick better value with `binwidth`.

Point

As is explained in Anatomy of gghighlight, lines and points typically have different semantics (group-wise or not). But, in most cases, you don’t need to be careful about the difference with gghighlight() because it automatically picks the right method of calculation.

set.seed(10)
d2 <- dplyr::slice_sample(d, n = 20)

ggplot(d2, aes(idx, value)) +
  geom_point() +
  gghighlight(value > 0, label_key = type)

More precisely, gghighlight() takes the following strategy:

1. Calculate the group IDs from mapping.
   1. If group exists, use it.
   2. Otherwise, assign the group IDs based on the combination of the values of discrete variables.
2. If the group IDs exists, evaluate the predicates in a grouped manner.
3. If the group IDs doesn’t exist or the grouped calculation fails, evaluate the predicates in an ungrouped manner.

Note that, in this case, label_key = type is needed to show labels because gghighlight() chooses a discrete variable from the mapping, but aes(idx, value) consists of continuous variables only.

unhighlighted_params

If you want to change the style of unhighlighted layers, use unhighlighted_params.

ggplot(d) +
  geom_line(aes(idx, value, colour = type), linewidth = 5) +
  gghighlight(max(value) > 19,
              unhighlighted_params = list(linewidth = 1, colour = alpha("pink", 0.4)))
#> label_key: type

You can also specify NULL to fill or colour to preserve the original color.

ggplot(d) +
  geom_line(aes(idx, value, colour = type)) +
  gghighlight(max(value) > 19,
              # preserve colour and modify alpha instead
              unhighlighted_params = list(colour = NULL, alpha = 0.3))
#> label_key: type

keep_scales

If you want to keep the original scales, set keep_scales to TRUE.

p <- ggplot(mtcars, aes(wt, mpg, colour = factor(cyl))) +
  geom_point()

p + gghighlight(cyl == 6)
#> Warning: Tried to calculate with group_by(), but the calculation failed.
#> Falling back to ungrouped filter operation...

p + gghighlight(cyl == 6, keep_scales = TRUE) + ggtitle("keep_scales = TRUE")
#> Warning: Tried to calculate with group_by(), but the calculation failed.
#> Falling back to ungrouped filter operation...

calculate_per_facet

If you want to highlight each facet individually, set calculate_per_facet to TRUE. Note that gghighlight() affects the plot before gghighlight(). If you add facet_*() after adding gghighlight(), this option doesn’t work.

d <- data.frame(
  idx =   c(1, 2, 3, 4, 1, 2, 3, 4),
  value = c(10, 11, 12, 13, 4, 8, 16, 32),
  cat1 =  rep(c("a", "b"), each = 4),
  cat2 =  rep(rep(c("1-2", "3-4"), each = 2), 2),
  stringsAsFactors = FALSE
)

p <- ggplot(d, aes(idx, value, colour = cat1)) +
  geom_line() +
  facet_wrap(vars(cat2))

p +
  gghighlight(max(value) > 10)
#> label_key: cat1

p +
  gghighlight(max(value) > 10, calculate_per_facet = TRUE) +
  ggtitle("calculate_per_facet = TRUE")
#> label_key: cat1

line_label_type (experimental)

By default, gghighlight uses the ggrepel package for labeling lines. You can change the method by line_label_type argument. The options are:

• "ggrepel_label" (default): Use ggrepel::geom_label_repel().
• "ggrepel_text": Use ggrepel::geom_text_repel().
• "text_path": Use geomtextpath::geom_textline() for lines and geomtextpath::geom_textpath() for paths.
• "label_path": Use geomtextpath::geom_labelline() for lines and geomtextpath::geom_labelpath() for paths.
• "sec_axis": Use secondary axis. Please refer to Simon Jackson’s blog post for the trick.

d <- data.frame(
  x = rep(1:3, times = 3),
  y = c(1:3, 2, 4, 2, 0, 1, 1),
  id = rep(c("a", "b", "c"), each = 3)
)

p <- ggplot(d) +
  geom_line(aes(x, y, colour = id))

p +
  gghighlight(max(y) >= 3, line_label_type = "label_path", label_params = list(size = 10)) +
  ggtitle('line_label_type = "label_path"')
#> label_key: id

p +
  gghighlight(max(y) >= 3, line_label_type = "sec_axis") +
  ggtitle('line_label_type = "sec_axis"') +
  theme(axis.text.y.right = element_text(size = 20))
#> label_key: id

Note that, while this looks good for this example, there are some limitations:

• Unlike ggrepel, there’s no mechanism to avoid overlapping. You’ll probably want to choose ggrepel_label or ggrepel_text when the data has many series.
• Since "sec_axis" is a very different approach than the other, some label_params are ignored. For example, if you want to change the text size of the labels, you need to specify it via ggplot2::theme() instead of label_params.