Skip to contents

Nested axis guide

Source: R/guide_axis_nested.R
guide_axis_nested.Rd

[Questioning] Discrete position scales containing interacting factors can be visualised more clearly with a nested axis guide. Nested axis guides separate labels based on a delimiter and groups identical later labels, indicating the grouping with a line spanning the earlier labels. The function is questioned due to a possible migration of guide functions after ggplot2 releases a new guide system.

Usage

guide_axis_nested(
  title = waiver(),
  check.overlap = FALSE,
  angle = NULL,
  n.dodge = 1,
  order = 0,
  position = waiver(),
  delim = waiver(),
  inv = FALSE,
  trunc_lower = NULL,
  trunc_upper = NULL,
  colour = NULL,
  color = NULL,
  extend = 0.5
)

Arguments

title

A character string or expression indicating a title of guide. If NULL, the title is not shown. By default (waiver()), the name of the scale object or the name specified in labs() is used for the title.

check.overlap

silently remove overlapping labels, (recursively) prioritizing the first, last, and middle labels.

angle

Compared to setting the angle in theme() / element_text(), this also uses some heuristics to automatically pick the hjust and vjust that you probably want. Can be one of the following:

  • NULL to take the angles and hjust/vjust directly from the theme.

  • waiver() to allow reasonable defaults in special cases.

  • A number representing the text angle in degrees.

n.dodge

The number of rows (for vertical axes) or columns (for horizontal axes) that should be used to render the labels. This is useful for displaying labels that would otherwise overlap.

order

A positive integer of length 1 that specifies the order of this guide among multiple guides. This controls in which order guides are merged if there are multiple guides for the same position. If 0 (default), the order is determined by a secret algorithm.

position

Where this guide should be drawn: one of top, bottom, left, or right.

delim

A character of length 1 to tell strsplit how hierarchies should be broken up. Internally defaults to "." to match interaction's default delimiter.

inv

A logical(1) which if TRUE, flips the grouping order. If FALSE (default), the grouping order is as-is.

trunc_lower, trunc_upper

The lower and upper range of the truncated axis:

  • NULL to not perform any truncation.

  • A function that takes the break positions as input and returns the lower or upper boundary. Note that also for discrete scales, positions are the mapped positions as numeric.

  • A numeric value in data units for the lower and upper boundaries.

  • A unit object.

colour, color

A character(1) with a valid colour for colouring the axis text, axis ticks and axis line. Overrules the colour assigned by the theme.

extend

A numeric of length 1 indicating how much to extend nesting lines relative to the smallest difference in break positions.

Value

A axis_nested guide class object.

Details

The guide itself makes no effort to group and order labels. To get nice groupings, consider re-ordering the levels of factor variables, or try setting the 'breaks' argument of a scale appropriately.

Theme elements

This axis guide uses the following the theme elements:

ggh4x.axis.nestline.x/y

An element_line() object to alter the display of the line separating different layers of labels.

ggh4x.axis.nesttext.x/y

An element_text() object to differentiate text higher up in the hierarchy, from the text closest to the axis line.

See also

ggplot2::guide_axis() for the classic axis documentation.
weave_factors() for an alternative to interaction().

Other axis-guides: guide_axis_logticks(), guide_axis_manual(), guide_axis_minor(), guide_axis_scalebar(), guide_axis_truncated()

Examples

# The defaults are suited for interaction variables
ggplot(mpg, aes(interaction(cyl, class), hwy)) +
  geom_boxplot() +
  scale_x_discrete(guide = "axis_nested")


# Control where labels are cut with the delim argument
ggplot(mpg, aes(interaction(cyl, class, sep = "~!~"), hwy)) +
  geom_boxplot() +
  scale_x_discrete(guide = guide_axis_nested(delim = "!"))


# The nesting lines inherit looks from axis ticks
ggplot(mpg, aes(interaction(cyl, class), hwy)) +
  geom_boxplot() +
  scale_x_discrete(guide = "axis_nested") +
  theme(axis.ticks = element_line(colour = "red"))


# The looks can be controlled independently by setting `ggh4x.axis.nestline`
ggplot(mpg, aes(interaction(cyl, class), hwy)) +
  geom_boxplot() +
  scale_x_discrete(guide = "axis_nested") +
  theme(ggh4x.axis.nestline = element_line(linetype = 2))