Package {legendry}

Title:	Extended Legends and Axes for 'ggplot2'
Version:	0.3.0
Description:	A 'ggplot2' extension that focusses on expanding the plotter's arsenal of guides. Guides in 'ggplot2' include axes and legends. 'legendry' offers new axes and annotation options, as well as new legends and colour displays.
License:	MIT + file LICENSE
URL:	https://teunbrand.github.io/legendry/, https://github.com/teunbrand/legendry
BugReports:	https://github.com/teunbrand/legendry/issues
Depends:	ggplot2 (≥ 4.0.0), R (≥ 4.1.0)
Imports:	cli, grid (≥ 4.1.0), gtable, lifecycle, rlang (≥ 1.2.0), S7, scales (≥ 1.1.1), vctrs (≥ 0.6.0)
Suggests:	knitr, ragg, rmarkdown, svglite, testthat (≥ 3.0.0), vdiffr, withr
Config/testthat/edition:	3
Encoding:	UTF-8
Config/roxygen2/version:	8.0.0
NeedsCompilation:	no
Packaged:	2026-05-12 19:00:54 UTC; Teun
Author:	Teun van den Brand [aut, cre, cph]
Maintainer:	Teun van den Brand <tahvdbrand@gmail.com>
Repository:	CRAN
Date/Publication:	2026-05-13 05:10:25 UTC

legendry: Extended Legends and Axes for 'ggplot2'

Description

A 'ggplot2' extension that focusses on expanding the plotter's arsenal of guides. Guides in 'ggplot2' include axes and legends. 'legendry' offers new axes and annotation options, as well as new legends and colour displays.

Author(s)

Maintainer: Teun van den Brand tahvdbrand@gmail.com (ORCID) [copyright holder]

Authors:

• Teun van den Brand tahvdbrand@gmail.com (ORCID) [copyright holder]

See Also

Useful links:

• https://teunbrand.github.io/legendry/

• https://github.com/teunbrand/legendry

• Report bugs at https://github.com/teunbrand/legendry/issues

ggproto objects in legendry

Description

The legendry package relies on an extension system of ggplot2 through ggproto class objects, which allow cross-package inheritance of objects such as geoms, stats, facets, scales and coordinate systems. For the purpose of making plots, users are invited to wholly ignore these objects, since interacting with these objects is preferred through various constructor functions. The legendry package introduces a new ⁠<Guide>⁠ ggproto class to support variations on axes, legends and colourbars.

See Also

The documentation over at ggproto.

Bracket options

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

Cap options

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

common parameters in legendry

Description

This is a collection of common parameters so they needn't be re-documented each time.

Arguments

Compose guides in a cross

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)

Compose guides on top of one another

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

Compose guides as a sandwich

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

Compose guides as stack

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

Guide gizmo: capped colour bar

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

Guide gizmo: kernel density estimate

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

Guide gizmo: custom grob

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

Guide gizmo: histogram

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

Guide gizmo: capped colour steps

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

Guide composition

Description

Guide composition is a meta-guide orchestrating an ensemble of other guides. On their own, a 'composing' guide is not very useful as a visual reflection of a scale.

Usage

new_compose(
  guides,
  args = list(),
  ...,
  available_aes = c("any", "x", "y", "r", "theta"),
  call = caller_env(),
  super = Compose
)

Arguments

Details

Styling options

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

There are no further styling options.

Value

A ⁠<Compose>⁠ (sub-)class guide that composes other guides.

See Also

Other composition: compose_crux(), compose_ontop(), compose_sandwich(), compose_stack()

Examples

# The `new_compose()` function is not intended to be used directly
my_composition <- new_compose(list("axis", "axis"), super = ComposeStack)

# Is the same as
my_composition <- compose_stack("axis", "axis")

Guide gizmos

Description

Guide gizmos are a speciality guide components that are very specific to one or a few aesthetics to display.

Typically they can be composed with other guides or guide primitives to form a complete guide.

Guide primitives

Description

Guide primitives are the building blocks of more complex guides. On their own, they are not very useful as a visual reflection of a scale.

Their purpose is to be combined with one another to form a more complex, complete guides that do reflect a scale in some way.

Details

The guide primitives are simple, but flexible in that they are not tailored for one particular aesthetic. That way they can be reused and combined at will.

Annotation axis guide

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

Custom axis guide

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

Dendrogram guide

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

Nested axis guide

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

Side-plot axis

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

Symbol and upset axis guide

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

Circle size guide

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

Custom colour bar guide

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

Colour rings and arcs

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

Custom colour steps guide

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

Custom legend guide

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

Cross legend guide

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

Grouped legend

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

Manual legend

Description

This is a guide that displays user-defined keys independent of scales. It should only be used as a last resort when struggling to format a conventional legend.

Usage

guide_legend_manual(
  labels,
  ...,
  layers = list(geom_point()),
  title = NULL,
  theme = NULL,
  design = NULL,
  nrow = NULL,
  ncol = NULL,
  reverse = FALSE,
  position = NULL,
  direction = NULL,
  order = 0L
)

Arguments

Details

Because this guide is not tied to a scale, it can be given an arbitrary name in guides(); as long as it doesn't clash with other aesthetics.

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_manual(legend_args = list(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 ⁠<GuideCustom>⁠ 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_group()

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

Examples

# A standard plot
p <- ggplot(mtcars, aes(disp, mpg)) +
  geom_point()

# Typical usage: set `label` and some aesthetics
p + guides(
  some_name = guide_legend_manual(
    label  = c("foo", "bar"),
    colour = c(NA, "black"),
    fill   = c("grey40", NA),
    layers = geom_col()
  )
)

# Alternative: use `layers` to set aesthetics
p + guides(
  some_name = guide_legend_manual(
    label = c("foo", "bar"),
    layers = geom_col(
      # Must match length of `label`
      colour = c(NA, "black"),
      fill = c("grey40", NA)
    )
  )
)

# You can use >1 layer
p + guides(
  some_name = guide_legend_manual(
    label = c("foo", "bar"),
    colour = c("tomato", "dodgerblue"),
    fill = NA,
    layers = list(geom_col(), geom_point())
  )
)

Group keys

Description

These functions are helper functions for working with grouped data as keys in guides. They all share the goal of creating a guide key, but have different methods.

• key_group_split() is a function factory whose functions make an attempt to infer groups from the scale's labels.

• key_group_lut() is a function factory whose functions use a look up table to sort out group membership.

Usage

key_group_split(sep = "[^[:alnum:]]+", reverse = FALSE)

key_group_lut(members, group, ungrouped = "Other")

Arguments

Value

A function to use as the key argument in a guide.

See Also

Other keys: key_range, key_segments, key_specialty, key_standard

Examples

# Example scale
values <- c("group A:value 1", "group A:value 2", "group B:value 1")
template <- scale_colour_hue(limits = values)

# Treat the 'group X' part as groups
key <- key_group_split(sep = ":")
key(template)

# Treat the 'value X' part as groups
key <- key_group_split(sep = ":", reverse = TRUE)
key(template)

# Example scale
template <- scale_colour_hue(limits = msleep$name[c(1, 7, 9, 23, 24)])

# A lookup table can have more entries than needed
key <- key_group_lut(msleep$name, msleep$order)
key(template)

# Or less entries than needed
key <- key_group_lut(
  msleep$name[23:24], msleep$order[23:24],
  ungrouped = "Other animals"
)
key(template)

Range keys

Description

These functions are helper functions for working with ranged data as keys in guides. They all share the goal creating of a guide key, but have different methods:

• key_range_auto() is a function factory whose functions make an attempt to infer ranges from the scale's labels.

• key_range_manual() uses user-provided vectors to set ranges.

• key_range_map() makes mappings from a ⁠<data.frame>⁠ to set ranges.

• key_range_rle() uses run-length encoding to determine the start and end of runs (blocks of repeated data values).

Usage

key_range_auto(sep = "[^[:alnum:]]+", reverse = FALSE, ...)

key_range_manual(start, end, name = NULL, level = NULL, ..., call = NULL)

key_range_map(data, ..., call = NULL)

key_range_rle(x, ..., call = NULL)

Arguments

Details

The level variable is optional and when missing, the guides use an algorithm similar to IRanges::disjointBins() to avoid overlaps.

The key_range_auto() does not work with expression labels.

Value

For key_range_auto() a function. For key_range_manual() and key_range_map() a ⁠<data.frame>⁠ with the ⁠<key_range>⁠ class.

See Also

Other keys: key_group, key_segments, key_specialty, key_standard

Examples

# Example scale
template <- scale_x_discrete(limits = c("A 1", "B 1", "C&1", "D&2", "E&2"))

# By default, splits on all non-alphanumeric characters
auto <- key_range_auto()
auto(template)

# Only split on a specific character
auto <- key_range_auto(sep = "&")
auto(template)

# Treating the letters as outer labels and numbers as inner labels
auto <- key_range_auto(reverse = TRUE)
auto(template)

# Providing custom values
key_range_manual(
  start = c(1, 5,  10),
  end   = c(4, 15, 11),
  level = c(0, 2, 1),
  name  = c("A", "B", "C")
)

# Values from a <data.frame>
key_range_map(presidential, start = start, end = end, name = name)

# Values from run length encoding
key_range_rle(c("AB", "AB", "C", "DEF", "DEF", "DEF"))

Segment keys

Description

These functions are helper functions for working with segment data as keys in guides. They all share the goal of creating a guide key, but have different methods:

• key_segment_manual() directly uses user-provided vectors to set segments.

• key_segment_map() makes mappings from a ⁠<data.frame>⁠ to set segments.

• key_dendro() is a specialty case for coercing dendrogram data to segments. Be aware that setting the key alone cannot affect the scale limits, and will give misleading results when used incorrectly!

Usage

key_segment_manual(value, oppo, value_end = value, oppo_end = oppo, ...)

key_segment_map(data, ..., .call = caller_env())

key_dendro(dendro = NULL, type = "rectangle", ..., .call = NULL)

Arguments

Value

For key_segments_manual() and key_segments_map(), a ⁠<data.frame>⁠ with the ⁠<key_range>⁠ class.

See Also

Other keys: key_group, key_range, key_specialty, key_standard

Examples

# Giving vectors directly
key_segment_manual(
  value = 0:1, value_end = 2:3,
  oppo  = 1:0, oppo_end  = 3:2
)

# Taking columns of a data frame
data <- data.frame(x = 0:1, y = 1:0, xend = 2:3, yend = 3:2)
key_segment_map(data, value = x, oppo = y, value_end = xend, oppo_end = yend)

# Using dendrogram data
clust <- hclust(dist(USArrests), "ave")
key_dendro(clust)(scale_x_discrete())

Speciality keys

Description

These functions are helper functions for working with keys in guides. The functions described here are not widely applicable and may only apply to a small subset of guides. As such, it is fine to adjust the arguments of a speciality key, but swapping types is ill-advised.

• key_sequence() is a function factory whose functions create a regularly spaced sequence between the limits of a scale. It is used in colour bar guides.

• key_bins() is a function factory whose function create a binned key given the breaks in the scale. It is used in colour steps guides.

• key_upset() is a function factory whose function creates an upset key from splitting the breaks in the scale. It is used in the upset guide.

• key_symbols() is a function factory whose function creates a key from the literal provided values. It is used in the symbols guide.

Usage

key_sequence(n = 15L)

key_bins(even.steps = FALSE, show.limits = NULL)

key_upset(sep = "[^[:alnum:]]+", order = NULL, empty_label = "Other")

key_symbols(aesthetic, level, symbol = NULL, ...)

Arguments

Value

A function.

See Also

Other keys: key_group, key_range, key_segments, key_standard

Examples

# An example scale
template <- scale_fill_viridis_c(limits = c(0, 10), breaks = c(2, 4, 6, 8))

# Retrieving colourbar and colourstep keys
key_sequence()(template)
key_bins()(template)

# Upset key with example scale
template <- scale_x_discrete(limits = c("A", "A,B", ""))
key_upset()(template)
# Putting 'B' in 1st level
key_upset(order = c("B", "A"))(template)
# Omit level for the empty break
key_upset(empty_label = NULL)(template)

# Symbol key with example scale
template <- scale_x_discrete(limits = LETTERS[1:5])
key_symbols(aesthetic = LETTERS[1:3], level = 3:1)(template)
# Aesthetic can also be numeric
key_symbols(1:3, 3:1)(template)
# Setting level order via factors
ordered <- factor(c("X", "Y", "Z"), c("Y", "X", "Z"))
key_symbols(1:3, level = ordered)(template)
# Setting groups for symbols, for `guide_axis_symbols(override.aes)`
key_symbols(1:3, 1:3, symbol = c(1, 1, 2))(template)
# Passing individual graphical parameters
key_symbols(1:3, 3:1, colour = c("red", "green", "blue"))(template)

Standard keys

Description

These functions are helper functions for working with tick marks as keys in guides. They all share the goal of creating a guide key, but have different outcomes:

• key_auto() is a function factory whose functions extract a typical key from major breaks in a scale.

• key_manual() uses user-provided vectors to make a key.

• key_map() makes mappings from a ⁠<data.frame>⁠ to make a key.

• key_minor() is a function factory whose functions also extract minor break positions for minor tick marks.

• key_log() is a function factory whose functions place ticks at intervals in log10 space.

• key_none() makes an empty key with no entries.

Usage

key_auto(..., call = NULL)

key_manual(
  aesthetic,
  value = aesthetic,
  label = as.character(value),
  type = NULL,
  ...,
  call = NULL
)

key_map(data, ..., call = NULL)

key_minor(..., call = NULL)

key_log(
  prescale_base = NULL,
  negative_small = 0.1,
  expanded = TRUE,
  labeller = NULL,
  ...,
  call = NULL
)

key_none()

Arguments

Value

For key_auto(), key_minor() and key_log() a function. For key_manual() and key_map() a ⁠<data.frame>⁠ with the ⁠<key_standard>⁠ class.

See Also

Other keys: key_group, key_range, key_segments, key_specialty

Examples

# An example scale
template <- scale_x_continuous(limits = c(0, 10))

# The auto, minor and log keys operate on scales
key_auto()(template)
key_minor()(template)

# So does the log key
template <- scale_x_continuous(transform = "log10", limits = c(0.1, 10))
key_log()(template)

# Providing custom values
key_manual(
  aesthetic = 1:5,
  label = c("one", "two", "three", "four", "five")
)

# Values from a `<data.frame>`
key_map(ToothGrowth, aesthetic = unique(supp))

# Empty key
key_none()

Helper to position text

Description

This is a helper function for use in guide_legend_cross(). It creates a list of text elements, each corresponding the top, right, bottom or left positions. Input is given for that order as well.

Usage

position_text(angle = NA, hjust = NA, vjust = NA, ..., element = element_text)

Arguments

Details

Input other than the element argument will be recycled to length 4. NA and 0-length input will be dropped.

Value

A named list of element objects of length 4. The list has the names "top", "right", "bottom" and "left".

Examples

# Red text turning along with position
position_text(angle = c(0, -90, 180, 90), colour = "red")

Guide primitives: boxes

Description

This function constructs a boxes guide primitive.

Usage

primitive_box(
  key = "range_auto",
  angle = waiver(),
  oob = "squish",
  drop_zero = TRUE,
  pad_discrete = 0.4,
  min_size = NULL,
  levels_box = NULL,
  levels_text = NULL,
  theme = NULL,
  position = waiver()
)

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide, which may differ depending on whether the guide is used in an axis or in a legend context.

The possible {position} suffixes mentioned below are x, x.top, x.bottom, y, y.left, y.right. The theta and r position suffixes in ggplot2 are not obeyed in legendry.

Styling options per level can be set in the levels_box and levels_text arguments. These override theme settings.

Styling options per range can be set in the range key. The rect and text prefixed properties are prioritised for the boxes and text respectively. These override theme settings and 'per level' settings.

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

primitive_box(theme = theme_guide(
  box = element_rect(),
  text = element_text()
))

Value

A ⁠<PrimitiveBox>⁠ primitive guide that can be used inside other guides.

See Also

Other primitives: primitive_bracket(), primitive_fence(), primitive_labels(), primitive_line(), primitive_segments(), primitive_spacer(), primitive_ticks(), primitive_title()

Examples

# A standard plot
p <- ggplot(mpg, aes(interaction(drv, year), displ)) +
 geom_point()

key <- key_range_manual(c(2, 4), c(5, 6), c("A", "B"))

# Adding as secondary guides
p + guides(
  x.sec = primitive_box(),
  y.sec = primitive_box(key = key)
)

Guide primitive: brackets

Description

This function constructs a brackets guide primitive.

Usage

primitive_bracket(
  key = "range_auto",
  bracket = "line",
  angle = waiver(),
  oob = "squish",
  drop_zero = TRUE,
  pad_discrete = 0.4,
  levels_brackets = NULL,
  levels_text = NULL,
  theme = NULL,
  position = waiver()
)

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide, which may differ depending on whether the guide is used in an axis or in a legend context.

The possible {position} suffixes mentioned below are x, x.top, x.bottom, y, y.left, y.right. The theta and r position suffixes in ggplot2 are not obeyed in legendry.

Styling options per level can be set in the levels_brackets and levels_text arguments. These override theme settings.

Styling options per range can be set in the range key. The line and text prefixed properties are prioritised for the brackets and text respectively. These override theme settings and 'per level' settings.

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

primitive_bracket(theme = theme_guide(
  bracket = element_line(),
  bracket.size = unit(5, "mm")
))

Value

A ⁠<PrimitiveBracket>⁠ primitive guide that can be used inside other guides.

See Also

Other primitives: primitive_box(), primitive_fence(), primitive_labels(), primitive_line(), primitive_segments(), primitive_spacer(), primitive_ticks(), primitive_title()

Examples

# A standard plot
p <- ggplot(mpg, aes(interaction(drv, year), displ)) +
 geom_point()

key <- key_range_manual(c(2, 4), c(5, 6), c("A", "B"))

# Adding as secondary guides
p + guides(
  x.sec = primitive_bracket(),
  y.sec = primitive_bracket(key = key)
)

Guide primitive: fence

Description

This function constructs a fence guide primitive. The customisation options are easier to understand if we view fence 'post' as the vertical pieces of a real world fence, and the 'rail' as the horizontal pieces.

Usage

primitive_fence(
  key = "range_auto",
  rail = "none",
  angle = waiver(),
  oob = "squish",
  drop_zero = TRUE,
  pad_discrete = 0.5,
  levels_text = NULL,
  levels_post = NULL,
  levels_rail = NULL,
  theme = NULL,
  position = waiver()
)

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide, which may differ depending on whether the guide is used in an axis or in a legend context.

The possible {position} suffixes mentioned below are x, x.top, x.bottom, y, y.left, y.right. The theta and r position suffixes in ggplot2 are not obeyed in legendry.

Styling options per level can be set in the levels_post, levels_rail and levels_text arguments. These override theme settings.

Styling options per range can be set in the range key. The line and text prefixed properties are prioritised for the fence and text respectively. The 'post' and 'rail' distinction does not apply at the 'per range' settings. These override theme settings and the 'per level' settings.

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

primitive_fence(theme = theme_guide(
  fence = element_line(),
  fence.post = element_line(),
  fence.rail = element_line(),
  text = element_text()
))

Value

A ⁠<PrimitiveFence>⁠ primitive guie that can be used inside other guides.

See Also

Other primitives: primitive_box(), primitive_bracket(), primitive_labels(), primitive_line(), primitive_segments(), primitive_spacer(), primitive_ticks(), primitive_title()

Examples

# A standard plot
p <- ggplot(mpg, aes(interaction(drv, year), displ)) +
  geom_point()

key <- key_range_manual(c(2, 4), c(5, 6), c("A", "B"))

# Adding as secondary guides
p + guides(
  x.sec = primitive_fence(rail = "inner"),
  y.sec = primitive_fence(key = key, rail = "outer")
)

Guide primitive: labels

Description

This function constructs a labels guide primitive.

Usage

primitive_labels(
  key = NULL,
  angle = waiver(),
  n.dodge = 1L,
  check.overlap = FALSE,
  theme = NULL,
  position = waiver()
)

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide, which may differ depending on whether the guide is used in an axis or in a legend context.

The possible {position} suffixes mentioned below are x, x.top, x.bottom, y, y.left, y.right. The theta and r position suffixes in ggplot2 are not obeyed in legendry.

Styling options per break can be set in the standard key. The text prefixed properties are prioritised. These override theme settings.

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

primitive_labels(theme = theme_guide(
  text = element_line()
))

Value

A ⁠<PrimitiveLabels>⁠ primitive guide that can be used inside other guides.

See Also

Other primitives: primitive_box(), primitive_bracket(), primitive_fence(), primitive_line(), primitive_segments(), primitive_spacer(), primitive_ticks(), primitive_title()

Examples

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

# Adding as secondary guides
p + guides(
  x.sec = primitive_labels(),
  y.sec = primitive_labels(n.dodge = 2)
)

Guide primitive: line

Description

This function constructs a line guide primitive.

Usage

primitive_line(key = NULL, cap = "none", theme = NULL, position = waiver())

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide, which may differ depending on whether the guide is used in an axis or in a legend context.

There are no other styling options. The context-agnostic alternative to using theme() is to use theme_guide():

primitive_line(theme = theme_guide(
  line = element_line()
))

Value

A PrimitiveLine primitive guide that can be used inside other guides.

See Also

Other primitives: primitive_box(), primitive_bracket(), primitive_fence(), primitive_labels(), primitive_segments(), primitive_spacer(), primitive_ticks(), primitive_title()

Examples

# A standard plot
p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  theme(axis.line = element_line())

# Adding as secondary guides
p + guides(
  x.sec = primitive_line(),
  y.sec = primitive_line(cap = "both")
)

Guide primitives: segments

Description

This function constructs a guide primitive.

Usage

primitive_segments(
  key = NULL,
  space = rel(10),
  vanish = FALSE,
  theme = NULL,
  position = waiver()
)

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide, which may differ depending on whether the guide is used in an axis or in a legend context.

The possible {position} suffixes mentioned below are x, x.top, x.bottom, y, y.left, y.right. The theta and r position suffixes in ggplot2 are not obeyed in legendry.

Styling options per segment can be set in the segment key. The line prefixed properties are prioritised for segments. These override theme settings.

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

primitive_segments(theme = theme_guide(
  ticks = element_line(),
  ticks.length = unit(5, "mm")
))

Value

A ⁠<PrimitiveSegments>⁠ primitive guide that can be used inside other guides.

See Also

Other primitives: primitive_box(), primitive_bracket(), primitive_fence(), primitive_labels(), primitive_line(), primitive_spacer(), primitive_ticks(), primitive_title()

Examples

# Building a key
key <- key_segment_manual(
  value     = c(1.6, 1.6, 3.4, 5.2),
  value_end = c(7.0, 7.0, 3.4, 5.2),
  oppo      = c(1.0, 2.0, 0.0, 0.0),
  oppo_end  = c(1.0, 2.0, 3.0, 3.0)
)

# Using the primitive in a plot
ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  scale_x_continuous(
    guide = primitive_segments(key = key)
  )

Guide primitive: spacer

Description

This function constructs a spacer guide primitive. The spacer is intended for use in guide composition.

Usage

primitive_spacer(
  space = NULL,
  title = waiver(),
  theme = NULL,
  position = waiver()
)

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide. In context to many primitive guides, whether it is used in an axis or legend has no bearing on the style.

There are no other styling options. The context-agnostic alternative to using theme() is to use theme_guide():

primitive_spacer(theme = theme_guide(
  spacing = unit(5, "mm"),
))

Value

A ⁠<PrimitiveSpacer>⁠ primitive guide that can be used inside other guides.

See Also

Other primitives: primitive_box(), primitive_bracket(), primitive_fence(), primitive_labels(), primitive_line(), primitive_segments(), primitive_ticks(), primitive_title()

Examples

ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  guides(
    x = guide_axis_stack("axis", primitive_spacer(unit(1, "cm")), "axis")
  )

Guide primitive: line

Description

This function constructs a ticks guide primitive.

Usage

primitive_ticks(key = NULL, bidi = FALSE, theme = NULL, position = waiver())

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide, which may differ depending on whether the guide is used in an axis or in a legend context.

The ticks can come in three variants: major, minor and minimal. Which variants are drawn depends on the keys: key_minor() draws major and minor ticks, whereas key_log() also has minimal ticks. Each variant has a corresponding length setting.

The possible {position} suffixes mentioned below are x, x.top, x.bottom, y, y.left, y.right. The theta and r position suffixes in ggplot2 are not obeyed in legendry.

Styling options per break can be set in the key. The line and prefixed properties are prioritised for the tick lines. These override theme settings.

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

primitive_ticks(theme = theme_guide(
  ticks = element_line(),
  ticks.length = unit(5, "mm"),
  minor.ticks = element_line(),
  minor.ticks.length = unit(4, "mm"),
  mini.ticks = element_line(),
  mini.ticks.length = unit(3, "mm")
))

Value

A PrimitiveTicks primitive guide that can be used inside other guides.

See Also

Other primitives: primitive_box(), primitive_bracket(), primitive_fence(), primitive_labels(), primitive_line(), primitive_segments(), primitive_spacer(), primitive_title()

Examples

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

# Adding as secondary guides
p + guides(x.sec = primitive_ticks(), y.sec = primitive_ticks())

Guide primitive: title

Description

This function constructs a title guide primitive.

Usage

primitive_title(
  title = waiver(),
  angle = waiver(),
  theme = NULL,
  position = waiver()
)

Arguments

Details

Styling options

Below are the theme options that determine the styling of this guide, which may differ depending on whether the guide is used in an axis or in a legend context.

There are no further styling options.

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

primitive_title(theme = theme_guide(
  title = element_text(),
))

Value

A ⁠<PrimitiveTitle>⁠ primitive guide that can be used inside other guides.

See Also

Other primitives: primitive_box(), primitive_bracket(), primitive_fence(), primitive_labels(), primitive_line(), primitive_segments(), primitive_spacer(), primitive_ticks()

Examples

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

# Adding as secondary guides
p + guides(
  x.sec = primitive_title("Horizontal Title"),
  y.sec = primitive_title(c("along vertical", "Multiple tiles"))
)

# 'Real' titles occur once per plot.
# Primitive titles repeat over facets and hide the 'real' title.
p + facet_wrap(~ drv) +
  guides(x = primitive_title("I am a repeated subtitle")) +
  labs(x = "I am the hidden real title")

Dendrogram scales

Description

These are speciality scales for use with hierarchically clustered data. The scale automatically orders the limits according to the clustering result and comes with a dendrogram axis.

Usage

scale_x_dendro(
  clust,
  ...,
  expand = waiver(),
  guide = "axis_dendro",
  position = "bottom"
)

scale_y_dendro(
  clust,
  ...,
  expand = waiver(),
  guide = "axis_dendro",
  position = "left"
)

Arguments

Details

The scale limits are determined by the order and labels in the clust argument. While limits is not an argument in these scales, the breaks argument can still be used to selectively omit some breaks and the labels can be used for formatting purposes.

Value

A ⁠<ScaleDiscretePosition>⁠ object that can be added to a plot.

See Also

guide_axis_dendro()

Examples

# Hierarchically cluster data, separately for rows and columns
car_clust <- hclust(dist(scale(mtcars)), "ave")
var_clust <- hclust(dist(scale(t(mtcars))), "ave")

long_mtcars <- data.frame(
  car = rownames(mtcars)[row(mtcars)],
  var = colnames(mtcars)[col(mtcars)],
  value = as.vector(scale(mtcars))
)

# A standard heatmap adorned with dendrograms
p <- ggplot(long_mtcars, aes(var, car, fill = value)) +
  geom_tile() +
  scale_x_dendro(var_clust) +
  scale_y_dendro(car_clust)
p

# Styling the dendrograms
p +
  guides(
    y = guide_axis_dendro(key_dendro(type = "triangle")),
    x = guide_axis_dendro(space = rel(5))
  ) +
  theme(
    axis.text.y.left = element_text(margin = margin(r = 3, l = 3)),
    axis.ticks.y = element_line("red"),
    axis.ticks.x = element_line(linetype = "dotted")
  )

# In polar coordinates, plus some formatting
p +
  coord_radial(
    theta = "y", inner.radius = 0.5,
    start = 0.25 * pi, end = 1.75 * pi
  ) +
  guides(
    theta = primitive_labels(angle = 90),
    theta.sec = primitive_segments("dendro", vanish = TRUE),
    r = guide_axis_dendro(angle = 0)
  )

Theme wrapper for guides

Description

This function does three things different than theme().

Usage

theme_guide(
  text = NULL,
  line = NULL,
  title = NULL,
  subtitle = NULL,
  text.position = NULL,
  title.position = NULL,
  subtitle.position = NULL,
  ticks = NULL,
  minor.ticks = NULL,
  mini.ticks = NULL,
  ticks.length = NULL,
  minor.ticks.length = NULL,
  mini.ticks.length = NULL,
  spacing = NULL,
  group.spacing = NULL,
  table.spacing = NULL,
  key = NULL,
  key.size = NULL,
  key.width = NULL,
  key.height = NULL,
  key.spacing = NULL,
  key.spacing.x = NULL,
  key.spacing.y = NULL,
  key.margin = NULL,
  key.justification = NULL,
  frame = NULL,
  byrow = NULL,
  background = NULL,
  margin = NULL,
  bracket = NULL,
  bracket.size = NULL,
  box = NULL,
  fence = NULL,
  fence.post = NULL,
  fence.rail = NULL,
  zebra.light = NULL,
  zebra.dark = NULL,
  point = NULL,
  connector = NULL
)

Arguments