A {grid} Legend

Paul Murrell

gg1 <- baseplot + 
    geom_col(aes(count, country, fill=pet), position="dodge") +
    basetheme
print(gg1)

This is a fairly normal {ggplot2} bar plot.

The important bit for this talk is that pet (cats and dogs) is being mapped to the bar fill.

This means that {ggplot2} has automatically produced a fill legend (guide).

Because I am fussy, I do not like {ggplot2}’s legend.

It is not the same size as the bars in the plot and it does not have the same spacing as the bars in the plot and it does not have a baseline like the bars in the plot and the bars are not aligned with any of the bars in the plot.

This legend makes me happy(er).

The bars in the legend are the same height as the bars in the plot.

The bars in the legend are aligned with (two of) the bars in the plot.

The bars in the legend have a grey “baseline” like the bars in the plot.

In this talk, I will demonstrate how I use {grid} to create a custom legend like this.

labels <- c(" dogs", " cats")
grid.legend <- function() {
    grid.segments(.2, .2, .2, .8, gp=gpar(col="grey"))
    grid.rect(.2, rep(.5, 2), .2, .2, hjust=0, vjust=1:0,
              gp=gpar(col=NA, fill=cols))
    grid.text(labels, .4, just="left",
              unit(.5, "npc") + unit(c(1, -1), "lines"),
              gp=gpar(fontsize=18))
}
grid.legend()

The most basic thing that {grid} lets me do is draw and arrange simple shapes.

I can draw lines, rectangles, and text.

I can position and size them using “normalised” coordinates.

I can justify the shapes relative to their position.

I can also use other coordinate systems like “lines” of text.

I can perform simple arithmetic to specify positions and sizes.

I can control the colours and fonts.

legendGrob <- function(width=.2, height=.2, fontsize=18) {
    line <- segmentsGrob(.2, .5 + height + .1,
                         .2, .5 - height - .1, 
                         gp=gpar(col="grey"))
    bars <- rectGrob(.2, rep(.5, 2), width, height, hjust=0, vjust=1:0,
                     gp=gpar(col=NA, fill=cols))
    labs <- textGrob(labels, .2 + width, just="left",
                     .5 + c(1, -1)*.5*height,
                     gp=gpar(fontsize=fontsize))
    grobTree(line, bars, labs)
}
grid.draw(legendGrob())

Alternatively, I can just create a “graphical object” (grob) that contains a description of the shapes and where I want to draw them and then draw that object as a separate step.

This will come in handy later on.

gg2 <- gg1 + theme(legend.position="none")
pushViewport(viewport(x=0, width=.8, just="left"))
print(gg2, newpage=FALSE)
popViewport()
pushViewport(viewport(x=1, width=.2, just="right"))
grid.legend()
popViewport()

I can use viewports to draw the {ggplot2} plot (minus its legend) on the left and my {grid} legend on the right.

Unfortunately, this combination is not terribly coherent.

legendViewport <- viewport(x=1, width=.2, just="left")
panelLegend <- grobTree(legendGrob(fontsize=12), 
                        vp=legendViewport)
gg3 <- gg2 + 
    coord_cartesian(clip="off") +
    grid_panel(panelLegend)
pushViewport(viewport(x=0, width=.8, just="left"))
print(gg3, newpage=FALSE)
popViewport()

We can make things more coherent by drawing the {grid} legend relative to the {ggplot2} plot panel viewport (using {gggrid}).

This passes the grob version of the legend to gggrid::grid_panel().

Unfortunately, the legend is still not consistent with the bars in the plot.

legendFun <- function(data, coords) {
    panelViewport <- viewport(x=1, width=.2, just="left", y=coords$y[1])
    h <- abs(diff(coords$y)[2])*.9/2
    grobTree(legendGrob(height=h, fontsize=12), vp=panelViewport)
}
gg4 <- gg2 + 
    coord_cartesian(clip="off") +
    grid_panel(legendFun, aes(count, country))
pushViewport(viewport(x=0, width=.8, just="left"))
print(gg4, newpage=FALSE)
popViewport()

This version passes a function to gggrid::grid_panel() (rather than a fixed grob).

That function gets access to the data in the plot.

We use that information to align the bars in the legend with (two of) the bars in the plot and to make the heights of the bars in the legend the same as the heights of the bars in the plot.

However, the calculation of the bar heights is a little mysterious and I would also like the bars in the legend to be square.

legendConvert <- function(data, coords) {
    panelViewport <- viewport(x=1, width=.2, just="left", y=coords$y[1])
    h <- abs(diff(coords$y)[2])*.9/2
    hin <- convertHeight(unit(h, "npc"), "in")
    w <- convertWidth(hin, "npc", valueOnly=TRUE)
    grobTree(legendGrob(width=w, height=h, fontsize=12), vp=panelViewport)
}
gg5 <- gg2 + 
    coord_cartesian(clip="off") +
    grid_panel(legendConvert, aes(count, country))
pushViewport(viewport(x=0, width=.8, just="left"))
print(gg5, newpage=FALSE)
popViewport()

This version attempts (unsuccessfully) to make the bars in the legend square.

We convert the bar height to inches and then that number of inches to a (normalised) width.

Unfortunately, the result reveals a potential problem with this sort of calculation.

The calculation is not occurring within the correct viewport.

makeContent.legend <- function(x) {
    h <- abs(diff(x$coords$y)[2])*.9/2
    hin <- convertHeight(unit(h, "npc"), "in")
    w <- convertWidth(hin, "npc", valueOnly=TRUE)
    setChildren(x,
                gList(grobTree(legendGrob(width=w, height=h, fontsize=12))))
}
legendDelayed <- function(data, coords) {
    panelViewport <- viewport(x=1, width=.2, just="left", y=coords$y[1])
    gTree(coords=coords, cl="legend", vp=panelViewport)
}

Rather than creating a fixed grob based on calculations, we can create a dynamic grob that delays the calculations until it is time to draw.

gg6 <- gg2 + 
    coord_cartesian(clip="off") +
    grid_panel(legendDelayed, aes(count, country))
pushViewport(viewport(x=0, width=.8, just="left"))
print(gg6, newpage=FALSE)
popViewport()

With the calculation happening when the legend is drawn (rather than when it is created), the legend bars are now square.

Unfortunately, the grey line is still wrong and the space to the right of the plot where we draw the legend is basically just a guess, rather than being exactly the space required for the legend.

print(gg2, newpage=FALSE)
grid.ls()

layout

We will start again with a different approach.

In this approach, we will calculate all of the dimensions we need before we begin drawing.

This starts with “measuring” the bars in the plot.

grid.ls() shows us the {grid} grobs that {ggplot2} has drawn.

Unfortunately, there is just one, which delays all of its calculations until it is time to draw (sound familiar?).

print(gg2, newpage=FALSE)
grid.force()
grid.ls()

layout
  background.1-13-16-1
    plot.background..zeroGrob.470
  panel.9-7-9-7
    panel-1.gTree.458
      grill.gTree.456
        panel.background..zeroGrob.454
        panel.grid.minor.x..zeroGrob.450
        panel.grid.major.y..zeroGrob.451
        panel.grid.major.x..polyline.453

If we grid.force() the drawing of the plot, we can see all of the {ggplot2} grobs.

print(gg2, newpage=FALSE)
grid.force()
barPath <- grid.grep("geom_rect", grep=TRUE, viewports=TRUE)
barPath

layout::panel.9-7-9-7::panel-1.gTree.507::geom_rect.rect.497 

attr(barPath, "vpPath")

[1] "layout::panel.9-7-9-7::GRID.VP.82"

The grobs have some funny (and dynamic) names, but there is enough structure there to search for what we want with grid.grep().

This code finds the bar grobs and the viewports that those grobs are drawn within.

print(gg2, newpage=FALSE)
grid.force()
barPath <- grid.grep("geom_rect", grep=TRUE, viewports=TRUE)
bars <- grid.get(barPath)
downViewport(attr(barPath, "vpPath"))
barHeight <- convertHeight(bars$height[1], "in")
barHeight

[1] 0.61327121682363inches

bottomGap <- convertY(bars$y[6], "in") - barHeight
bottomGap

[1] 0.20442373894121inches

We can get a copy of the bar grobs and visit the viewport that the bars were drawn within and calculate how high they are.

We also calculate how much the grey line sticks out beyond the bottom of the bottom bar.

labelGrob <- textGrob(labels, gp=gpar(fontsize=10))
gap <- unit(10, "mm")
legendWidth <- 3*gap + barHeight + grobWidth(labelGrob)
legend <- function(data, coords) {
    line <- segmentsGrob(2*gap, unit(.5, "npc") + barHeight + bottomGap,
                         2*gap, unit(.5, "npc") - barHeight - bottomGap, 
                         gp=gpar(col="grey", lwd=1.5))
    bars <- rectGrob(2*gap, rep(.5, 2), barHeight, barHeight, 
                     hjust=0, vjust=1:0,
                     gp=gpar(col=NA, fill=cols))
    labs <- textGrob(labels, 2*gap + barHeight, just="left",
                     unit(.5, "npc") + c(1, -1)*.5*barHeight,
                     gp=gpar(fontsize=10))
    vp <- viewport(x=1, width=legendWidth, y=coords$y[1], just="left")
    grobTree(line, bars, labs, vp=vp)
}

Given those dimensions, we can build a new {grid} legend and calculate how wide that legend is.

gg7 <- gg2 +
    theme(plot.margin=margin_part(r=0)) +
    grid_panel(legend, aes(count, country))
pushViewport(viewport(x=0, width=unit(1, "npc") - legendWidth, just="left"))
print(gg7, newpage=FALSE)
popViewport()

This allows us to arrange the legend relative to the plot to produce the final desired result.

This is neither the best possible legend, nor the best possible way to produce it.

However, it provided an excuse to cover a variety of ways of working with {grid} and the result is still code-based and therefore reproducible (and shareable, and version controllable, etc).