cubehelix_scale: CubeHelix color scale and palette

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

CubeHelix color scale and palette

Description

The CubeHelix color palette, by Dave Green (Unlicense license).

Usage

cubehelix_scale(
  h = 300,
  rot = -1.5,
  c = 0.5,
  l = c(0.1, 0.9),
  gamma = 1,
  domain = c(0, 1),
  reverse = FALSE,
  na.value = NULL,
  extrapolate = FALSE
)

cubehelix_map(x, ...)

cubehelix_palette(...)

cubehelix_colors(n, ...)

scale_color_cubehelix_c(
  ...,
  h = 300,
  rot = -1.5,
  c = 0.5,
  l = c(0.1, 0.9),
  gamma = 1,
  reverse = FALSE,
  na.value = NULL,
  guide = "colorbar"
)

scale_fill_cubehelix_c(
  ...,
  h = 300,
  rot = -1.5,
  c = 0.5,
  l = c(0.1, 0.9),
  gamma = 1,
  reverse = FALSE,
  na.value = NULL,
  guide = "colorbar"
)

scale_color_cubehelix_d(
  ...,
  h = 300,
  rot = -1.5,
  c = 0.5,
  l = c(0.1, 0.9),
  gamma = 1,
  reverse = FALSE,
  na.value = "#grey50",
  guide = "legend"
)

scale_fill_cubehelix_d(
  ...,
  h = 300,
  rot = -1.5,
  c = 0.5,
  l = c(0.1, 0.9),
  gamma = 1,
  reverse = FALSE,
  na.value = "#grey50",
  guide = "legend"
)

Arguments

h	hue, either an angle 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 a color (hex or named) from which the hue is extracted (by function hue).
rot	number of rotations of the helix in RGB space, in [-2,2] (1 = 360°, -1.5 = -540°)
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.
gamma	gamma contrast factor, in [0,+Inf] (sane values are in [0.5,3]). gamma < 1 emphasises the low end of the scale by whitening the high colors. gamma > 1 emphasises the high end of the scale by darkening the low colors. Use with caution and restraint.
domain	vector of two values between which the scale is computed.
reverse	whether to reverse the order of colors along the scale.
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 cubehelix_scale. Note that argument domain is meaningless in functions other than cubehelix_scale and passing it through ... is 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.

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).

References

https://www.mrao.cam.ac.uk/~dag/CUBEHELIX/

See Also

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

Examples

# Basic color palettes
show_col(
  cubehelix_colors(20),
  cubehelix_colors(20, reverse=TRUE)
)

# Rotating less gives more sensible scales
show_col(
  cubehelix_colors(20, h=300, rot=-0.75),
  cubehelix_colors(20, h=300, rot=0.5)
)

# No rotation gives single hue palettes
show_col(
  cubehelix_colors(20, h=0  , rot=0, c=0.8),
  cubehelix_colors(20, h=120, rot=0, c=0.8),
  cubehelix_colors(20, h=200, rot=0, c=0.8)
)

# Examine the effect of the other arguments
show_col(
  cubehelix_colors(20, h=300, rot=0.5),
  # smaller range of lightness change
  cubehelix_colors(20, h=300, rot=0.5, l=c(0.2, 0.7)),
  # change chromacity
  cubehelix_colors(20, h=300, rot=0.5, c=0.9),
  cubehelix_colors(20, h=300, rot=0.5, c=0.3),
  # change gamma contrast factor
  cubehelix_colors(20, h=300, rot=0.5, gamma=0.5),
  cubehelix_colors(20, h=300, rot=0.5, gamma=1.5)
)

# Plot the Maunga Whau volcano elevation map: a continuous variable
image(maunga, col=cubehelix_colors(100, rot=-0.75))
contour(maunga, col=alpha("black", 0.4), add=TRUE)

persp(maunga, theta=50, phi=25, scale=FALSE, expand=2,
      border=alpha("black", 0.4),
      col=cubehelix_map(persp_facets(maunga$z), rot=-0.75))

## Not run: 
# in spinning 3D
library("rgl")
persp3d(maunga, aspect=c(1,0.7,0.2), axes=FALSE, box=FALSE,
        col=cubehelix_map(maunga$z, rot=-0.75))
play3d(spin3d(axis=c(0, 0, 1), rpm=10), duration=6)

# or with ggplot2
library(ggplot2)
ggplot(maungaxyz) + coord_fixed() +
  geom_raster(aes(x, y, fill=z)) +
  scale_fill_cubehelix_c(rot=-0.75)

## End(Not run)

# For discrete variables, using saturated colors along a scale of
# constant lightness gives a good hue-only scale
attach(iris)
plot(Petal.Length, Sepal.Length, pch=19,
  col=cubehelix_map(
    Species,
    h=0, rot=0.75, # Start from red-ish and do not rotate
                   # full circle to avoid falling back on red
    c=1,           # Use saturated colors
    l=c(0.6, 0.6) # Do not vary lightness
  )
)
legend(1, 8, legend=levels(Species), pch=19,
       col=cubehelix_map(1:3, h=0, rot=0.75, c=1, l=c(0.6, 0.6)))
detach(iris)
## Not run: ggplot(iris) +
  geom_point(aes(Petal.Length, Sepal.Length, color=Species)) +
  scale_color_cubehelix_d(h=0, rot=0.75, c=1, l=c(0.6, 0.6))

## End(Not run)
# But see ?hue_scale for a simpler solution

jiho/chroma documentation built on Feb. 5, 2025, 10:32 p.m.