marquee (version 1.0.0)

guide_marquee: Marquee subtitle guide

Description

This legend appears similar to a subtitle and uses marquee syntax to typeset the text and interpolate legend glyphs.

Usage

guide_marquee(
  title = ggplot2::waiver(),
  style = marquee::style(background = NA),
  detect = FALSE,
  theme = NULL,
  position = "top",
  override.aes = list(),
  order = 1
)

Value

A GuideMarquee object that can be passed to the guides() function or used as the guide argument in a scale.

Arguments

title

A single character string indicating the text to display. If NULL the title is not shown. If waiver() (default), the name of the scale or the name specified in labs() is used for the tyle.

style

Either a style_set to override style sets inherited from the theme, or a style for styling the labels specifically. For colour or fill scales, the color, background and border style properties are overridden when set as NULL, see examples.

detect

Either FALSE to typeset entirely through syntax or TRUE to automatically detect labels and apply.

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 string indicating where the legend should be placed relative to the plot panels.

override.aes

A list specifying aesthetic parameters of the legend keys. See details and examples in ?guide_legend.

order

positive integer less than 99 that specifies the order of this guide among multiple guides. This controls the order in which multiple guides are displayed, not the contents of the guide itself. If 0 (default), the order is determined by a secret algorithm.

Text formatting

In addition to standard marquee syntax, there is additional syntax to make building a guide easier. In the text below, n marks the n-th break in the scale, label represents any of the scale's labels and foo represents arbitrary text.

• <<n>> or <<label>> can be used to insert key glyphs into the text.

• ![](n) or ![](label) can also be used to insert key glyphs into the text.

• {.n foo} or {.label foo} applies the style argument to foo, including recoloring when the guide represents a colour or fill scale.

• !!n or !!label translates to {.label label} to insert the label verbatim with the application of the style argument.

Examples

if (FALSE) { # rlang::is_installed("ggplot2", version = "3.5.0")
library(ggplot2)
# A standard plot
base <- ggplot(mpg, aes(displ, hwy)) +
  geom_point()

# Using key glyphs
base + aes(shape = drv) +
  scale_shape_discrete(
    # Same as using <<1>>, <<2>> and <<3>>,
    # or ![](1), ![](2) and ![](3)
    # or ![](4), ![](f) and ![](r)
    name = "Cars with four wheel <<4>>, forward <> or reverse <> drive.",
    guide = "marquee"
  )

# Recolouring text
base <- base +
  aes(colour = drv) +
  labs(
    colour = "Cars with {.4 four wheel}, {.f forward} or {.r reverse} drive."
  )
base + guides(colour = "marquee")

# Adjust display of labels
st <- style(weight = "bold", italic = TRUE, background = NA)
base + guides(colour = guide_marquee(style = st))

# Using background instead of text colour by setting it to NULL
st <- style(color = "black", background = NULL)
base + guides(colour = guide_marquee(style = st))

# Customising style of each label through style sets
# Note: tag names must be universal per `vctrs::vec_as_names` and
# prefixed with `lab_`.
st <- classic_style()
st <- modify_style(st, tag = "lab_f", background = NULL, color = "black")
st <- modify_style(st, tag = "lab_r", border_size = trbl(1),
                   color = "black", background = NA)
base + guides(colour = guide_marquee(style = st))

# Alternatively:
base + guides(colour = "marquee") +
  theme(plot.subtitle = element_marquee(style = st))

# Splicing in labels by number (!!2) or label (!!subcompact)
base + aes(colour = class) +
  labs(colour = "Cars including !!2 and !!subcompact vehicles") +
  guides(colour = "marquee")

# Using automatic detection
base + aes(colour = class) +
  labs(colour = "Cars including suv and minivan vehicles") +
  guides(colour = guide_marquee(detect = TRUE))
}