legendry (version 0.2.1)

guide_circles: Circle size guide

Description

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 = 1),
  position = waiver(),
  direction = NULL
)

Value

A <GuideCircles> object.

Arguments

key

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

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.

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

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.

See Also

Other standalone guides: guide_axis_base(), guide_axis_dendro(), guide_axis_nested(), guide_colbar(), guide_colring(), guide_colsteps(), guide_legend_base(), guide_legend_cross(), guide_legend_group()

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