When polishing graphics for production you often spend a lot of time getting the axes and legends looking exactly right. This vignette describes the ggvis functions that allow you to control plot guides: axes and legends.

In ggvis, axes and legends are related to scales, but are described separately. This is different to ggplot2, where the scale objects controlled both the details of the mapping and how it should be displayed on the plot. This makes ggvis a little more verbose, but it also makes it more flexible.

Currently, ggvis guides are a close map to their vega equivalents. For reference, you may also want to read the vega documentation for the underlying axis and legend components.

Common properties

Axes and legends have relatively few components in common, but the ones that they share are particularly important.

Custom styles

Finally, both axes and legends share properties, which is a named list of props() that is applied to specified components of the axis or legend. For axes, you can set the properties of the ticks (or majorTicks and minorTicks separately), the labels and axis. For legends, you can set properties of the title, label, symbols (for categorical scales), gradient (for continuous scales), and legend.

Currently, if you’re using multiple scales, you’ll need to adjust properties to make sure that your legends don’t overlap.

ggvis(mtcars, props(x = ~wt, y = ~mpg)) +
  layer_point() +
  guide_axis("x", properties = list(
    axis = props(stroke = "red", strokeWidth = 5),
    grid = props(stroke = "blue"),
    ticks = props(stroke = "blue", strokeWidth = 2),
    labels = props(angle = 45, align = "left", fontSize = 20)
  ))

Axis

ggvis(mtcars, props(x = ~wt, y = ~mpg)) + layer_point()
ggvis(mtcars, props(x = ~wt, y = ~mpg)) + layer_point() +
  guide_axis("x", title = "Weight") +
  guide_axis("y", title = "Miles per gallon")
# Use title offset to push the titles further away
ggvis(mtcars, props(x = ~wt, y = ~mpg)) +
  layer_point() +
  guide_axis("x", title = "Weight", title_offset = 50) +
  guide_axis("y", title = "Miles per gallon", title_offset = 50)

Tick sizes and padding

There are five options that control the appearance of ticks:

# Change ticks and subdivide with minor ticks
ggvis(mtcars, props(x = ~wt, y = ~mpg)) +
  layer_point() +
  guide_axis("x", subdivide = 9, values = 1:6) +
  guide_axis("y", subdivide = 1, values = seq(10, 34, by = 2))
# Make the minor ticks smaller and the end ticks longer
ggvis(mtcars, props(x = ~wt, y = ~mpg)) +
  layer_point() +
  guide_axis("x", subdivide = 9, values = 1:6, tick_size_major = 10,
    tick_size_minor = 5, tick_size_end = 15, tick_padding = 20)

Orientation

You can control the placement of the axes with the orient argument:

ggvis(mtcars, props(x = ~wt, y = ~mpg)) +
  layer_point() +
  guide_axis("x", orient = "top") +
  guide_axis("y", orient = "right")

If you want axes on both sides, just add two axes:

ggvis(mtcars, props(x = ~wt, y = ~mpg)) +
  layer_point() +
  guide_axis("x", orient = "bottom") +
  guide_axis("x", orient = "top")

You can even put multiple scales on one side:

ggvis(mtcars, props(x = ~wt, y = ~mpg)) +
  layer_point() +
  guide_axis("x") +
  guide_axis("x", offset = 40, grid = FALSE)

This is probably more useful if you have multiple x or y position scales, but I’ve already discussed that enough times in these vignettes given how much I dislike them.

Legends

Combining legends

Unlike ggplot2, by default, ggvis will not combine scales based on the same underlying variables into a single legend. Instead you must do this yourself by supplying the name of multiple scales to one legend:

mtcars$cyl <- ordered(mtcars$cyl)
ggvis(mtcars, props(x = ~mpg, y = ~wt, size = ~cyl, fill = ~cyl)) +
  layer_point()
ggvis(mtcars, props(x = ~mpg, y = ~wt, size = ~cyl, fill = ~cyl)) +
  layer_point() +
  guide_legend(size = "size", fill = "fill")