jimjam-slam / stickylabeller

Create facet labels for ggplot2 using the glue package.

stickylabeller

The stickylabeller package helps you label the facets in your ggplot2 plots. If you know how to use the glue package, you know how to use stickylabeller!

Installation

Install stickylabeller from GitHub using devtools:

devtools::install_github("rensa/stickylabeller")

Use

The package has just one function: label_glue. Give it a string template to be processed by glue, and it'll return a labelling function that you can pass to facet_*:

library(stickylabeller)

# here's some example data
mydf = data_frame(
  x = 1:90,
  y = rnorm(90),
  red = rep(letters[1:3], 30),
  blue = c(rep(1, 30), rep(2, 30), rep(3, 30)))

# and here's a plot!
ggplot(mydf) +
  geom_point(aes(x = x, y = y)) +
  facet_wrap(
    ~ red + blue,
    labeller = label_glue('Red is {red}\nand blue is {blue}'))

ggplot(mydf) +
  geom_point(aes(x = x, y = y)) +
  facet_grid(
    red ~ blue,
    labeller = label_glue(
      rows = 'Red is {red}',
      cols = 'Blue is {blue}'))

Your label_glue labeller can refer to any of the data frame columns included in the facetting formula. It can also use those columns in expressions, like:

label_glue('Red is {toupper(red)}\nand blue is {blue}')

Numbering sequential facets

As well as the columns you include in the facetting specification, stickylabeller includes a few helper columns:

• .n numbers the facets numerically: "1", "2", "3"...
• .l numbers the facets using lowercase letters: "a", "b", "c"...
• .L numbers the facets using uppercase letters: "A", "B", "C"...
• .r numbers the facets using lowercase Roman numerals: "i", "ii", "iii"...
• .R numbers the facets using uppercase Roman numerals: "I", "II", "III"...

So you can automatically number your facets like:

ggplot(mydf) +
  geom_point(aes(x = x, y = y)) +
  facet_wrap(
    ~ red + blue,
    labeller = label_glue('({.l}) Red is {toupper(red)}\nand blue is {blue}'))

Limitations

• .n, .l and .L only work with facet_wrap for now. See Issue #1.

Including summary statistics in facet labels

There are a couple of ways to include summary statistics using stickylabeller. The most flexible way (but probably not the most performant, if you're working with a massive dataset) is to summarise your data and join it back to the original data, so that the summary statistics appear as new columns in the original data. Then include the summary columns in your facetting specification:

library(dplyr)

# summarise the data
multi_summary = mydf %>%
  group_by(red, blue) %>%
  summarise(
    mean_y = sprintf('%#.2f', mean(y)),
    sd_y = sprintf('%#.2f', sd(y))) %>%
  ungroup()

# join it back to the original data
mydf = mydf %>%
  inner_join(multi_summary)

# plot! remember to include the summaries in your facetting spec
ggplot(mydf) +
  geom_point(aes(x = x, y = y)) +
  facet_wrap(
    ~ red + blue + mean_y + sd_y,
    labeller = label_glue(
      '({.L}) Red = {red}, blue = {blue}\n(mean = {mean_y}, SD = {sd_y})'))

This works even if you're facetting by multiple columns and summarising by multiple columns. Keep in mind, however, that if you're going to continue to work with the data after plotting, you might want to drop the summary columns in order to avoid confusing yourself.

An alternate way to accomplish this is to convert each of your summary statistics into a vector named for the values of your facet column. This gets really messy with more than one facet column, though!

Have fun! If you hit any snags, please feel free to file an issue here so that I can get on it! <3

stickylabeller's Issues

In-panel labs

Just the other day I needed a helper function to polish some plots for a paper: I often have facetted plots without facet strips to save on space, and the editors require a label (a), (b), etc. for each facet, which they see as a sub-figure.

It'd be nice to use your glue framework with this alternative labelling technique (a dummy text layer placed with the panels).

label_facets <- function(p, hjust=-0.5, vjust=1.5, fontface=2, ...){
  
  gb <- ggplot_build(p)
  lay <- gb$layout$panel_layout
  nm <- names(gb$layout$facet$params$rows)
  tags <- cbind(lay, label = paste0("(",letters[lay$PANEL],")"))
  p + geom_text(data=tags, aes(x = -Inf, y=Inf, label=label), ...,
            hjust=hjust, vjust=vjust, fontface=fontface, inherit.aes = FALSE) +
    theme(strip.text = element_blank(), strip.background = element_blank())
}

Number more than 26 facets with letters

Ideally, using .l or .L with more than 26 facets should result in something like "AA", "AB", "AC"... "AZ", "BA", "BB", …. I don't know why you'd want that many facets in a single plot, but hey.

Pass arguments on to glue

glue supports additional arguments, like .open and .close for custom delimiters, and other named arguments for use as temporary variables. It'd be nice to pass these on from label_glue, but I want to wait until I've figured out facet-grid numbering and feel confident that the interface isn't going to change.

Roman numerals

Proposal: .r and .R columns for Roman numerals, analogous to .l and .L. I can do a pull request if you think this would be worth having.

Edit text size for panel labels?

Hi there -- I am using this package to annotate my panel labels for a figure I have targeted for publication. I really love the package and was able to annotate the labels as I desired. However, the base size of the text for the labels appears too small in the final figure. Is there any way to increase the font size for the labels? If not, can you please add it?

Sincerely,
Augustus

Facet numbering columns in facet_grid

Facet numbering is fairly easy with facet_wrap: each facet gets its own label and each label only covers one facet, so you can just assign numbers to each row in the incoming data frame, labels, and then parse them with glue.

It's not so easy with facet_grid: there are labels for the margins, not individual facets. The labeller gets called separately for each margin; when it does, you get the following attributes on labels:

• facet: this is "grid" for facet_grid;
• type: either rows or cols depending on which margin is being worked,
• row.names: each row is equal to the first cell in the row or column, as far as I can tell.

Here's the problem: if you're processing the row margins, the gaps in the row.names tell you how many columns there are, so you can work out in turn the values of all the cells in the row (assuming that there are no dropped levels! I think this is a somewhat reasonable assumption for facet_grid, though).

But if you're processing the column margins, all you can see is the first row. There's no way to infer how many rows there are, and you therefore can't work out the values of all the cells in the column.

One solution I'd considered is to use the fact that label_glue is a closure to store state between label_glue_inner calls. If the row margins were done first, this info could be passed on to the column margins. And since each call of label_glue has its own state, this shouldn't present a problem if you then go and use another call of it on a different plot (or the same plot again).

But in every test I've done, the column margins are done first, and I don't know if this can be changed. This appears to happen in ggplot2::render_strips. I'll file an issue and see if it can be changed. A less destructive change to ggplot2 might simply be to pass more metadata on to the labeller so that this stuff can be worked out without storing state.