Circle size guide

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

key

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

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.

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.

hjust, vjust

A <numeric[1]> between 0 and 1 giving the horizontal and vertical justification, respectively, of the central shapes. It is recommended hjust = 0.5 when text is placed on the left or right and vjust = 0.5 is recommended when text is placed on top or in the bottom.

text_position

A string, one of "ontop", "top", "right", "bottom", or "left" do describe the placement of labels. The default (NULL), will take the legend.text.position theme setting.

clip_text

A <logical[1]> whether to give text in the "ontop" position a small rectangle of background colour.

override.aes

A named <list> specifying aesthetic parameters of the key glyphs. See details and examples in guide_legend().

position

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

direction

A <character[1]> indicating the direction of the guide. Can be on of "horizontal" or "vertical".

Value

A <GuideCircles> object.

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.

Theme setting	Type	Description
legend.background	element_rect()	Background of the legend.
legend.margin	margin()	Padding around the legend.
legend.key	element_rect()	Background of the key area underneath circles.
legend.text	element_text()	Labels displayed next to tick marks or on top of circles.
legendry.legend.key.margin	margin()	Padding between circles and edge of key area.
legend.ticks	element_line()	Tick marks connecting circle to label.
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_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(),
))

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