interp_scale: Interpolated color scale and palette

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

Interpolated color scale and palette

Description

Interpolate between colors to create a color scale, map values to colors along a scale, create a color palette, or get a few colors from a palette.

Usage

interp_scale(
  colors = c("white", "black"),
  model = "lab",
  interp = "linear",
  correct.lightness = FALSE,
  domain = c(0, 1),
  values = c(0, 1),
  reverse = FALSE,
  na.value = NULL,
  exact.until = 64
)

interp_map(x, ...)

interp_palette(...)

interp_colors(n, ...)

scale_color_interp(
  ...,
  colors = c("white", "black"),
  model = "lab",
  interp = "linear",
  correct.lightness = FALSE,
  reverse = FALSE,
  values = NULL,
  na.value = NULL,
  extrapolate = FALSE,
  exact.until = 100,
  guide = "colorbar"
)

scale_fill_interp(
  ...,
  colors = c("white", "black"),
  model = "lab",
  interp = "linear",
  correct.lightness = correct.lightness,
  reverse = FALSE,
  values = NULL,
  na.value = NULL,
  exact.until = 100,
  guide = "colorbar"
)

Arguments

colors	vector of colors specified as hex strings or named R colors. By default, those colors will be evenly distributed along the scale and new colors will be interpolated between them.
model	string defining the color model in which to perform the interpolation; valid models are lab (the default and usually most suitable), hcl, lch, hsi, hsl, hsv, rgb, lrgb. Beware that all but lab and (l)rgb can give surprising results.
interp	string defining the type of interpolation to perform; either linear (the default) or bezier, which results in a smoother transition between colors. bezier interpolation is only available with model="lab" however.
correct.lightness	whether to correct lightness to come closer to a linear increase in lightness along the scale, which is preferable perpectually. This correction is particularly effective together with bezier interpolation.
domain	vector of two values between which the scale is computed.
values	if colors should not be evenly positioned along the gradient, this vector gives the position along the scale of each color in the colors vector. This argument supersedes domain because it defines the bounds of the color scale.
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.
exact.until	integer, when more than exact.until colors need to be computed, a fast but not exact alternative algorithm is used. This should not make a difference visually unless the argument values is used and some transitions between input colors are sharp.
x	a vector whose values will be coerced to numbers and mapped to colors.
...	passed to interp_scale from other interp_* functions; passed to ggplot2::continuous_scale from the scale_* functions. NB: in all situations, passing domain or values is meaningless and yields an error.
n	number of colors to extract from the color palette.
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.
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).

See Also

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

Examples

# Define a color scale
coldhot <- interp_scale(c("#2B5DCD", "#EC2D38"))
# Apply it to some data
coldhot(c(0, 0.2, 0.6, 1))

# Define a palette
coldhot_pal <- interp_palette(c("#2B5DCD", "#EC2D38"))
# and get 10 colors from it
coldhot_pal(10)
show_col(coldhot_pal(10))
# Use the shortcut to define a palette and extract n colors from it
show_col(interp_colors(n=50, colors=c("#2B5DCD", "#EC2D38")))

# Test interpolation spaces and types
cols <- c("yellow", "blue", "red")
show_col(
   interp_colors(10, cols, model="lab"),
   interp_colors(10, cols, model="lab", interp="bez"),
   interp_colors(10, cols, model="rgb"),
   interp_colors(10, cols, model="hsv"),
   interp_colors(10, cols, model="hcl")
)

# Change mapping region/direction
x <- 0:10
cols <- c("aliceblue", "cornflowerblue", "dodgerblue4")
show_col(
   interp_scale(cols)(x),
   interp_scale(cols, domain=range(x))(x),
   interp_scale(cols, domain=range(x), reverse=TRUE)(x),
   interp_scale(cols, values=c(0,1,10))(x)
)

# Plot Maunga Whau volcano with colors picked from a picture
# (likely incorrect perceptually but attempts a "realistic" look)
topo_colors <- c("#C4B99F", "#282A19", "#61781B", "#BC9352")
show_col(topo_colors)
image(maunga, col=interp_colors(100, colors=topo_colors))
# = the dark ring-like level is indeed misleading

persp(maunga, theta=50, phi=25, scale=FALSE, expand=2,
      border=alpha("black", 0.4),
      col=interp_map(persp_facets(maunga$z), colors=topo_colors))

## Not run: 
library("rgl")
persp3d(maunga, aspect=c(1,0.7,0.2), axes=FALSE, box=FALSE,
        col=interp_map(maunga$z, colors=topo_colors))
play3d(spin3d(axis=c(0, 0, 1), rpm=10), duration=6)

library("ggplot2")
p <- ggplot(maungaxyz) + coord_fixed() +
  geom_raster(aes(x=x, y=y, fill=z)) +
  geom_contour(aes(x=x, y=y, z=z), color="white", alpha=0.5)
p + scale_fill_interp(colors=topo_colors)
p + scale_fill_interp(colors=topo_colors, model="hsl")
p + scale_fill_interp(colors=topo_colors, reverse=TRUE)
p + scale_fill_interp(colors=topo_colors, interp="bezier")

## End(Not run)

# Map a third variable on a scatterplot
attach(airquality)
# define a scale encompassing the whole data
coldhot <- interp_scale(c("#2B5DCD", "#EC2D38"), domain=c(0,200))
# use it on a plot and in the legend
pars <- sidemargin()
plot(Wind, Temp, col=coldhot(Ozone), pch=19)
sidelegend(legend=c(pretty(Ozone), "NA"),
           col=coldhot(c(pretty(Ozone), NA)), pch=19)
par(pars)
# note that the missing value color contrasts with the rest of the scale

## Not run: 
# Or in ggplot
library("ggplot2")
ggplot(airquality) +
  geom_point(aes(x=Wind, y=Temp, color=Ozone)) +
  scale_color_interp(colors=c("#2B5DCD", "#EC2D38"))
# Which is very similar to
ggplot(airquality) +
  geom_point(aes(x=Wind, y=Temp, color=Ozone)) +
  scale_color_gradientn(colors=c("#2B5DCD", "#EC2D38"))
# but scale_color_interp provides more options regarding how colors are
# interpolated (and is a bit slower).

## End(Not run)

# Continuous, interpolated color scales are not really appropriate for
# categorical variables. This works
attach(iris)
plot(Petal.Length, Petal.Width, pch=21, bg=interp_map(Species))
legend(1, 2, legend=levels(Species),
             pt.bg=interp_colors(n=nlevels(Species)), pch=21)
# but a hue-based scale would be much better (see ?hue_scale)

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