% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/guide-circles.R
\name{guide_circles}
\alias{guide_circles}
\title{Circle size guide}
\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{
\item{key}{A \link[=key_standard]{standard key} specification. Defaults to
\code{\link[=key_auto]{key_auto()}}. See more information in the linked topic.}

\item{title}{One of the following to indicate the title of the guide:
\itemize{
\item A \verb{<character[1]>} or \verb{<expression[1]>} to set a custom title.
\item \code{NULL} to not display any title.
\item \code{\link[ggplot2:waiver]{waiver()}} (default) to take the name of the scale
object or the name specified in \code{\link[ggplot2:labs]{labs()}} as the title.
}}

\item{theme}{A \code{\link[ggplot2:theme]{<theme>}} object to style the guide individually or
differently from the plot's theme settings. The \code{theme} argument in the
guide overrides and is combined with the plot's theme.}

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

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

\item{clip_text}{A \verb{<logical[1]>} whether to give text in the \code{"ontop"}
position a small rectangle of background colour.}

\item{override.aes}{A named \verb{<list>} specifying aesthetic parameters of the
key glyphs. See details and examples in
\code{\link[ggplot2:guide_legend]{guide_legend()}}.}

\item{position}{A \verb{<character[1]>} giving the location of the guide. Can be one of \code{"top"},
\code{"bottom"}, \code{"left"} or \code{"right"}.}

\item{direction}{A \verb{<character[1]>} indicating the direction of the guide. Can be on of
\code{"horizontal"} or \code{"vertical"}.}
}
\value{
A \verb{<GuideCircles>} object.
}
\description{
This guide displays the sizes of points as a series of circles. It is
typically paired with \code{\link[ggplot2:geom_point]{geom_point()}} with
\code{\link[ggplot2:draw_key_point]{draw_key_point()}} glyphs.
}
\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 \link[ggplot2:scale_shape]{shapes}
in mind, i.e. shapes 1, 16, 19 and 21. For that reason, \code{shape = 1} is the
default \code{override.aes} argument. Other shapes will probably be drawn but the
quality of their alignment and label placement may be unsatisfactory.
\subsection{Styling options}{

Below are the \link[ggplot2:theme]{theme} options that determine the styling of
this guide.\tabular{lll}{
   \strong{Theme setting} \tab \strong{Type} \tab \strong{Description} \cr
   \code{legend.background} \tab \code{\link[ggplot2:element_rect]{element_rect()}} \tab Background of the legend. \cr
   \code{legend.margin} \tab \code{\link[ggplot2:margin]{margin()}} \tab Padding around the legend. \cr
   \code{legend.key} \tab \code{\link[ggplot2:element_rect]{element_rect()}} \tab Background of the key area underneath circles. \cr
   \code{legend.text} \tab \code{\link[ggplot2:element_text]{element_text()}} \tab Labels displayed next to tick marks or on top of circles. \cr
   \code{legendry.legend.key.margin} \tab \code{\link[ggplot2:margin]{margin()}} \tab Padding between circles and edge of key area. \cr
   \code{legend.ticks} \tab \code{\link[ggplot2:element_line]{element_line()}} \tab Tick marks connecting circle to label. \cr
   \code{legend.title} \tab \code{\link[ggplot2:element_text]{element_text()}} \tab Title of the legend. \cr
   \code{legend.title.position} \tab \verb{<character[1]>} \tab One of \code{"top"}, \code{"right"}, \code{"bottom"} or \code{"left"}. \cr
}


Styling options \emph{per break} can be set in the \link[=key_standard]{standard key}.
These override theme settings.

The context-agnostic alternative to using \code{theme()} is to use
\code{\link[=theme_guide]{theme_guide()}}:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{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(),
))
}\if{html}{\out{</div>}}
}
}
\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"
  )
}
\seealso{
Other standalone guides:
\code{\link[=guide_axis_annotation]{guide_axis_annotation()}},
\code{\link[=guide_axis_base]{guide_axis_base()}},
\code{\link[=guide_axis_dendro]{guide_axis_dendro()}},
\code{\link[=guide_axis_nested]{guide_axis_nested()}},
\code{\link[=guide_axis_plot]{guide_axis_plot()}},
\code{\link[=guide_axis_symbols]{guide_axis_symbols()}},
\code{\link[=guide_colbar]{guide_colbar()}},
\code{\link[=guide_colring]{guide_colring()}},
\code{\link[=guide_colsteps]{guide_colsteps()}},
\code{\link[=guide_legend_base]{guide_legend_base()}},
\code{\link[=guide_legend_cross]{guide_legend_cross()}},
\code{\link[=guide_legend_group]{guide_legend_group()}},
\code{\link[=guide_legend_manual]{guide_legend_manual()}}
}
\concept{standalone guides}
