Colour rings and arcs

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

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.

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.

Constituent	Description
guide_axis_base()	Makes up the tick marks and labels at inner and outer rings.

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

Theme setting	Type	Description
legend.background	element_rect()	Background of the legend.
legend.margin	margin()	Padding around the legend.
legend.key.width	unit()	Radial thickness of the donut ring.
legend.key.size	unit()	Size of the legend. Multiplied by 5 to roughly match dimensions of colour bar guides.
legend.frame	element_rect()	Outline of the donut. The fill setting is ignored.
legend.title	element_text()	Title of the legend.
legend.title.position	<character[1]>	One of "top", "right", "bottom" or "left".

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

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