hue_scale: Hue scale and palette

In jiho/chroma: Parse and Manipulate Colors, Create Perceptually Correct Color Palettes

Hue scale and palette

Description

Hue-based color scale, in HCL space.

Usage

hue_scale(
  h = c(0, 360) + 40,
  c = 0.65,
  l = 0.65,
  domain = c(0, 1),
  reverse = FALSE,
  full.circle = FALSE,
  na.value = NULL,
  extrapolate = FALSE
)

hue_map(x, ...)

hue_palette(...)

hue_colors(n, ...)

scale_color_hue_c(
  ...,
  h = c(250, 350),
  c = 0.65,
  l = 0.65,
  reverse = FALSE,
  full.circle = FALSE,
  na.value = NULL,
  guide = "colorbar"
)

scale_fill_hue_c(
  ...,
  h = c(250, 350),
  c = 0.65,
  l = 0.65,
  reverse = FALSE,
  full.circle = FALSE,
  na.value = NULL,
  guide = "colorbar"
)

scale_color_hue_d(
  ...,
  h = c(0, 360) + 40,
  c = 0.65,
  l = 0.65,
  reverse = FALSE,
  full.circle = FALSE,
  na.value = NULL,
  guide = "legend"
)

scale_fill_hue_d(
  ...,
  h = c(0, 360) + 40,
  c = 0.65,
  l = 0.65,
  reverse = FALSE,
  full.circle = FALSE,
  na.value = NULL,
  guide = "legend"
)

Arguments

h	range of hues to use, a vector of length 2 with either angles around the color wheel, in [0,360] (angles outside of the range are rotated back to within [0,360]: 380 = 20, -15 = 345, etc.), or colors (hex or named) from which the hue is extracted (by function hue).
c	chromacity, number in [0,~1]; 0 is grey, ~1 is full color.
l	lightness, number in [0,1]; 0 is darkest, 1 is brightest.
domain	vector of two values between which the scale is computed.
reverse	whether to reverse the order of colors along the scale.
full.circle	when the range of hues specified in h spans 360°, this argument determines if the color scale should also span the full circle (which results in the same color being associated with different values, at the extremes of the scale), or not. By default it is set to FALSE to avoid this caveat. When h does not span 360°, this argument is ignored because the caveat disappears.
na.value	value to return for missing values in the input. Can be either a color, NULL in which case a tentitatively appropriate color will be chosen automatically, or NA.
extrapolate	when FALSE, the default, return NA for input values that are out of the domain; when TRUE return the color corresponding to the extreme of the domain instead.
x	a vector whose values will be coerced to numbers and mapped to colors.
...	passed to hue_scale from other hue_* functions; passed to ggplot2::continuous_scale or ggplot2::discrete_scale from the scale_* functions, as appropriate. NB: in all situations, passing domain is meaningless and yields an error.
n	number of colors to extract from the color palette.
guide	type of guide for the legend ("colorbar" for a continuous colorbar, "legend" for a categorical guide) or guide object itself.

Details

In HCL space, the perceived color (hue) is completely separated from the perceived intensity (chromacity) and lightness of the color. This means that colors of various hues but same chromacity and lightness appear as the exact same grey when converted to greyscale. This makes the HCL space particularly suitable to create good color palettes:

• For qualitative palettes (discrete variables): varying h at constant c and l avoids drawing attention to certain hues, as would happen if the same was done in HSV or HSL space. Indeed, some hues are perceived as brighter (yellow, light green, etc.), others as duller/darker (blues, etc.).

• For sequential palettes (continuous variables): varying l (or possibly c) for a constant h gives a sense of direction and avoid the many perceptual pitfalls typical of 'rainbow'-like scales.

Value

*_scale returns a function. This function takes a single argument (x: a numeric vector), maps its values to colors, and returns thee colors as hex codes.

*_map is a shortcut for *_scale(domain=range(x))(x): it creates a scale that spans the range of values in argument x, maps the content of x on that scale, and returns the colors.

*_palette returns a function. This function takes an integer (n) as argument, picks n colors evenly spaced along the scale, and returns them as hex codes.

*_colors is a shortcut for *_palette()(n) and directly returns n evenly spaced colors. It is equivalent to built-in functions such as heat.colors, topo.colors, etc.

scale_* return a ggplot2 scale, either discrete (similar to scale_color_discrete) or continuous (similar to scale_color_continuous).

See Also

The hcl function, on which this one is based.

Other HCL-based scales: chroma_scale(), light_scale()

Other color scales and palettes: brewer_scale(), chroma_scale(), cubehelix_scale(), etopo_scale(), inferno_scale(), interp_scale(), light_scale(), magma_scale(), plasma_scale(), turbo_scale(), viridis_scale(), wikitopo_scale()

Examples

# Display the full hue range with
x <- 0:360
plot(x, rep(0,length(x)), col=hue_map(x, h=c(0,360), full.circle=TRUE), ylab="", pch="|", cex=5)

# Define a perceptually-correct "rainbow"-like scale function
rainbow_scale <- hue_scale()
# and apply it to some data
show_col(rainbow_scale(x=c(0, 0.2, 0.6, 1)))

# Define a palette function
# (which works like the actual rainbow() function)
rainbow_pal <- hue_palette()
# and get 10 colors from it
rainbow_pal(n=10)
show_col(rainbow_pal(n=10))
# or use the shortcut
hue_colors(n=50)
show_col(hue_colors(n=50))

# Palettes of varying hue but constant chromacity and lightness
# are appropriate to distinguish among levels of a qualitative variable
attach(iris)
plot(Petal.Length, Petal.Width, col=hue_map(Species), pch=19)
legend(1, 2, legend=levels(Species), col=hue_colors(n=nlevels(Species)), pch=19)

# Let us try with a quantitative variable
image(maunga, col=hue_colors(100))
# = typical rainbow scale bullseye effect, yuk!
# but, with a limited hue range, they can be OK
image(maunga, col=hue_colors(10, h=c(170, 90), l=0.6))
contour(maunga, col=alpha("white", 0.5), add=TRUE)

persp(maunga, theta=50, phi=25, scale=FALSE, expand=2,
      border=alpha("black", 0.4),
      col=hue_map(persp_facets(maunga$z), h=c(170, 90), l=0.6))
# Still, lightness (or chromacity) based scales are likely to be better...

# To create a legend for a continuous variable, we need to define the
# scale with its domain and then use it for both the plot and the legend.
attach(airquality)
oz_scale <- hue_scale(h=c(250,350), l=0.5, domain=range(Ozone, na.rm=TRUE))
plot(Wind, Temp, col=oz_scale(Ozone), pch=19)
legend(17, 95, legend=pretty(Ozone), col=oz_scale(pretty(Ozone)), pch=19)

# Note how the missing value grey matches the rest of the colors on the scale
plot(Wind, Temp, col=hue_map(Ozone, h=c(250,350), l=0.5), pch=19)
plot(Wind, Temp, col=hue_map(Ozone, h=c(250,350), l=0.8), pch=19)
plot(Wind, Temp, col=hue_map(Ozone, h=c(250,350), l=0.3), pch=19)

# Make the plot nicer to read by putting the legend on the side
pars <- sidemargin()
plot(Wind, Temp, col=oz_scale(Ozone), pch=19)
sidelegend(legend=pretty(Ozone), col=oz_scale(pretty(Ozone)), pch=19)
par(pars)

## Not run: 
# or just use ggplot2
library("ggplot2")
ggplot(iris) +
  geom_point(aes(x=Petal.Length, y=Petal.Width, color=Species)) +
  scale_color_hue_d()
ggplot(airquality) +
  geom_point(aes(x=Wind, y=Temp, color=Ozone)) +
  scale_color_hue_c()
## End(Not run)

jiho/chroma documentation built on Nov. 26, 2022, 2:39 a.m.