File: scale_brewer.Rd

package info (click to toggle)
r-cran-ggplot2 3.5.1%2Bdfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: sid, trixie
  • size: 9,944 kB
  • sloc: sh: 15; makefile: 5
file content (207 lines) | stat: -rw-r--r-- 6,517 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scale-brewer.R, R/zxx.R
\name{scale_colour_brewer}
\alias{scale_colour_brewer}
\alias{scale_fill_brewer}
\alias{scale_colour_distiller}
\alias{scale_fill_distiller}
\alias{scale_colour_fermenter}
\alias{scale_fill_fermenter}
\alias{scale_color_brewer}
\alias{scale_color_distiller}
\alias{scale_color_fermenter}
\title{Sequential, diverging and qualitative colour scales from ColorBrewer}
\usage{
scale_colour_brewer(
  name = waiver(),
  ...,
  type = "seq",
  palette = 1,
  direction = 1,
  aesthetics = "colour"
)

scale_fill_brewer(
  name = waiver(),
  ...,
  type = "seq",
  palette = 1,
  direction = 1,
  aesthetics = "fill"
)

scale_colour_distiller(
  name = waiver(),
  ...,
  type = "seq",
  palette = 1,
  direction = -1,
  values = NULL,
  space = "Lab",
  na.value = "grey50",
  guide = "colourbar",
  aesthetics = "colour"
)

scale_fill_distiller(
  name = waiver(),
  ...,
  type = "seq",
  palette = 1,
  direction = -1,
  values = NULL,
  space = "Lab",
  na.value = "grey50",
  guide = "colourbar",
  aesthetics = "fill"
)

scale_colour_fermenter(
  name = waiver(),
  ...,
  type = "seq",
  palette = 1,
  direction = -1,
  na.value = "grey50",
  guide = "coloursteps",
  aesthetics = "colour"
)

scale_fill_fermenter(
  name = waiver(),
  ...,
  type = "seq",
  palette = 1,
  direction = -1,
  na.value = "grey50",
  guide = "coloursteps",
  aesthetics = "fill"
)
}
\arguments{
\item{name}{The name of the scale. Used as the axis or legend title. If
\code{waiver()}, the default, the name of the scale is taken from the first
mapping used for that aesthetic. If \code{NULL}, the legend title will be
omitted.}

\item{...}{Other arguments passed on to \code{\link[=discrete_scale]{discrete_scale()}}, \code{\link[=continuous_scale]{continuous_scale()}},
or \code{\link[=binned_scale]{binned_scale()}}, for \code{brewer}, \code{distiller}, and \code{fermenter} variants
respectively, to control name, limits, breaks, labels and so forth.}

\item{type}{One of "seq" (sequential), "div" (diverging) or "qual"
(qualitative)}

\item{palette}{If a string, will use that named palette. If a number, will index into
the list of palettes of appropriate \code{type}. The list of available palettes can found
in the Palettes section.}

\item{direction}{Sets the order of colours in the scale. If 1, the default,
colours are as output by \code{\link[RColorBrewer:ColorBrewer]{RColorBrewer::brewer.pal()}}. If -1, the
order of colours is reversed.}

\item{aesthetics}{Character string or vector of character strings listing the
name(s) of the aesthetic(s) that this scale works with. This can be useful, for
example, to apply colour settings to the \code{colour} and \code{fill} aesthetics at the
same time, via \code{aesthetics = c("colour", "fill")}.}

\item{values}{if colours should not be evenly positioned along the gradient
this vector gives the position (between 0 and 1) for each colour in the
\code{colours} vector. See \code{\link[scales:rescale]{rescale()}} for a convenience function
to map an arbitrary range to between 0 and 1.}

\item{space}{colour space in which to calculate gradient. Must be "Lab" -
other values are deprecated.}

\item{na.value}{Colour to use for missing values}

\item{guide}{Type of legend. Use \code{"colourbar"} for continuous
colour bar, or \code{"legend"} for discrete colour legend.}
}
\description{
The \code{brewer} scales provide sequential, diverging and qualitative
colour schemes from ColorBrewer. These are particularly well suited to
display discrete values on a map. See \url{https://colorbrewer2.org} for
more information.
}
\details{
The \code{brewer} scales were carefully designed and tested on discrete data.
They were not designed to be extended to continuous data, but results often
look good. Your mileage may vary.
}
\note{
The \code{distiller} scales extend \code{brewer} scales by smoothly
interpolating 7 colours from any palette to a continuous scale.
The \code{distiller} scales have a default direction = -1. To reverse, use direction = 1.
The \code{fermenter} scales provide binned versions of the \code{brewer} scales.
}
\section{Palettes}{

The following palettes are available for use with these scales:
\describe{
\item{Diverging}{BrBG, PiYG, PRGn, PuOr, RdBu, RdGy, RdYlBu, RdYlGn, Spectral}
\item{Qualitative}{Accent, Dark2, Paired, Pastel1, Pastel2, Set1, Set2, Set3}
\item{Sequential}{Blues, BuGn, BuPu, GnBu, Greens, Greys, Oranges,
OrRd, PuBu, PuBuGn, PuRd, Purples, RdPu, Reds, YlGn, YlGnBu, YlOrBr, YlOrRd}
}
Modify the palette through the \code{palette} argument.
}

\examples{
set.seed(596)
dsamp <- diamonds[sample(nrow(diamonds), 1000), ]
(d <- ggplot(dsamp, aes(carat, price)) +
  geom_point(aes(colour = clarity)))
d + scale_colour_brewer()

# Change scale label
d + scale_colour_brewer("Diamond\nclarity")

# Select brewer palette to use, see ?scales::pal_brewer for more details
d + scale_colour_brewer(palette = "Greens")
d + scale_colour_brewer(palette = "Set1")

\donttest{
# scale_fill_brewer works just the same as
# scale_colour_brewer but for fill colours
p <- ggplot(diamonds, aes(x = price, fill = cut)) +
  geom_histogram(position = "dodge", binwidth = 1000)
p + scale_fill_brewer()
# the order of colour can be reversed
p + scale_fill_brewer(direction = -1)
# the brewer scales look better on a darker background
p +
  scale_fill_brewer(direction = -1) +
  theme_dark()
}

# Use distiller variant with continuous data
v <- ggplot(faithfuld) +
  geom_tile(aes(waiting, eruptions, fill = density))
v
v + scale_fill_distiller()
v + scale_fill_distiller(palette = "Spectral")
# the order of colour can be reversed, but with scale_*_distiller(),
# the default direction = -1, so to reverse, use direction = 1.
v + scale_fill_distiller(palette = "Spectral", direction = 1)

# or use blender variants to discretise continuous data
v + scale_fill_fermenter()

}
\seealso{
The documentation on \link[=aes_colour_fill_alpha]{colour aesthetics}.

The \href{https://ggplot2-book.org/scales-colour#brewer-scales}{brewer scales section} of the online ggplot2 book.

Other colour scales: 
\code{\link{scale_alpha}()},
\code{\link{scale_colour_continuous}()},
\code{\link{scale_colour_gradient}()},
\code{\link{scale_colour_grey}()},
\code{\link{scale_colour_hue}()},
\code{\link{scale_colour_identity}()},
\code{\link{scale_colour_manual}()},
\code{\link{scale_colour_steps}()},
\code{\link{scale_colour_viridis_d}()}
}
\concept{colour scales}