Skip to contents

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 = 300,
  reverse = FALSE,
  show_labels = "outer",
  theme = NULL,
  vanilla = TRUE,
  position = waiver(),
  available_aes = c("colour", "fill"),
  ...
)

Arguments

title

One of the following to indicate the title of the guide:

  • A <character[1]> or <expression[1]> to set a custom title.

  • NULL to not display any title.

  • waiver() (default) to take the name of the scale object or the name specified in labs() as the title.

key

A standard key specification. Defaults to key_auto().

start, end

A <numeric[1]> in radians specifying the offset of the starting and end points from 12 o'clock. The NULL default for end, internally defaults to start + 2 * pi.

outer_guide, inner_guide

Guides to display on the outside and inside of the colour ring. Each guide can be specified using one of the following:

  • A <Guide> class object.

  • A <function> that returns a <Guide> class object.

  • A <character> naming such function, without the guide_ or primitive_ prefix.

nbin

A positive <integer[1]> determining how many colours to display.

reverse

A <logical[1]> whether to reverse continuous guides. If TRUE, guides like colour bars are flipped. If FALSE (default), the original order is maintained.

show_labels

A <character[1]> indicating for which guide labels should be shown. Can be one of "outer" (default), "inner", "both" or "none". Note that labels can only be omitted if the related guide has a label suppression mechanism.

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.

vanilla

A <logical[1]> whether to have the default style match the vanilla guide_colourbar() (TRUE) or take the theme verbatim (FALSE).

position

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

available_aes

A <character> vector listing the aesthetics for which this guide can be build.

...

Arguments forwarded to the outer_guide and inner_guide if provided as functions or strings.

Value

A <Guide> object.

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