Custom axis guide

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_custom(
  key = NULL,
  title = waiver(),
  theme = NULL,
  n.dodge = 1,
  check.overlap = FALSE,
  angle = waiver(),
  cap = "none",
  bidi = FALSE,
  order = 0,
  position = waiver()
)

Arguments

key

A standard key specification. Defaults to key_auto(). See more information in the linked topic and the 'Details' section.

title

A <character[1]> or <expression[1]> indicating the title of the guide. If NULL, the title is not shown. The default, waiver(), takes the name of the scale object or the name specified in labs() as the title.

theme

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

n.dodge

An positive <integer[1]> setting the number of layers text labels can occupy to avoid overlapping labels.

check.overlap

A <logical[1]> indicating whether to check for and omit overlapping text. If TRUE, first, last and middle labels are recursively prioritised in that order. If FALSE, all labels are drawn.

angle

A specification for the text angle. Compared to setting the angle argument in element_text(), this argument uses some heuristics to automatically pick the hjust and vjust that you probably want. Can be one of the following:

• NULL to take angles and justification settings directly from the theme.

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

• A <numeric[1]> between -360 and 360 for the text angle in degrees.

cap

A method to cap the axes. One of the following:

• A <character[1]> with one of the following:

  • "none" to perform no capping.

  • "both" to cap the line at both ends at the most extreme breaks.

  • "upper" to cap the line at the upper extreme break.

  • "lower" to cap the line at the lower extreme break.

• A <logical>[1], where TRUE is equivalent to "both" and FALSE is equivalent to "none" in the options above.

• A sorted <numeric>[2n] with an even number of members. The lines will be drawn between every odd-even pair.

• A <function> that takes the scale's breaks as the first argument, the scale's limits as the second argument and returns a <numeric>[2n] as described above.

bidi

A <logical[1]>: whether ticks should be drawn bidirectionally (TRUE) or in a single direction (FALSE, default).

order

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

position

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

Value

A <Guide> object.

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

See also

Other standalone guides: guide_colour_ring(), guide_colourbar_custom(), guide_coloursteps_custom(), guide_subtitle()

Examples

# A standard plot with custom keys
p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  scale_x_continuous(
    guide = guide_axis_custom(key = key_minor())
  ) +
  scale_y_continuous(
    guide = guide_axis_custom(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_custom("log")
  )