Cross legend guide

This is a legend type similar to guide_legend() that displays crosses, or: interactions, between two variables.

Usage

guide_legend_cross(
  key = NULL,
  title = waiver(),
  row_title = waiver(),
  col_title = waiver(),
  swap = FALSE,
  col_text = element_text(angle = 90, vjust = 0.5),
  subtitle_position = position_text(angle = c(0, -90, 0, 90), hjust = 0.5),
  override.aes = list(),
  reverse = FALSE,
  theme = NULL,
  position = NULL,
  direction = NULL,
  order = 0L
)

Arguments

key

One of the following key specifications:

• A group split specification when using the legend to display a compound variable like paste(var1, var2).

• A standard key specification, like key_auto(), when crossing two separate variables across two scales.

title

One of the following to indicate the title of the guide:

• A <character[1]> or <expression[1]> to set a custom title.

• NULL to not display any title.

• waiver() (default) to take the name of the scale object or the name specified in labs() as the title.

row_title, col_title

One of the following to indicate subtitles spanning the rows and columns of the guide:

• A <character[1]> or <expression[1]> to set a custom title.

• NULL to not display any title.

• waiver() to propagate subtitles from merging guides (default).

swap

A <logical[1]> which when TRUE exchanges the column and row variables in the displayed legend.

col_text

An <element_text> object giving adjustments to text for the column labels. Can be NULL to display column labels in equal fashion to the row labels.

subtitle_position

A named list of 4 text elements, having the names "top", "right", "bottom" and "left. These govern the display of subtitles when placed in any of these positions relative to the keys. See position_text() for a convenient helper.

override.aes

A named <list> specifying aesthetic parameters of the key glyphs. See details and examples in guide_legend().

reverse

A <logical[2]> whether the order of the keys should be inverted, where the first value controls the row order and second value the column order. Input as <logical[1]> will be recycled.

theme

A <theme> object to style the guide individually or differently from the plot's theme settings. The theme argument in the guide overrides and is combined with the plot's theme.

position

A <character[1]> giving the location of the guide. Can be one of "top", "bottom", "left" or "right".

direction

A <character[1]> indicating the direction of the guide. Can be on of "horizontal" or "vertical".

order

A positive <integer[1]> that specifies the order of this guide among multiple guides. This controls in which order guides are merged if there are multiple guides for the same position. If 0 (default), the order is determined by a hashing indicative settings of a guide.

Value

A <GuideLegend> object.

Details

Styling options

Below are the theme options that determine the styling of this guide. Note that these are almost the same for ggplot2::guide_legend().

Theme setting	Type	Description
legend.background	element_rect()	Background of the legend.
legend.margin	margin()	Padding around the legend.
legend.text	element_text()	Labels displayed next to keys.
legend.text.position	<character[1]>	One of "top", "right", "bottom" or "left".
legend.title	element_text()	Title of the legend.
legend.title.position	<character[1]>	One of "top", "right", "bottom" or "left".
legend.key	element_rect()	Background of the key areas.
legend.key.height	unit()	Height of keys.
legend.key.width	unit()	Width of keys.
legend.key.justification	<numeric[2]>	Justification for placing legend keys in excess space.
legend.key.spacing.x	unit()	Horizontal spacing between keys.
legend.key.spacing.y	unit()	Vertical spacing between keys. Taken literally.

The context-agnostic alternative to using theme() is to use theme_guide():

guide_legend_cross(theme = theme_guide(
  text = element_text(),
  text.position = "right",
  title = element_text(),
  title.position = "top",
  key = element_rect(),
  key.height = unit(5, "mm"),
  key.width = unit(5, "mm"),
  key.justification = c(0.5, 0.5),
  key.spacing.x = unit(5, "mm"),
  key.spacing.y = unit(5, "mm"),
  margin = margin(5),
  background = element_rect(),
))

See also

Other standalone guides: guide_axis_annotation(), guide_axis_base(), guide_axis_dendro(), guide_axis_nested(), guide_axis_plot(), guide_axis_symbols(), guide_circles(), guide_colbar(), guide_colring(), guide_colsteps(), guide_legend_base(), guide_legend_group(), guide_legend_manual()

Other legend guides: guide_legend_base(), guide_legend_group(), guide_legend_manual()

Examples

# Standard use for single aesthetic. The default is to split labels to
# disentangle aesthetics that are already crossed (by e.g. `paste()`)
ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = paste(year, drv))) +
  guides(colour = "legend_cross")


# If legends should be merged between identical aesthetics, both need the
# same legend type.
ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = paste(year, drv), shape = paste(year, drv))) +
  guides(colour = "legend_cross", shape = "legend_cross")


# Crossing two aesthetics requires a shared title and `key = "auto"`. The
# easy way to achieve this is to predefine a shared guide.
my_guide <- guide_legend_cross(key = "auto", title = "My title")

ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = drv, shape = factor(year))) +
  guides(colour = my_guide, shape  = my_guide)


# You can cross more than 2 aesthetics but not more than 2 unique aesthetics.
ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = drv, shape = factor(year), size = factor(drv))) +
  scale_size_ordinal() +
  guides(colour = my_guide, shape = my_guide, size = my_guide)


# You can merge an aesthetic that is already crossed with an aesthetic that
# contributes to only one side of the cross.
ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = paste(year, drv), shape  = drv)) +
  guides(
    colour = guide_legend_cross(title = "My Title"),
    shape  = guide_legend_cross(title = "My Title", key = "auto")
  )