1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/guide-bins.R
3\name{guide_bins}
4\alias{guide_bins}
5\title{A binned version of guide_legend}
6\usage{
7guide_bins(
8  title = waiver(),
9  title.position = NULL,
10  title.theme = NULL,
11  title.hjust = NULL,
12  title.vjust = NULL,
13  label = TRUE,
14  label.position = NULL,
15  label.theme = NULL,
16  label.hjust = NULL,
17  label.vjust = NULL,
18  keywidth = NULL,
19  keyheight = NULL,
20  axis = TRUE,
21  axis.colour = "black",
22  axis.linewidth = 0.5,
23  axis.arrow = NULL,
24  direction = NULL,
25  default.unit = "line",
26  override.aes = list(),
27  reverse = FALSE,
28  order = 0,
29  show.limits = NULL,
30  ...
31)
32}
33\arguments{
34\item{title}{A character string or expression indicating a title of guide.
35If \code{NULL}, the title is not shown. By default
36(\code{\link[=waiver]{waiver()}}), the name of the scale object or the name
37specified in \code{\link[=labs]{labs()}} is used for the title.}
38
39\item{title.position}{A character string indicating the position of a
40title. One of "top" (default for a vertical guide), "bottom", "left"
41(default for a horizontal guide), or "right."}
42
43\item{title.theme}{A theme object for rendering the title text. Usually the
44object of \code{\link[=element_text]{element_text()}} is expected. By default, the theme is
45specified by \code{legend.title} in \code{\link[=theme]{theme()}} or theme.}
46
47\item{title.hjust}{A number specifying horizontal justification of the
48title text.}
49
50\item{title.vjust}{A number specifying vertical justification of the title
51text.}
52
53\item{label}{logical. If \code{TRUE} then the labels are drawn. If
54\code{FALSE} then the labels are invisible.}
55
56\item{label.position}{A character string indicating the position of a
57label. One of "top", "bottom" (default for horizontal guide), "left", or
58"right" (default for vertical guide).}
59
60\item{label.theme}{A theme object for rendering the label text. Usually the
61object of \code{\link[=element_text]{element_text()}} is expected. By default, the theme is
62specified by \code{legend.text} in \code{\link[=theme]{theme()}}.}
63
64\item{label.hjust}{A numeric specifying horizontal justification of the
65label text.}
66
67\item{label.vjust}{A numeric specifying vertical justification of the label
68text.}
69
70\item{keywidth}{A numeric or a \code{\link[grid:unit]{grid::unit()}} object specifying
71the width of the legend key. Default value is \code{legend.key.width} or
72\code{legend.key.size} in \code{\link[=theme]{theme()}}.}
73
74\item{keyheight}{A numeric or a \code{\link[grid:unit]{grid::unit()}} object specifying
75the height of the legend key. Default value is \code{legend.key.height} or
76\code{legend.key.size} in \code{\link[=theme]{theme()}}.}
77
78\item{axis}{Logical. Should a small axis be drawn along the guide}
79
80\item{axis.colour, axis.linewidth}{Graphic specifications for the look of the
81axis.}
82
83\item{axis.arrow}{A call to \code{arrow()} to specify arrows at the end of the
84axis line, thus showing an open interval.}
85
86\item{direction}{A character string indicating the direction of the guide.
87One of "horizontal" or "vertical."}
88
89\item{default.unit}{A character string indicating \code{\link[grid:unit]{grid::unit()}}
90for \code{keywidth} and \code{keyheight}.}
91
92\item{override.aes}{A list specifying aesthetic parameters of legend key.
93See details and examples.}
94
95\item{reverse}{logical. If \code{TRUE} the order of legends is reversed.}
96
97\item{order}{positive integer less than 99 that specifies the order of
98this guide among multiple guides. This controls the order in which
99multiple guides are displayed, not the contents of the guide itself.
100If 0 (default), the order is determined by a secret algorithm.}
101
102\item{show.limits}{Logical. Should the limits of the scale be shown with
103labels and ticks.}
104
105\item{...}{ignored.}
106}
107\value{
108A guide object
109}
110\description{
111This guide is a version of the \code{\link[=guide_legend]{guide_legend()}} guide for binned scales. It
112differs in that it places ticks correctly between the keys, and sports a
113small axis to better show the binning. Like \code{\link[=guide_legend]{guide_legend()}} it can be used
114for all non-position aesthetics though colour and fill defaults to
115\code{\link[=guide_coloursteps]{guide_coloursteps()}}, and it will merge aesthetics together into the same
116guide if they are mapped in the same way.
117}
118\section{Use with discrete scale}{
119
120This guide is intended to show binned data and work together with ggplot2's
121binning scales. However, it is sometimes desirable to perform the binning in
122a separate step, either as part of a stat (e.g. \code{\link[=stat_contour_filled]{stat_contour_filled()}}) or
123prior to the visualisation. If you want to use this guide for discrete data
124the levels must follow the naming scheme implemented by \code{\link[base:cut]{base::cut()}}. This
125means that a bin must be encoded as \code{"(<lower>, <upper>]"} with \verb{<lower>}
126giving the lower bound of the bin and \verb{<upper>} giving the upper bound
127(\code{"[<lower>, <upper>)"} is also accepted). If you use \code{\link[base:cut]{base::cut()}} to
128perform the binning everything should work as expected, if not, some recoding
129may be needed.
130}
131
132\examples{
133p <- ggplot(mtcars) +
134  geom_point(aes(disp, mpg, size = hp)) +
135  scale_size_binned()
136
137# Standard look
138p
139
140# Remove the axis or style it
141p + guides(size = guide_bins(axis = FALSE))
142
143p + guides(size = guide_bins(show.limits = TRUE))
144
145p + guides(size = guide_bins(
146  axis.arrow = arrow(length = unit(1.5, 'mm'), ends = 'both')
147))
148
149# Guides are merged together if possible
150ggplot(mtcars) +
151  geom_point(aes(disp, mpg, size = hp, colour = hp)) +
152  scale_size_binned() +
153  scale_colour_binned(guide = "bins")
154
155}
156\seealso{
157Other guides:
158\code{\link{guide_colourbar}()},
159\code{\link{guide_coloursteps}()},
160\code{\link{guide_legend}()},
161\code{\link{guides}()}
162}
163\concept{guides}
164