Alpha version of colorbar legend in ggplot2

The examples below show colorbar legends in ggplot2.

Please note that this is alpha version and it is not sure if this implementation appears in the future version of ggplot2.

I’m happy if you play with this function and report potential bugs and missing functions.

To test this, you need install Hadley’s scales package and my implementation based on Hadley’s ggplot2.

Here is a direct link to the tarball:

The colorbar is controlled by passing the legend_param argument to scale_{fill, colour}_XXX. XXX needs to be continuous family, e.g., discrete, etc.

The legend_param needs to be a list. Currently three elements is available.

  1. colorbar (logical): draw colorbar if TRUE.
  2. colorbar_nbin (integer): the number of division of colorbar, i.e., the resolution of the colorbar default: approx. 20).
  3. colorbar_nbreaks (integer): the number of breaks of the colorbar (default: approx. 5).

The size of colorbar is controlled by theme – legend.key.size, legend.key.width, and legend.key.height.

The breaks and labels can be controlled via breaks and labels arguments in scale_*, this is same as normal legend.

Default legend

# default legend
p <- ggplot(melt(outer(1:4, 1:4)), aes(x=X1, y=X2)) + geom_tile(aes(fill=value))

Default colorbar legend

# colorbar legend (vertical)
p + scale_fill_continuous(legend_param=list(colorbar=T))

Default colorbar legend – horizontal

# colorbar legend (horizontal)
p + scale_fill_continuous(legend_param=list(colorbar=T)) + opts(legend.position="bottom", legend.direction="horizontal")

Specify the size of colorbar

# change the size of legend
p + scale_fill_continuous(legend_param=list(colorbar=T)) + opts(legend.key.width=unit(0.5, "line"), legend.key.height=unit(2, "line"))

Specify the number of breaks

# specify the number of breaks of legend
p + scale_fill_continuous(legend_param=list(colorbar=T, colorbar_nbreaks=10))

Manually specify the breaks

# manually specify the breaks
p + scale_fill_continuous(legend_param=list(colorbar=T), breaks=c(1,4,9,16))

Manually specify both breaks and labels

# manually specify the breaks and labels
p + scale_fill_continuous(legend_param=list(colorbar=T), breaks=c(1,4,9,16), labels=c("one^2", "two^2", "three^2", "four^2"))

Resolution of colorbar

# change the resolution of colorbar (default = 20)
p + scale_fill_continuous(legend_param=list(colorbar=T, colorbar_nbin=3))
p + scale_fill_continuous(legend_param=list(colorbar=T, colorbar_nbin=100))

Low resolution

High resolution

Combine with other legends

# combine with other scales with default scales
p + scale_fill_continuous(legend_param=list(colorbar=T)) + geom_point(aes(size=value))

Combine with colour and fill legends

# combine and merge colour and fill
p + geom_point(aes(y=X2+4, colour=value), size=10) + 
  scale_fill_continuous(legend_param=list(colorbar=T)) +

Seperately draw colour and fill colorbars

# combine but not merge colour and fill
ggplot(melt(outer(1:4, 1:4)), aes(x=X1, y=X2)) + geom_tile(aes(fill=value, colour=value), size=3) +
  scale_fill_continuous(name="fill", legend_param=list(colorbar=T)) +
  scale_colour_gradient(name="colour", low="pink", high="green", legend_param=list(colorbar=T))

Customize the color map

# use custom gradient (here jet colormap)
jet.colors <- colorRampPalette(c("#00007F", "blue", "#007FFF", "cyan", "#7FFF7F", "yellow", "#FF7F00", "red", "#7F0000"))
ggplot(melt(volcano), aes(x=X1, y=X2, fill=value)) + geom_tile() +
  scale_fill_gradientn(colours=jet.colors(7), legend_param=list(colorbar=T, colorbar_nbin=100))

Using plotmath expression for the legends

# plot math label by expression
p + scale_fill_continuous(
  expression(paste(alpha, beta, gamma)),
  breaks=c(1,16), labels=c(expression(1^2), expression(4^2)))

Specify the limits of the colorbar

# if the limits are pretty, then it looks like no expantion outside the limits
p + scale_fill_continuous(legend_param=list(colorbar=T, colorbar_nbin=100), limits=c(0,20))
# or set the breaks by using data range
p + scale_fill_continuous(legend_param=list(colorbar=T, colorbar_nbin=100),
  breaks=seq(range(p$data$value)[1], range(p$data$value)[2], length=5))


11 thoughts on “Alpha version of colorbar legend in ggplot2

  1. Very Nice kohske!

    Haven’t tried it yet, but from your set of examples my immediate questions would be:

    – can the labels be parsed as plotmath expressions?

    – can the color limits be specified not to expand on either side of the first and last breaks?

    Looks great!

    • Thanks baptiste,

      As for the 1st point, I will do that. Plotmath expression will be supported soon.

      As for the second point, it is not easy to implement that, because of the mapping of breaks and values.
      The mapping from value to color is a kind of point-to-point, not range-to-range.
      So, instead, I will provide an example that would look like very small expansion.

      Further discussion and suggestions are welcome.

  2. Thanks. For the last two examples the legend title seems a bit close to the top label; perhaps a vjust/hjust option could be added for the justification of the two.

    Other detail, browsing through the code, I was under the impression that the implementation relies on rectGrob with a given resolution. Have you considered using rasterGrob instead, with the option interpolate? In my experience, with lattice, color scale produced with rectGrob can lead to unpleasant artefacts in pdf viewers (spurious white lines between the rectangles).

    Thanks again.

    • Hi,

      Yes, the justification of the legend title can be controlled by the existing options like:


      And also thanks for the suggestion of rasterGrob. I just read the online help and probably the rasterGrob would be appropriate for the colorbar, at least if the interpolation will work well with n-gradients.

      Thanks again.

  3. I think rasterGrob is well suited for this; at least with the interpolation left as an option.

    You can test a direct comparison with,


    colorstripGrob(brewer.pal(8,”Blues”), raster=TRUE), ncol=2)

    • Yes, I got it. And pushed rasterGrob version to the github.

      It looks like working well.
      And also it save me from the calculation of the size and position of each div.


  4. I’m having hard time installing and testing this. The original link on the page ( is not functional, and I’ve tried installing different versions of the ggplot2 from your github site (assuming you merged this functionality there). I’ve tried the latest development version and some of the master versions, but they all seem to have various issues, either giving errors or not corresponding to the documentation/these examples.

    Could you provide us with a somewhat up-to-date instructions on how to install/use this colorbar legend at its current state?

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s