Package 'legendry'

Description

These functions construct various sorts of brackets. They construct a matrix that can be supplied as the bracket argument in primitive_bracket().

Usage

bracket_line()

bracket_square()

bracket_chevron()

bracket_round(angle = 180, n = 100L)

bracket_sigmoid(curvature = 10, n = 100L)

bracket_atan(curvature = 5, n = 100L)

bracket_curvy(angle = 225, n = 100L)

Arguments

Details

When designing custom bracket shapes, the expectation is both columns are are a number between 0 and 1. The first column follows the direction of the guide whereas the second column is orthogonal to that direction.

Value

A ⁠<matrix[n, 2]>⁠ with coordinates for points on the brackets.

Functions

• bracket_line(): A simple line as bracket. Has n = 2 points.

• bracket_square(): A square bracket. Has n = 4 points.

• bracket_chevron(): A chevron (V-shape) that makes a bracket. Has n = 3 points.

• bracket_round(): One circular arc that makes a bracket.

• bracket_sigmoid(): Two sigmoid curves stacked on top of one another to form a bracket.

• bracket_atan(): Two arctangent curves stacked on top of one another to form a bracket.

• bracket_curvy(): Four circular arcs that make a bracket.

Examples

plot(bracket_sigmoid(), type = 'l')

Description

These functions construct various sorts of caps. They construct a matrix that can be supplied as the shape argument in gizmo_barcap().

Usage

cap_triangle()

cap_round(n = 100L)

cap_arch(n = 100L)

cap_ogee(n = 100L)

cap_none()

Arguments

Details

When designing custom cap shapes, the expectation is that the first point starts at the ⁠(0, 0)⁠ coordinate and the last point ends at the ⁠(0, 1)⁠ coordinate. The first column follows the orthogonal direction of the bar whereas the second column follows the direction of the bar.

Value

A ⁠<matrix[n, 2]>⁠ with coordinates for points on the brackets.

Functions

• cap_triangle(): An equilateral triangle with n = 3 points.

• cap_round(): A semicircle.

• cap_arch(): Two circular arcs forming an equilateral Gothic arch.

• cap_ogee(): Four circular arcs forming an 'ogee' arch.

• cap_none(): No cap.

Examples

plot(cap_arch(), type = 'l')

Description

This guide composition has a central guide optionally surrounded by other guides on all four sides.

Usage

compose_crux(
  key = NULL,
  centre = "none",
  left = "none",
  right = "none",
  top = "none",
  bottom = "none",
  args = list(),
  complete = FALSE,
  theme = NULL,
  theme_defaults = list(),
  reverse = FALSE,
  order = 0L,
  title = waiver(),
  position = waiver(),
  available_aes = NULL
)

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide.

There are no further styling options.

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

compose_crux(theme = theme_guide(
  title = element_text(),
  title.position = "top",
  text.position = "right",
  margin = margin(5),
  background = element_rect()
))

Value

A ⁠<ComposeCrux>⁠ guide object.

See Also

Other composition: compose_ontop(), compose_sandwich(), compose_stack(), guide-composition

Examples

# Roughly recreating a colour bar with extra text on top and bottom
crux <- compose_crux(
  centre = gizmo_barcap(), left = "axis_base",
  right = "axis_base",
  top = primitive_title("A lot"),
  bottom = primitive_title("A little")
)

ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = cty)) +
  guides(colour = crux)

Description

This guide can place other guides on top of one another.

Usage

compose_ontop(
  ...,
  args = list(),
  key = NULL,
  title = waiver(),
  angle = waiver(),
  theme = NULL,
  order = 0L,
  position = waiver(),
  available_aes = NULL
)

Arguments

Details

Styling options

There are no styling options in theme() for this composition.

Value

A ⁠<ComposeOntop>⁠ composite guide object.

See Also

Other composition: compose_crux(), compose_sandwich(), compose_stack(), guide-composition

Examples

# Using the ontop composition to get two types of ticks with different
# lengths
ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  guides(x = compose_ontop(
    guide_axis_base(
      key_manual(c(2, 4, 6)),
      theme = theme(
        axis.ticks = element_line(colour = "limegreen"),
        axis.ticks.length = unit(11, "pt")
      )
    ),
    guide_axis_base(
      key_manual(c(3, 5, 7)),
      theme = theme(
        axis.ticks = element_line(colour = "tomato"),
        axis.ticks.length = unit(5.5, "pt")
      )
    )
  ))

Description

This guide composition has a middle guide flanked by two parallel guides.

Usage

compose_sandwich(
  key = key_auto(),
  middle = gizmo_barcap(),
  text = "none",
  opposite = "none",
  args = list(),
  suppress_labels = "opposite",
  complete = TRUE,
  theme = NULL,
  theme_defaults = list(),
  reverse = FALSE,
  order = 0L,
  title = waiver(),
  position = waiver(),
  available_aes = NULL
)

Arguments

Details

The sandwich composition is effectively the same as a crux composition lacking two opposing arms.

Styling options

Below are the theme options that determine the styling of this guide.

There are no further styling options.

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

compose_sandwich(theme = theme_guide(
  title = element_text(),
  title.position = "top",
  text.position = "right",
  margin = margin(5),
  background = element_rect()
))

Value

A ⁠<ComposeSandwich>⁠ guide object.

See Also

Other composition: compose_crux(), compose_ontop(), compose_stack(), guide-composition

Examples

# A standard plot with a sandwich guide
ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = cty)) +
  guides(colour = compose_sandwich(
    middle = "colourbar",
    text = "axis_base",
    opposite = primitive_bracket(key = key_range_manual(
      start = c(10, 20), end = c(25, 30), name = c("A", "B")
    ))
  ))

Description

This guide can stack other guides.

Usage

compose_stack(
  ...,
  args = list(),
  key = NULL,
  title = waiver(),
  side.titles = waiver(),
  angle = waiver(),
  theme = NULL,
  order = 0L,
  drop = NULL,
  position = waiver(),
  available_aes = NULL
)

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide.

There are no further styling options.

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

compose_stack(theme = theme_guide(
  subtitle = element_text(),
  subtitle.position = "left",
  guide.spacing = unit(5, "mm")
))

Value

A ⁠<ComposeStack>⁠ guide object.

See Also

Other composition: compose_crux(), compose_ontop(), compose_sandwich(), guide-composition

Examples

ggplot() +
  geom_function(fun = dnorm, xlim = c(-3, 3)) +
  guides(x = compose_stack(
    "axis", "axis",
    side.titles = c("first", "second")
  )) +
  # Add margin to make room for side titles
  theme(plot.margin = margin(5.5, 5.5, 5.5, 11))

Description

This guide displays a colour bar with optional caps at either ends of the bar.

Usage

gizmo_barcap(
  key = "sequence",
  shape = "triangle",
  size = NULL,
  show = NA,
  alpha = NA,
  oob = "keep",
  theme = NULL,
  position = waiver(),
  direction = NULL
)

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide. Note that the width or height (depending on the direction argument) includes the cap.

Please note that depending on the direction argument, the legend.key.width/legend.key.height setting are expanded 5-fold if originating from the global theme. To set these directly, you can use the local theme argument in the guide. These settings have shorthands in theme_guide():

gizmo_barcap(theme = theme_guide(
  frame = element_rect(),
  key.width = unit(5, "mm")
  key.height = unit(5, "cm")
))

Value

A ⁠<GizmoBarcap>⁠ object.

See Also

Other gizmos: gizmo_density(), gizmo_grob(), gizmo_histogram(), gizmo_stepcap()

Examples

# A standard plot
p <- ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point()

# Just a bar
p + scale_colour_viridis_c(guide = gizmo_barcap())

# Caps show up when there is data outside the limits
p + scale_colour_viridis_c(
  limits = c(10, 30),
  guide  = gizmo_barcap()
)

# The scale's out-of-bounds handler determines cap colour
p + scale_colour_viridis_c(
  limits = c(10, 30), oob = scales::oob_squish,
  guide = gizmo_barcap()
)

# Customising display of the guide
p +
  scale_colour_viridis_c(
    oob = scales::oob_squish,
    guide = gizmo_barcap(
      shape = "arch", show = c(FALSE, TRUE),
      size = unit(2, "cm"),
      theme = theme(legend.key.height = unit(4, "cm"))
    )
  ) +
  theme(
    legend.frame = element_rect(colour = "black"),
    legend.key.width = unit(0.5, "cm")
  )

Description

This guide displays a kernel density estimate (KDE) of the aesthetic. If the aesthetic is colour or fill, the shape will reflect this.

Usage

gizmo_density(
  key = waiver(),
  density = NULL,
  density.args = list(),
  density.fun = stats::density,
  just = 0.5,
  oob = "keep",
  alpha = NA,
  theme = NULL,
  position = waiver(),
  direction = NULL
)

Arguments

Details

Non-finite values such as NA and NaN are ignored while infinite values such as -Inf and Inf are squished to the limits.

Styling options

Below are the theme options that determine the styling of this guide.

Please note that depending on the direction argument, the legend.key.width/legend.key.height setting are expanded 5-fold if originating from the global theme. To set these directly, you can use the local theme argument in the guide. These settings have shorthands in theme_guide():

gizmo_density(theme = theme_guide(
  frame = element_rect(),
  key = element_rect(),
  key.width = unit(5, "mm")
  key.height = unit(5, "cm")
))

Value

A ⁠<GizmoDensity>⁠ object.

See Also

Other gizmos: gizmo_barcap(), gizmo_grob(), gizmo_histogram(), gizmo_stepcap()

Examples

# A standard plot
p <- ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point() +
  scale_colour_viridis_c()

# Density from plot data
p + guides(colour = gizmo_density())

# Using bins instead of gradient
p + guides(colour = gizmo_density("bins"))

# Providing custom values to compute density of
p + guides(colour = gizmo_density(density = runif(1000, min = 5, max = 35)))

# Providing a precomputed density
p + guides(colour = gizmo_density(density = density(mpg$cty, adjust = 0.5)))

# Alternatively, parameters may be passed through density.args
p + guides(colour = gizmo_density(density.args = list(adjust = 0.5)))

Description

This guide displays a user-provided grob.

Usage

gizmo_grob(
  grob,
  width = grobWidth(grob),
  height = grobHeight(grob),
  hjust = 0.5,
  vjust = 0.5,
  position = waiver()
)

Arguments

Details

Styling options

There are no theme() styling options for gizmo_grob().

Value

A ⁠<GizmoGrob>⁠ object.

See Also

Other gizmos: gizmo_barcap(), gizmo_density(), gizmo_histogram(), gizmo_stepcap()

Examples

circle <- grid::circleGrob()

# A standard plot with grob gizmos
ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point() +
  guides(
    x.sec = gizmo_grob(
      circle, hjust = 0.75,
      width = unit(2, "cm"), height = unit(2, "cm")
    ),
    colour = gizmo_grob(
      circle, width = unit(1, "cm"), height = unit(1, "cm")
    )
  )

Description

This guide displays a histogram of the aesthetic. If the aesthetic is colour or fill, the shape will reflect this.

Usage

gizmo_histogram(
  key = waiver(),
  hist = NULL,
  hist.args = list(),
  hist.fun = graphics::hist,
  just = 1,
  oob = oob_keep,
  metric = "counts",
  alpha = NA,
  theme = NULL,
  position = waiver(),
  direction = NULL
)

Arguments

Details

Non-finite values such as NA and NaN are ignored while infinite values such as -Inf and Inf are squished to the limits.

Styling options

Below are the theme options that determine the styling of this guide.

Please note that depending on the direction argument, the legend.key.width/legend.key.height setting are expanded 5-fold if originating from the global theme. To set these directly, you can use the local theme argument in the guide. These settings have shorthands in theme_guide():

gizmo_histogram(theme = theme_guide(
  frame = element_rect(),
  key = element_rect(),
  key.width = unit(5, "mm")
  key.height = unit(5, "cm")
))

Value

A ⁠<GizmoHistogram>⁠ object.

See Also

Other gizmos: gizmo_barcap(), gizmo_density(), gizmo_grob(), gizmo_stepcap()

Examples

# A standard plot
p <- ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point() +
  scale_colour_viridis_c()

# Histogram from plot data
p + guides(colour = gizmo_histogram())

# Using bins instead of gradient
p + guides(colour = gizmo_histogram("bins"))

# Providing custom values to compute histogram
p + guides(colour = gizmo_histogram(hist = runif(1000, min = 5, max = 35)))

# Providing precomputed histogram
p + guides(colour = gizmo_histogram(hist = hist(mpg$cty, breaks = 10)))

# Alternatively, parameters may be passed through hist.args
p + guides(colour = gizmo_histogram(hist.arg = list(breaks = 10)))

Description

This guide displays a binned variant of the colour bar with optional caps at either ends of the bar.

Usage

gizmo_stepcap(
  key = "bins",
  shape = "triangle",
  size = NULL,
  show = NA,
  alpha = NA,
  oob = "keep",
  theme = NULL,
  position = waiver(),
  direction = NULL
)

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide. Note that the width or height (depending on the direction argument) includes the cap.

Please note that depending on the direction argument, the legend.key.width/legend.key.height setting are expanded 5-fold if originating from the global theme. To set these directly, you can use the local theme argument in the guide. These settings have shorthands in theme_guide():

gizmo_stepcap(theme = theme_guide(
  frame = element_rect(),
  key.width = unit(5, "mm")
  key.height = unit(5, "cm")
))

Value

A GizmoStepcap object.

See Also

Other gizmos: gizmo_barcap(), gizmo_density(), gizmo_grob(), gizmo_histogram()

Examples

# A standard plot
p <- ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point()

# Just some recangles
p + scale_colour_viridis_c(guide = gizmo_stepcap())

# Caps show up when there is data outside the limits
p + scale_colour_viridis_c(
  limits = c(10, 30),
  guide = gizmo_stepcap()
)

# The scale's out-of-bounds handler determines cap colour
p + scale_colour_viridis_c(
  limits = c(10, 30), oob = scales::oob_squish,
  guide = gizmo_stepcap()
)

# Customising the display of the guide
p +
  scale_colour_viridis_c(
    oob = scales::oob_squish,
    guide = gizmo_stepcap(
      shape = "round", show = c(FALSE, TRUE),
      size = unit(1, "cm"),
      theme = theme(legend.key.height = unit(4, "cm"))
    )
  ) +
  theme(
    legend.frame = element_rect(colour = "black"),
    legend.key.width = unit(0.5, "cm")
  )

Description

This axis guide acts as annotation: it draws labels at specified places. It also wraps an inner guide, making the behaviour look like one is 'adding' the annotation on top of the regular guide.

Usage

guide_axis_annotation(
  aesthetic,
  label = as.character(aesthetic),
  ...,
  key = NULL,
  arrow = NULL,
  inner = waiver(),
  title = waiver(),
  theme = NULL,
  order = 0L,
  position = waiver(),
  call = NULL
)

annotate_top(..., position = "top")

annotate_right(..., position = "right")

annotate_bottom(..., position = "bottom")

annotate_left(..., position = "left")

Arguments

Details

Under the hood, this guide is a hybrid composition guide. The theme() options that govern the styling are partially determined by its consituents. They are linked below so you can find their 'Styling options' sections.

| Constituent | Description | | compose_ontop() | Composes the annotation on top of the inner guide | | guide_axis_base() | The default inner guide | | primitive_ticks() | Display of the annotation ticks | | primitive_labels() | Display of the annotation labels |

Styling options per annotation can be set via ... as described above.

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

# Note that `theme` is used *only* for the annotation
guide_axis_annotation(theme = theme_guide(
  text = element_text(),
  ticks = element_line(),
  ticks.length = unit(5, "mm")
))

Value

A ⁠<Guide>⁠ object

See Also

Other standalone guides: 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_cross(), guide_legend_group(), guide_legend_manual()

Examples

# Basic plot
p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point()

# Typical use
p +
  annotate_top(5, face = "bold") +
  annotate_bottom(c(2.5, 4.5), c("Bottom annotation", "Second label"))

# If you want to combine them with secondary axes, you must
# set the `inner` argument manually.
p +
  scale_y_continuous(
    sec.axis = dup_axis(breaks = c(15, 25, 35))
  ) +
  annotate_right(30, inner = "axis")

# Use in theta axis
p + coord_radial() +
  guides(theta = guide_axis_annotation(4.5, "Theta annotation"))

# Specialised use as part of other guides
# Note that `guide_colbar` imposes white inward ticks
# We can overrule these impositions with a replacement theme
p + aes(colour = cty) +
  guides(colour = guide_colbar(
    second_guide = guide_axis_annotation(22, "This", theme = theme_gray())
  ))

Description

This axis guide is a visual representation of position scales and can represent the x, y, theta and r aesthetics. It differs from guide_axis() in that it can accept custom keys and is can act as an axis for coord_radial() like guide_axis_theta().

Usage

guide_axis_base(
  key = NULL,
  title = waiver(),
  subtitle = NULL,
  theme = NULL,
  n.dodge = 1L,
  check.overlap = FALSE,
  angle = waiver(),
  cap = "none",
  bidi = FALSE,
  order = 0L,
  position = waiver()
)

Arguments

Details

Under the hood, this guide is a stack composition of a line, ticks and labels primitives.

To set minor ticks, use key = "minor", or use the type argument in key_manual() or key_map().

To use this as a logarithmic axis, set key = "log".

Styling options

Because this guide is pure composite guide, the theme options that govern the styling are determined by its constituents. They are linked below so you can find their 'Styling options' sections.

Styling options per break can be set in the standard key. These override theme settings.

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

guide_axis_base(theme = theme_guide(
  # Common options
  line = element_line(),
  text = element_text(),
  ticks = element_line(),
  ticks.length = unit(5, "mm"),

  # Niche options below
  minor.ticks = element_line(),
  minor.ticks.length = unit(5, "mm"),
  mini.ticks = element_line(),
  mini.ticks.length = unit(5, "mm"),
))

Value

A ⁠<Guide>⁠ object.

See Also

Other standalone guides: guide_axis_annotation(), 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_cross(), guide_legend_group(), guide_legend_manual()

Examples

# A standard plot with custom keys
p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  scale_x_continuous(
    guide = guide_axis_base(key = key_minor())
  ) +
  scale_y_continuous(
    guide = guide_axis_base(key = key_manual(c(20, 25, 30, 40)))
  )
p

# Is translated to theta axis without fuss
p + coord_radial()

# To use as logarithmic axis:
ggplot(msleep, aes(bodywt, brainwt)) +
  geom_point(na.rm = TRUE) +
  scale_x_continuous(
    transform = "log10",
    guide = guide_axis_base("log")
  )

Description

This axis is a speciality axis for discrete data that has been hierarchically clustered. Please be aware that the guide cannot affect the scale limits, which should be set appropriately. This guide will give misleading results when this step is skipped!

Usage

guide_axis_dendro(
  key = "dendro",
  title = waiver(),
  theme = NULL,
  labels = TRUE,
  space = rel(10),
  vanish = TRUE,
  n.dodge = 1L,
  angle = waiver(),
  check.overlap = FALSE,
  ticks = "none",
  axis_line = "none",
  order = 0L,
  position = waiver()
)

Arguments

Details

Styling options

Because this guide is pure composite guide, the theme options that govern the styling are determined by its constituents. They are linked below so you can find their 'Styling options' sections.

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

guide_axis_dendro(theme = theme_guide(
  line = element_line(),
  text = element_text(),
  ticks = element_line(),
  ticks.length = unit(5, "mm"),
))

Value

A ⁠<Guide>⁠ object.

See Also

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

Examples

# Hierarchically cluster data
clust <- hclust(dist(scale(mtcars)), "ave")

# Using the guide along with appropriate limits
p <- ggplot(mtcars, aes(disp, rownames(mtcars))) +
  geom_col() +
  scale_y_discrete(limits = clust$labels[clust$order])

# Standard usage
p + guides(y = guide_axis_dendro(clust))

# Adding ticks and axis line
p +
  guides(y = guide_axis_dendro(clust, ticks = "ticks", axis_line = "line")) +
  theme(axis.line = element_line())

# Controlling space allocated to dendrogram
p + guides(y = guide_axis_dendro(clust, space = unit(4, "cm"))) +
  theme(axis.ticks.y.left = element_line("red"))

# If want just the dendrogram, use `labels = FALSE`
p + guides(y = guide_axis_dendro(clust, labels = FALSE), y.sec = "axis")

Description

This axis guide gives extra range annotations to position scales. It can be used to infer nesting structure from labels or annotate ranges.

Usage

guide_axis_nested(
  key = "range_auto",
  regular_key = "auto",
  type = "bracket",
  title = waiver(),
  subtitle = NULL,
  theme = NULL,
  angle = waiver(),
  cap = "none",
  bidi = FALSE,
  oob = "squish",
  drop_zero = TRUE,
  pad_discrete = NULL,
  levels_text = NULL,
  ...,
  order = 0L,
  position = waiver()
)

Arguments

Details

To offer other keys the opportunity to display ranges alongside regular-looking labels, the regular_key argument can be used to setup a separate key for display in between the ticks and ranges.

By default, the key = "range_auto" will incorporate the 0th level labels inferred from the scale's labels. These labels will look like regular labels.

Styling options

Because this guide is pure composite guide, the theme options that govern the styling are determined by its constituents. They are linked below so you can find their 'Styling options' sections.

Styling options per range can be set in the range key. These override theme settings.

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

guide_axis_nested(theme = theme_guide(
  # Common options
  line = element_line(),
  text = element_text(),
  ticks = element_line(),
  ticks.length = unit(5, "mm"),

  # For brackets
  bracket = element_line(),
  bracket.size = unit(5, "mm"),

  # For boxes
  box = element_rect(),

  # For fences
  fence = element_line(),
  fence.post = element_line(),
  fence.rail = element_line(),

  # For subtitle (not main title)
  title = element_text()
))

Value

A ⁠<Guide>⁠ object.

See Also

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

Examples

# A plot with nested categories on the x-axis
p <- ggplot(mpg, aes(interaction(drv, cyl), hwy)) +
  geom_boxplot()

p + guides(x = "axis_nested")

# Apply styling to brackets
p + guides(x = "axis_nested") +
  theme_guide(bracket = element_line("red", linewidth = 1))

# Don't drop nesting indicators that have 0-width
p + guides(x = guide_axis_nested(drop_zero = FALSE))

# Change additional padding for discrete categories
p + guides(x = guide_axis_nested(pad_discrete = 0))

# Change bracket type
p + guides(x = guide_axis_nested(bracket = "curvy"))

# Use boxes instead of brackets + styling of boxes
p + guides(x = guide_axis_nested(type = "box")) +
  theme_guide(box = element_rect("limegreen", "forestgreen"))

# Using fences instead of brackets + styling of fences
p + guides(x = guide_axis_nested(type = "fence", rail = "inner")) +
  theme_guide(
    fence.post = element_line("tomato"),
    fence.rail = element_line("dodgerblue")
  )

# Use as annotation of a typical axis
# `regular_key` controls display of typical axis
ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  guides(x = guide_axis_nested(
    key = key_range_manual(
      start = 2:3,
      end = 5:6,
      name = c("First", "Second")
    ),
    regular_key = key_manual(c(2, 2.5, 3, 5, 7))
  ))

Description

Displays an axis-sharing plot to the side of the panel.

Usage

guide_axis_plot(
  plot,
  title = NULL,
  size = unit(2, "cm"),
  reposition = TRUE,
  theme = theme_sub_legend(position = "none"),
  position = waiver()
)

Arguments

Details

This guide is subject to the following limitations:

• The x- or y-scale of the main plot override the corresponding scale in the plot argument. This ensures that the scales line up. The plot argument should not have the relevant scale.

• The plot argument cannot have custom facets. It must use the default facet_null().

• This guide cannot be used in non-linear coordinate systems of the main plot and does not support non-linear coordinate systems in the plot argument.

• The theme(panel.widths, panel.heights) setting in the plot argument will be ignored in favour of the size argument.

• There is no mechanism to accommodate extra space needed by plot components outside the panel. This applies in the horizontal direction for x-axes and the vertical direction for y-axes. You may need to manually tweak the theme(plot.margin) setting of the main plot to accommodate these components.

Styling options

This guide has no style options in theme() on itself. However, the plot herein is subject to styling as described under the theme argument.

Value

A ⁠<Guide>⁠ object.

See Also

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

Examples

# A standard plot
main_plot <- ggplot(mpg, aes(displ, hwy, colour = drv)) +
  geom_point()

# Simple plot sharing the x-variable
x_plot <- ggplot(mpg, aes(displ, fill = drv)) +
  geom_density(alpha = 0.7)

# Simple plot sharing the y-variable
y_plot <- ggplot(mpg, aes(drv, hwy, colour = drv)) +
  geom_boxplot()

# Typical use
main_plot + guides(
  x = guide_axis_plot(x_plot),
  y = guide_axis_plot(y_plot)
)

main_plot + guides(
  # Include `fill` legend by overriding theme
  x = guide_axis_plot(x_plot, theme = NULL),
  # Change the size of the side-plot
  y = guide_axis_plot(y_plot, size = unit(4, "cm"))
)

# Components outside panels may need to be manually acommodated
main_plot +
  guides(y = guide_axis_plot(y_plot + labs(title = "Boxplot"))) +
  theme(plot.margin = margin(25, 5.5, 5.5, 5.5))

# Recursive use of this guide
main_plot + guides(x = guide_axis_plot(
  main_plot + guides(x = guide_axis_plot(x_plot))
))

Description

These axis guides can be used for set annotations of discrete categories. The upset guide displays set intersections in matrix and is can be used to replace Venn/Euler diagrams. The symbol guide also displays a matrix of symbols, but requires manually specifying them.

Usage

guide_axis_symbols(
  key = NULL,
  connect = NULL,
  title = waiver(),
  theme = NULL,
  override.aes = list(),
  position = waiver(),
  direction = NULL,
  call = NULL
)

guide_axis_upset(
  key = "upset",
  connect = "perpendicular",
  title = waiver(),
  theme = NULL,
  override.aes = list(),
  position = waiver(),
  direction = NULL,
  call = NULL
)

Arguments

Details

The upset axis does not predetermine the order the categories. If any sorting based on set size needs to occur, the scale is the correct tool to handle this task.

Styling options

Several styling options are provided in the theme, while individualised styling is discussed below the table.

Moreover, styling options per group of symbols can be set via the override.aes argument. These override theme settings.

Styling options per symbol can be set in key_symbols() via the ... argument. These override theme settings and 'per group' settings.

Styling options per line in line connectors can be set by including graphical parameters as columns in the ⁠connect = <data.frame>⁠ argument. These override theme settings.

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

guide_axis_symbols(theme = theme_guide(
  subtitle = element_line(),
  subtitle.position = "left",
  zebra.light = element_rect(),
  zebra.dark = element_rect(),
  table.spacing = unit(5, "mm"),
  point = element_point(),
  connector = element_line()
))

Value

A ⁠<Guide>⁠ object.

See Also

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

Examples

# Example plot
p <- ggplot(mpg, aes(paste(drv, year))) +
  geom_bar()

# A standard upset axis might not have right order of levels
p + guides(x = "axis_upset")

# The levels can be manually adjusted to taste
p + guides(x = guide_axis_upset(c("1999", "2008", "4", "f", "r")))

# The connections can be turned off to just show symbols
p + guides(x = guide_axis_upset(connect = NULL))

# The style can be changed per group of symbols.
# We need to give 3 colours to also cover NA-breaks
p + guides(x = guide_axis_upset(
  override.aes = list(colour = c("purple", "orange", NA))
))

# For symbol guides you have to manually specify where you want symbols and
# connection lines appear.
p + guides(x = guide_axis_symbols(
  key_symbols(
    aesthetic = c("4 1999", "4 2008", "r 1999"),
    level = c("Lvl 1", "Lvl 2", "Lvl 3")
  ),
  connect = data.frame(
    value_start = "4 2008", value_end = "r 1999",
    level_start = 2, level_end = 3
  )
))

Description

This guide displays the sizes of points as a series of circles. It is typically paired with geom_point() with draw_key_point() glyphs.

Usage

guide_circles(
  key = NULL,
  title = waiver(),
  theme = NULL,
  hjust = 0.5,
  vjust = 0,
  text_position = NULL,
  clip_text = FALSE,
  override.aes = list(shape = 1L),
  position = waiver(),
  direction = NULL
)

Arguments

Details

Please note that the default size scales scale to area, not radius, so equidistant breaks will appear at irregularly spaced positions due to labelling the diameter of a circle.

This graph was designed with standard round shapes in mind, i.e. shapes 1, 16, 19 and 21. For that reason, shape = 1 is the default override.aes argument. Other shapes will probably be drawn but the quality of their alignment and label placement may be unsatisfactory.

Styling options

Below are the theme options that determine the styling of this guide.

Styling options per break can be set in the standard key. These override theme settings.

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

guide_circles(theme = theme_guide(
  text = element_text(),
  title = element_text(),
  title.position = "top",
  margin = margin(5),
  key = element_rect(),
  key.margin = margin(5),
  background = element_rect(),
  ticks = element_line(),
))

Value

A ⁠<GuideCircles>⁠ object.

See Also

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

Examples

# A standard plot
p <- ggplot(mtcars, aes(disp, mpg)) +
  geom_point(aes(size = hp), alpha = 0.3)

# By default, the sizes aren't large enough to make this guide clear
p + scale_size_area(guide = "circles")

# Update with a more approrpriate scale
p <- p +
  scale_size_area(
    max_size = 30,
    limits = c(0, NA),
    breaks = c(0, 25, 100, 250)
  )
p + guides(size = "circles")

# Horizontal orientation
p + guides(size = guide_circles(
  vjust = 0.5, hjust = 0, text_position = "bottom"
))

# Alternative text placement
p + guides(size = guide_circles(
  text_position = "ontop",
  clip_text = TRUE
))

# More styling options
p + guides(size = guide_circles(override.aes = aes(colour = "red")))+
  theme(
    # Key background
    legend.key = element_rect(colour = "black", fill = 'white'),
    # Padding around central shapes
    legendry.legend.key.margin = margin(1, 1, 1, 1, "cm"),
    legend.ticks = element_line(colour = "blue"),
    legend.text.position = "left"
  )

Description

Similar to guide_colourbar(), this guide displays continuous colour or fill aesthetics. It has additional options to display caps at the end of the bar, depending on out-of-bounds values.

Usage

guide_colbar(
  title = waiver(),
  key = "auto",
  first_guide = "axis_base",
  second_guide = first_guide,
  shape = "triangle",
  size = NULL,
  show = NA,
  nbin = 15L,
  alpha = NA,
  reverse = FALSE,
  suppress_labels = "second",
  oob = scales::oob_keep,
  theme = NULL,
  vanilla = TRUE,
  position = waiver(),
  available_aes = c("colour", "fill")
)

Arguments

Details

As colours are always rendered as gradients, it is important to use a graphics device that can render these. This can be checked by using check_device("gradients").

Styling options

Because this guide is pure composite guide, the theme options that govern the styling are determined by its constituents. They are linked below so you can find their 'Styling options' sections. Note that guide_axis_base() is just a default that can be swapped out.

Styling options per break can be set in the standard key. These override theme settings.

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

guide_colbar(theme = theme_guide(
  # Composition settings
  title = element_text(),
  title.position = "top",
  text.position = "right",
  margin = margin(5),
  background = element_rect(),

  # Bar settings
  frame = element_rect(),
  key.width = unit(5, "mm")
  key.height = unit(5, "cm")

  # Common options for `guide_axis_base()`
  line = element_line(),
  text = element_text(),
  ticks = element_line(),
  ticks.length = unit(5, "mm"),
))

Value

A ⁠<Guide>⁠ object

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_colring(), guide_colsteps(), guide_legend_base(), guide_legend_cross(), guide_legend_group(), guide_legend_manual()

Examples

# A standard plot
p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = cty))

# The colourbar shows caps when values are out-of-bounds (oob)
p + scale_colour_viridis_c(
  limits = c(10, NA),
  guide = "colbar"
)

# It also shows how oob values are handled
p + scale_colour_viridis_c(
  limits = c(10, NA), oob = scales::oob_squish,
  guide = "colbar"
)

# Adjusting the type of cap
p + scale_colour_viridis_c(
  limits = c(10, 30), oob = scales::oob_squish,
  guide = guide_colbar(shape = "round")
)

# One-sided ticks
p + scale_colour_viridis_c(
  guide = guide_colbar(second_guide = "none")
)

# Colour bar with minor breaks
p + scale_colour_viridis_c(
  minor_breaks = scales::breaks_width(1),
  guide = guide_colbar(key = "minor")
)

# Using log ticks on a colourbar
ggplot(msleep, aes(sleep_total, sleep_rem)) +
  geom_point(aes(colour = bodywt), na.rm = TRUE) +
  scale_colour_viridis_c(
    transform = "log10",
    guide = guide_colbar(key = "log")
  )

Description

Similar to guide_colourbar(), this guide displays continuous colour or fill aesthetics. Instead of a bar, the gradient in shown in a ring or arc, which can be convenient for cyclical palettes such as some provided in the scico package.

Usage

guide_colring(
  title = waiver(),
  key = "auto",
  start = 0,
  end = NULL,
  outer_guide = "axis_base",
  inner_guide = "axis_base",
  nbin = 300L,
  reverse = FALSE,
  show_labels = "outer",
  theme = NULL,
  vanilla = TRUE,
  position = waiver(),
  available_aes = c("colour", "fill"),
  ...
)

Arguments

Details

Styling options

This guide is a hybrid composition guide, where the theme settings apply both this guide itself and the constituents it manages. The constituents are linked below so you can find their 'Styling options' sections. Note that guide_axis_base() is just a default that can be swapped out.

In addition to the constituent's theme setting, it also has the following settings:

Styling options per break can be set in the standard key. These override theme settings.

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

guide_colring(theme = theme_guide(
  # Ring settings
  title = element_text(),
  title.position = "top",
  margin = margin(5),
  background = element_rect(),
  frame = element_rect(),
  key.size = unit(1, "cm"),
  key.width = unit(5, "mm"),

  # Common options for `guide_axis_base()`
  line = element_line(),
  text = element_text(),
  ticks = element_line(),
  ticks.length = unit(5, "mm"),
))

Value

A ⁠<Guide>⁠ object.

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_colsteps(), guide_legend_base(), guide_legend_cross(), guide_legend_group(), guide_legend_manual()

Examples

# Rings works best with a cyclical palette
my_pal <- c("black", "tomato", "white", "dodgerblue", "black")

p <- ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point() +
  scale_colour_gradientn(colours = my_pal)

# Standard colour ring
p + guides(colour = "colring")

# As an arc
p + guides(colour = guide_colring(
  start = 1.25 * pi, end = 2.75 * pi
))

# Removing the inner tick marks
p + guides(colour = guide_colring(inner_guide = "none"))

# Include labels on the inner axis
p + guides(colour = guide_colring(show_labels = "both"))

# Passing an argument to inner/outer guides
p + guides(colour = guide_colring(angle = 0))

Description

Similar to guide_coloursteps(), this guide displays continuous colour or fill aesthetics. It has additional options to display caps at the end of the bar, depending on out-of-bounds values.

Usage

guide_colsteps(
  title = waiver(),
  key = "bins",
  first_guide = "axis_base",
  second_guide = "axis_base",
  shape = "triangle",
  size = NULL,
  show = NA,
  alpha = NA,
  reverse = FALSE,
  suppress_labels = "second",
  oob = scales::oob_keep,
  theme = NULL,
  position = waiver(),
  vanilla = TRUE,
  available_aes = c("colour", "fill")
)

Arguments

Details

As steps are rendered as clipped rectangles, it is important to use a graphics device that can render clipped paths. This can be checked by using check_device("clippingPaths").

Styling options

Because this guide is pure composite guide, the theme options that govern the styling are determined by its constituents. They are linked below so you can find their 'Styling options' sections. Note that guide_axis_base() is just a default that can be swapped out.

Styling options per break can be set in the standard key. These override theme settings.

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

guide_colsteps(theme = theme_guide(
  # Composition settings
  title = element_text(),
  title.position = "top",
  text.position = "right",
  margin = margin(5),
  background = element_rect(),

  # Steps settings
  frame = element_rect(),
  key.width = unit(5, "mm")
  key.height = unit(5, "cm")

  # Common options for `guide_axis_base()`
  line = element_line(),
  text = element_text(),
  ticks = element_line(),
  ticks.length = unit(5, "mm"),
))

Value

A ⁠<Guide>⁠ object

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_legend_base(), guide_legend_cross(), guide_legend_group(), guide_legend_manual()

Examples

p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = cty))

# The colour steps show caps when values are out-of-bounds
p + scale_colour_viridis_b(
  limits = c(10, NA),
  guide = "colsteps"
)

# It also shows how oob values are handled
p + scale_colour_viridis_b(
  limits = c(10, 30), oob = scales::oob_censor,
  guide = "colsteps"
)

# Adjusting the type of cap
p + scale_colour_viridis_b(
  limits = c(10, 30),
  guide = guide_colsteps(shape = "round")
)

# The default is to use the breaks as-is
p + scale_colour_viridis_b(
  limits = c(10, 30), breaks = c(10, 20, 25),
  guide = "colsteps"
)

# But the display can be set to use evenly spaced steps
p + scale_colour_viridis_b(
  limits = c(10, 30), breaks = c(10, 20, 25),
  guide = guide_colsteps(key = key_bins(even.steps = TRUE))
)

# Using tick marks by swapping side guides
p + scale_colour_viridis_b(
  guide = guide_colsteps(
    first_guide  = "axis_base",
    second_guide = "axis_base"
  )
)

Description

This legend closely mirrors ggplot2::guide_legend(), but has two adjustments. First, guide_legend_base() supports a design argument for a more flexible layout. Secondly, the legend.spacing.y theme element is observed verbatim instead of overruled.

Usage

guide_legend_base(
  key = NULL,
  title = waiver(),
  theme = NULL,
  design = NULL,
  nrow = NULL,
  ncol = NULL,
  reverse = FALSE,
  override.aes = list(),
  position = NULL,
  direction = NULL,
  order = 0L
)

Arguments

Details

Styling options

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

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

guide_legend_base(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"),
  byrow = TRUE,
  margin = margin(5),
  background = element_rect(),
))

Value

A ⁠<GuideLegend>⁠ object.

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_cross(), guide_legend_group(), guide_legend_manual()

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

Examples

# A dummy plot
p <- ggplot(data.frame(x = 1:3, type = c("tic", "tac", "toe"))) +
  aes(x, x, shape = type) +
  geom_point(na.rm = TRUE) +
  scale_shape_manual(values = c(1, 4, NA))

# A design string, each character giving a cell value.
# Newlines separate rows, white space is ignored.
design <- "
  123
  213
  321
"

# Alternatively, the same can be specified using a matrix directly
# design <- matrix(c(1, 2, 3, 2, 1, 3, 3, 2, 1), 3, 3, byrow = TRUE)

p + guides(shape = guide_legend_base(design = design))

# Empty cells can be created using `#`
design <- "
  #2#
  1#3
"

# Alternatively:
# design <- matrix(c(NA, 1, 2, NA, NA, 3), nrow = 2)

p + guides(shape = guide_legend_base(design = design))

Description

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

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().

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(),
))

Value

A ⁠<GuideLegend>⁠ object.

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")
  )

Description

This legend resembles ggplot2::guide_legend(), but has the ability to keep groups in blocks with their own titles.

Usage

guide_legend_group(
  key = "group_split",
  title = waiver(),
  override.aes = list(),
  nrow = NULL,
  ncol = NULL,
  theme = NULL,
  position = NULL,
  direction = NULL,
  order = 0L
)

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide.

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

guide_legend_group(theme = theme_guide(
  subtitle = element_text(),
  subtitle.position = "top",
  group.spacing = unit(5, "mm"),
  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"),
  byrow = TRUE,
  margin = margin(5),
  background = element_rect(),
))

Value

A ⁠<GuideLegend>⁠ object.

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_cross(), guide_legend_manual()

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

Examples

# Standard plot for selection of `msleep`
df <- msleep[c(9, 28, 11, 5, 34, 54, 64, 24, 53), ]

p <- ggplot(df) +
  aes(bodywt, awake, colour = paste(order, name)) +
  geom_point()

# By default, groups are inferred from the name
p + guides(colour = "legend_group")

# You can also use a look-up table for groups
# The lookup table can be more expansive than just the data:
# We're using the full 'msleep' data here instead of the subset
lut <- key_group_lut(msleep$name, msleep$order)

p + aes(colour = name) +
  guides(colour = guide_legend_group(key = lut))

# `nrow` and `ncol` apply within groups
p + guides(colour = guide_legend_group(nrow = 1))

# Groups are arranged according to `direction`
p + guides(colour = guide_legend_group(ncol = 1, direction = "horizontal")) +
  theme(legend.title.position = "top")

# Customising the group titles
p + guides(colour = "legend_group") +
  theme(
    legendry.legend.subtitle.position = "left",
    legendry.legend.subtitle = element_text(
      hjust = 1, vjust = 1, size = rel(0.9),
      margin = margin(t = 5.5, r = 5.5)
    )
  )

# Changing the spacing between groups
p + guides(colour = "legend_group") +
  theme(legendry.group.spacing = unit(0, "cm"))