1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/scale-hue.r, R/zxx.r
3\name{scale_colour_hue}
4\alias{scale_colour_hue}
5\alias{scale_fill_hue}
6\alias{scale_color_hue}
7\title{Evenly spaced colours for discrete data}
8\usage{
9scale_colour_hue(
10  ...,
11  h = c(0, 360) + 15,
12  c = 100,
13  l = 65,
14  h.start = 0,
15  direction = 1,
16  na.value = "grey50",
17  aesthetics = "colour"
18)
19
20scale_fill_hue(
21  ...,
22  h = c(0, 360) + 15,
23  c = 100,
24  l = 65,
25  h.start = 0,
26  direction = 1,
27  na.value = "grey50",
28  aesthetics = "fill"
29)
30}
31\arguments{
32\item{...}{
33  Arguments passed on to \code{\link[=discrete_scale]{discrete_scale}}
34  \describe{
35    \item{\code{palette}}{A palette function that when called with a single integer
36argument (the number of levels in the scale) returns the values that
37they should take (e.g., \code{\link[scales:hue_pal]{scales::hue_pal()}}).}
38    \item{\code{breaks}}{One of:
39\itemize{
40\item \code{NULL} for no breaks
41\item \code{waiver()} for the default breaks (the scale limits)
42\item A character vector of breaks
43\item A function that takes the limits as input and returns breaks
44as output. Also accepts rlang \link[rlang:as_function]{lambda} function
45notation.
46}}
47    \item{\code{limits}}{One of:
48\itemize{
49\item \code{NULL} to use the default scale values
50\item A character vector that defines possible values of the scale and their
51order
52\item A function that accepts the existing (automatic) values and returns
53new ones. Also accepts rlang \link[rlang:as_function]{lambda} function
54notation.
55}}
56    \item{\code{drop}}{Should unused factor levels be omitted from the scale?
57The default, \code{TRUE}, uses the levels that appear in the data;
58\code{FALSE} uses all the levels in the factor.}
59    \item{\code{na.translate}}{Unlike continuous scales, discrete scales can easily show
60missing values, and do so by default. If you want to remove missing values
61from a discrete scale, specify \code{na.translate = FALSE}.}
62    \item{\code{scale_name}}{The name of the scale that should be used for error messages
63associated with this scale.}
64    \item{\code{name}}{The name of the scale. Used as the axis or legend title. If
65\code{waiver()}, the default, the name of the scale is taken from the first
66mapping used for that aesthetic. If \code{NULL}, the legend title will be
67omitted.}
68    \item{\code{labels}}{One of:
69\itemize{
70\item \code{NULL} for no labels
71\item \code{waiver()} for the default labels computed by the
72transformation object
73\item A character vector giving labels (must be same length as \code{breaks})
74\item A function that takes the breaks as input and returns labels
75as output. Also accepts rlang \link[rlang:as_function]{lambda} function
76notation.
77}}
78    \item{\code{expand}}{For position scales, a vector of range expansion constants used to add some
79padding around the data to ensure that they are placed some distance
80away from the axes. Use the convenience function \code{\link[=expansion]{expansion()}}
81to generate the values for the \code{expand} argument. The defaults are to
82expand the scale by 5\% on each side for continuous variables, and by
830.6 units on each side for discrete variables.}
84    \item{\code{guide}}{A function used to create a guide or its name. See
85\code{\link[=guides]{guides()}} for more information.}
86    \item{\code{position}}{For position scales, The position of the axis.
87\code{left} or \code{right} for y axes, \code{top} or \code{bottom} for x axes.}
88    \item{\code{super}}{The super class to use for the constructed scale}
89  }}
90
91\item{h}{range of hues to use, in [0, 360]}
92
93\item{c}{chroma (intensity of colour), maximum value varies depending on
94combination of hue and luminance.}
95
96\item{l}{luminance (lightness), in [0, 100]}
97
98\item{h.start}{hue to start at}
99
100\item{direction}{direction to travel around the colour wheel,
1011 = clockwise, -1 = counter-clockwise}
102
103\item{na.value}{Colour to use for missing values}
104
105\item{aesthetics}{Character string or vector of character strings listing the
106name(s) of the aesthetic(s) that this scale works with. This can be useful, for
107example, to apply colour settings to the \code{colour} and \code{fill} aesthetics at the
108same time, via \code{aesthetics = c("colour", "fill")}.}
109}
110\description{
111Maps each level to an evenly spaced hue on the colour wheel.
112It does not generate colour-blind safe palettes.
113}
114\examples{
115\donttest{
116dsamp <- diamonds[sample(nrow(diamonds), 1000), ]
117(d <- ggplot(dsamp, aes(carat, price)) + geom_point(aes(colour = clarity)))
118
119# Change scale label
120d + scale_colour_hue()
121d + scale_colour_hue("clarity")
122d + scale_colour_hue(expression(clarity[beta]))
123
124# Adjust luminosity and chroma
125d + scale_colour_hue(l = 40, c = 30)
126d + scale_colour_hue(l = 70, c = 30)
127d + scale_colour_hue(l = 70, c = 150)
128d + scale_colour_hue(l = 80, c = 150)
129
130# Change range of hues used
131d + scale_colour_hue(h = c(0, 90))
132d + scale_colour_hue(h = c(90, 180))
133d + scale_colour_hue(h = c(180, 270))
134d + scale_colour_hue(h = c(270, 360))
135
136# Vary opacity
137# (only works with pdf, quartz and cairo devices)
138d <- ggplot(dsamp, aes(carat, price, colour = clarity))
139d + geom_point(alpha = 0.9)
140d + geom_point(alpha = 0.5)
141d + geom_point(alpha = 0.2)
142
143# Colour of missing values is controlled with na.value:
144miss <- factor(sample(c(NA, 1:5), nrow(mtcars), replace = TRUE))
145ggplot(mtcars, aes(mpg, wt)) +
146  geom_point(aes(colour = miss))
147ggplot(mtcars, aes(mpg, wt)) +
148  geom_point(aes(colour = miss)) +
149  scale_colour_hue(na.value = "black")
150}
151}
152\seealso{
153Other colour scales:
154\code{\link{scale_alpha}()},
155\code{\link{scale_colour_brewer}()},
156\code{\link{scale_colour_continuous}()},
157\code{\link{scale_colour_gradient}()},
158\code{\link{scale_colour_grey}()},
159\code{\link{scale_colour_steps}()},
160\code{\link{scale_colour_viridis_d}()}
161}
162\concept{colour scales}
163