add_legend {ggvis}

Add a vega legend specification to a ggvis plot

Description

Axis specifications allow you to either override the default legends, or supply additional legends.

Usage

add_legend(
  vis,
  scales = NULL,
  orient = "right",
  title = NULL,
  format = NULL,
  values = NULL,
  properties = NULL
)

hide_legend(vis, scales)

Arguments

vis

A ggvis object.

scales

The name of one or more scales for which to add a legend. Typically one of "size", "shape", "fill", "stroke", although custom scale names may also be used. Multiple names can also be used, like c("fill", "shape").

orient

The orientation of the legend. One of "left" or "right". This determines how the legend is positioned within the scene. The default is "right".

title

A title for the legend. By default, it uses the name the fields used in the legend. Use "" to suppress the title.

format

The formatting pattern for axis labels. Vega uses D3's format pattern.

values

Explicitly set the visible legend values.

properties

Optional mark property definitions for custom legend styling. Should be an object created by legend_props, with properties for title, label, symbols, gradient, legend.

Details

More information about axes can be found in the "axes and legends" vignettes.

Compared to ggplot2

In ggplot2, legend (and axis) properties are part of the scales specification. In vega, they are separate, which allows the specification of multiple legends, and more flexible linkage between scales and legends.

Examples

mtcars %>% ggvis(x = ~wt, y = ~mpg, fill = ~cyl) %>%
  layer_points() %>%
  add_legend("fill", title = "Cylinders")

# Suppress legend with hide_legend
mtcars %>% ggvis(x = ~wt, y = ~mpg, fill = ~cyl) %>%
  layer_points() %>%
  hide_legend("fill")

# Combining two properties in one legend
mtcars %>%
  ggvis(x = ~wt, y = ~mpg, fill = ~factor(cyl), shape = ~factor(cyl)) %>%
  layer_points() %>%
  add_legend(c("fill", "shape"))

# Control legend properties with a continuous legend, with x and y position
# in pixels.
mtcars %>% ggvis(x = ~wt, y = ~mpg, fill = ~cyl) %>%
  layer_points() %>%
  add_legend("fill", title = "Cylinders",
    properties = legend_props(
      title = list(fontSize = 16),
      labels = list(fontSize = 12, fill = "#00F"),
      gradient = list(stroke = "red", strokeWidth = 2),
      legend = list(x = 500, y = 50)
    )
  )

# Control legend properties with a categorical legend, with x and y position
# in the scaled data space.
mtcars %>% ggvis(x = ~wt, y = ~mpg, fill = ~factor(cyl)) %>%
  layer_points() %>%
  add_legend("fill", title = "Cylinders",
    properties = legend_props(
      title = list(fontSize = 16),
      labels = list(fontSize = 14, dx = 5),
      symbol = list(stroke = "black", strokeWidth = 2,
        shape = "square", size = 200),
      legend = list(
        x = scaled_value("x", 4.5),
        y = scaled_value("y", 30)
      )
    )
  )

# Control legend position using x_rel and y_rel which specify relative
# position, going from 0 to 1. (0, 0) is the bottom-left corner, and
# (1, 1) is the upper-right corner. The values control the position of
# the upper-left corner of the legend.
mtcars %>% ggvis(x = ~wt, y = ~mpg, fill = ~cyl) %>%
  layer_points() %>%
  add_relative_scales() %>%
  add_legend("fill", title = "Cylinders",
    properties = legend_props(
      legend = list(
        x = scaled_value("x_rel", 0.8),
        y = scaled_value("y_rel", 1)
      )
    )
  )