,
Kurt Hornik [aut] ,
Jason C. Fisher [aut] ,
Reto Stauffer [aut] ,
Claus O. Wilke [aut] ,
Claire D. McWhite [aut] ,
Achim Zeileis [aut, cre] | Title: | A Toolbox for Manipulating and Assessing Colors and Palettes |
|---|---|
| Description: | Carries out mapping between assorted color spaces including RGB, HSV, HLS, CIEXYZ, CIELUV, HCL (polar CIELUV), CIELAB, and polar CIELAB. Qualitative, sequential, and diverging color palettes based on HCL colors are provided along with corresponding ggplot2 color scales. Color palette choice is aided by an interactive app (with either a Tcl/Tk or a shiny graphical user interface) and shiny apps with an HCL color picker and a color vision deficiency emulator. Plotting functions for displaying and assessing palettes include color swatches, visualizations of the HCL space, and trajectories in HCL and/or RGB spectrum. Color manipulation functions include: desaturation, lightening/darkening, mixing, and simulation of color vision deficiencies (deutanomaly, protanomaly, tritanomaly). Details can be found on the project web page at <https://colorspace.R-Forge.R-project.org/> and in the accompanying scientific paper: Zeileis et al. (2020, Journal of Statistical Software, <doi:10.18637/jss.v096.i01>). |
| Authors: | Ross Ihaka [aut],
Paul Murrell [aut] ,
Kurt Hornik [aut] ,
Jason C. Fisher [aut] ,
Reto Stauffer [aut] ,
Claus O. Wilke [aut] ,
Claire D. McWhite [aut] ,
Achim Zeileis [aut, cre] |
| Maintainer: | Achim Zeileis <[email protected]> |
| License: | BSD_3_clause + file LICENSE |
| Version: | 2.1-1 |
| Built: | 2024-03-26 06:26:24 UTC |
| Source: | https://github.com/r-forge/colorspace |
Adjust (i.e., add, remove, or modify) or extract alpha transparency of a vector of colors.
adjust_transparency(col, alpha = TRUE)
extract_transparency(col, mode = "numeric", default = 1)col |
vector of R colors. Can be any of the three kinds of R colors,
i.e., either a color name (an element of
|
alpha |
either a new alpha transparency value or logical (to add/remove alpha)
or |
mode |
character specifying the output mode for the alpha transparency, can be
|
default |
vector of length 1 specifying the default alpha transparency that should be returned for colors that do not specify any explicitly (defaulting to fully opaque). Can either be numeric, integer, character, or hexmode. |
Alpha transparency is useful for making colors semi-transparent, e.g., for overlaying different elements in graphics. An alpha value of 0 (or 00 in hex strings) corresponds to fully transparent and an alpha value of 1 (or FF in hex strings) corresponds to fully opaque. If a color hex string in R does not provide an explicit alpha transparency, the color is assumed to be fully opaque.
The adjust_transparency function can be used to adjust the alpha transparency
of a set of colors. It always returns a hex color specification. This hex color
can have the alpha transparency added/removed/modified depending on the
specification of alpha:
alpha = NULL: Returns a hex vector with alpha transparency only if needed.
Thus, it keeps the alpha transparency for the colors (if any) but only if
different from opaque.
alpha = TRUE: Returns a hex vector with alpha transparency
for all colors, using opaque (FF) as the default if missing.
alpha = FALSE: Returns a hex vector without alpha transparency for
all colors (even if the original colors had non-opaque alpha).
alpha numeric: Returns a hex vector with alpha transparency for
all colors set to the alpha argument (recycled if necessary).
The extract_transparency function can be used to extract the alpha transparency
from a set of colors. It allows to specify the default value - that should be used
for colors without an explicit alpha transparency (defaulting to fully opaque) - and
mode of the return value. This can either be numeric (in [0, 1]), integer
(0L, 1L, ..., 255L), character (“00”, “01”, ..., “FF”),
or an object of class hexmode (internally represented as integer
with printing as character). The default can use any of these modes as well
(independent of the output mode) or be NA.
For adjust_transparency character vector with hexadecimal color strings with alpha transparency
corresponding to alpha argument. For extract_transparency a vector of
alpha transparency values with the indicated mode.
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
## modify transparency of a color (in different formats)
adjust_transparency("black", alpha = c(0, 0.5, 1)) ## name
adjust_transparency("#000000", alpha = c(0, 0.5, 1)) ## hex string
adjust_transparency(1, alpha = c(0, 0.5, 1)) ## palette() integer
## three shades of gray (in different formats:
## name/opaque, hex/opaque, hex/semi-transparent)
x <- c("gray", "#BEBEBE", "#BEBEBE80")
## adjust transparency
adjust_transparency(x, alpha = NULL) ## only if necessary
adjust_transparency(x, alpha = TRUE) ## add
adjust_transparency(x, alpha = FALSE) ## remove
adjust_transparency(x, alpha = 0.8) ## modify
## extract transparency in different formats
extract_transparency(x, mode = "numeric") ## default
extract_transparency(x, mode = "integer")
extract_transparency(x, mode = "character")
extract_transparency(x, mode = "hexmode")
## extract transparency with different default values
extract_transparency(x, default = NA)
extract_transparency(x, default = 0.5)
extract_transparency(x, default = 128L)
extract_transparency(x, default = "80", mode = "integer")A graphical user interface (GUI) for viewing, manipulating, and choosing HCL color palettes.
choose_palette(pal = diverging_hcl, n = 7L, parent = NULL, gui = "tcltk", ...)
hclwizard(n = 7L, gui = "shiny", ...)pal |
function; the initial palette, see ‘Value’ below. Only
used if |
n |
integer; the initial number of colors in the palette. |
parent |
tkwin; the GUI parent window. Only used if |
gui |
character; GUI to use. Available options are |
... |
used for development purposes only. |
Computes palettes based on the HCL (hue-chroma-luminance) color model (as
implemented by polarLUV). The GUIs interface the palette
functions qualitative_hcl for qualitative palettes,
sequential_hcl for sequential palettes with a single or
multiple hues, and diverging_hcl for diverging palettes (composed
from two single-hue sequential palettes).
Two different GUIs are implemented and can be selected using the function
input argument gui ("tcltk" or "shiny"). Both GUIs
allows for interactive modification of the arguments of the respective
palette-generating functions, i.e., starting/ending hue (wavelength, type of
color), minimal/maximal chroma (colorfulness), minimal maximal luminance
(brightness, amount of gray), and a power transformations that control how
quickly/slowly chroma and/or luminance are changed through the palette.
Subsets of the parameters may not be applicable depending on the type of
palette chosen. See qualitative_hcl and Zeileis et al. (2009, 2019) for
a more detailed explanation of the different arguments. Stauffer et al.
(2015) provide more examples and guidance.
Optionally, active palette can be illustrated by using a range of examples such as a map, heatmap, scatter plot, perspective 3D surface etc.
To demonstrate different types of deficiencies, the active palette may be
desaturated (emulating printing on a grayscale printer) and collapsed to
emulate different types of color-blindness (without red-green or green-blue
contrasts) using the simulate_cvd functions.
choose_palette by default starts the Tcl/Tk version of the GUI while
hclwizard by default starts the shiny version. hcl_wizard is
an alias for hclwizard.
Returns a palette-generating function with the selected arguments. Thus, the returned function takes an integer argument and returns the corresponding number of HCL colors by traversing HCL space through interpolation of the specified hue/chroma/luminance/power values.
Jason C. Fisher, Reto Stauffer, Achim Zeileis
Zeileis A, Hornik K, Murrell P (2009). Escaping RGBland: Selecting Colors for Statistical Graphics. Computational Statistics & Data Analysis, 53, 3259–3270. doi:10.1016/j.csda.2008.11.033 Preprint available from https://www.zeileis.org/papers/Zeileis+Hornik+Murrell-2009.pdf.
Stauffer R, Mayr GJ, Dabernig M, Zeileis A (2015). Somewhere over the Rainbow: How to Make Effective Use of Colors in Meteorological Visualizations. Bulletin of the American Meteorological Society, 96(2), 203–216. doi:10.1175/BAMS-D-13-00155.1
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
simulate_cvd, desaturate, qualitative_hcl.
if(interactive()) {
## Using tcltk GUI
pal <- choose_palette()
## or equivalently: hclwizard(gui = "tcltk")
## Using shiny GUI
pal <- hclwizard()
## or equivalently: choose_palette(gui = "shiny")
## use resulting palette function
filled.contour(volcano, color.palette = pal, asp = 1)
}Objects from the class color represent colors in a number of color spaces. In particular, there are subclasses of color which correspond to RGB, HSV, HLS, CIEXYZ, CIELUV, CIELAB and polar versions of the last two spaces.
Objects can be created by calls to the
functions RGB, sRGB, HSV, HLS, XYZ,
LUV, LAB, polarLUV, and polarLAB. These are all
subclasses of the virtual class color.
coords:An object of class "matrix".
signature(x = "color"): This method makes it possible to
take subsets of a vector of colors.
signature(from = "color", to = "RGB"): convert
a color vector to RGB.
signature(from = "color", to = "sRGB"): convert
a color vector to sRGB.
signature(from = "color", to = "XYZ"): convert
a color vector to XYZ.
signature(from = "color", to = "LAB"): convert
a color vector to LAB.
signature(from = "color", to = "polarLAB"): convert
a color vector to polarLAB.
signature(from = "color", to = "HSV"): convert
a color vector to HSV.
signature(from = "color", to = "HLS"): convert
a color vector to HLS.
signature(from = "color", to = "LUV"): convert
a color vector to LUV.
signature(from = "color", to = "polarLUV"): convert
a color vector to polarLUV.
signature(color = "color"): extract the color
coordinates from a color vector.
signature(x = "color"): plot a color vector
signature(object = "color"): show a color vector.
Ross Ihaka
RGB, XYZ, HSV,
HLS, LAB, polarLAB,
LUV, polarLUV, mixcolor.
x <- sRGB(runif(1000), runif(1000), runif(1000))
plot(as(x, "LUV"))Compute (and visualize) the contrast ratio of pairs of colors, as defined by the World Wide Web Consortium (W3C).
contrast_ratio(
col,
col2 = "white",
algorithm = c("WCAG", "APCA"),
plot = FALSE,
border = FALSE,
cex = 2,
off = 0.05,
mar = rep(0.5, 4),
digits = 2L,
...
)
col, col2
|
vectors of any of the three kind of R colors, i.e., either a color
name (an element of |
algorithm |
character specifying whether the established standard |
plot |
logical indicating whether the contrast ratios should also be visualized by simple color swatches. Can also be a vector of length 2, indicating whether the foreground color should be visualized on the background color and/or the background color on the foreground color. |
border |
logical or color specification for the borders around the color swatches (only
used if |
cex |
numeric. Size of the text in the color color swatches (only if |
off |
numeric. Vertical offset between the different color swatches (only if |
mar |
numeric. Size of the margins around the color swatches (only if |
digits |
numeric. Number of digits for the contrast ratios displayed in the color swatches
(only if |
... |
further arguments passed to the plot of the color swatches (only if |
The W3C Content Accessibility Guidelines (WCAG) recommend a contrast ratio of at least 4.5 for the color of regular text on the background color, and a ratio of at least 3 for large text. See https://www.w3.org/TR/WCAG21/#contrast-minimum.
The contrast ratio is defined in https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
as (L1 + 0.05) / (L2 + 0.05) where L1 and L2 are the relative luminances
(see https://www.w3.org/TR/WCAG21/#dfn-relative-luminance) of the lighter and darker
colors, respectively. The relative luminances are weighted sums of scaled sRGB coordinates:
0.2126 * R + 0.7152 * G + 0.0722 * B where each of R, G, and B
is defined as ifelse(RGB <= 0.03928, RGB/12.92, ((RGB + 0.055)/1.055)^2.4) based on
the RGB coordinates between 0 and 1.
For use in the next major revision of the WCAG a new advanced perceptual contrast algorithm (APCA) has been proposed by Somers (2022), see also Muth (2022) for more background and details. APCA is still under development, here version 0.98G-4g is implemented. Unlike the standard WCAG algorithm, APCA takes into account which color is the text and which is the background. Hence for the APCA algorithm a matrix with normal and reverse polarity is returned. An absolute value of 45 is "sort of" like a WCAG ratio of 3, 60 is "sort of" like 4.5.
A numeric vector with the contrast ratios is returned (invisibly, if plot is TRUE).
W3C (2018). “Web Content Accessibility Guidelines (WCAG) 2.1.” https://www.w3.org/TR/WCAG21/
Somers A (2022). “Advanced Perceptual Contrast Algorithm.” https://github.com/Myndex/SAPC-APCA
Muth LC (2022). “It's Time for a More Sophisticated Color Contrast Check for Data Visualizations.” Datawrapper Blog. https://blog.datawrapper.de/color-contrast-check-data-vis-wcag-apca/
# check contrast ratio of default palette on white background
contrast_ratio(palette(), "white")
# visualize contrast ratio of default palette on white and black background
contrast_ratio(palette(), "white", plot = TRUE)
contrast_ratio(palette()[-1], "black", plot = TRUE)
# APCA algorithm
contrast_ratio(palette(), "white", algorithm = "APCA")
contrast_ratio(palette(), "white", algorithm = "APCA", plot = TRUE, digits = 0)This function returns a matrix with three columns which give the coordinates of a color in its natural color space.
coords(color)color |
A color. |
A numeric matrix giving the coordinates of the color.
Ross Ihaka
RGB, XYZ, LAB,
polarLAB, LUV, polarLUV,
mixcolor.
x <- sRGB(1, 0, 0)
coords(as(x, "HSV"))Conversion tables for simulating different types of color vision deficiency (CVD): Protanomaly, deutanomaly, tritanomaly.
protanomaly_cvd
deutanomaly_cvd
tritanomaly_cvdLists of 3x3 RGB-color transformation matrices for the various types of CVD. Each list contains 11 transformation matrices representing increasingly severe color vision deficiency.
Machado et al. (2009) have established a novel model, that allows to handle normal color
vision, anomalous trichromacy, and dichromacy in a unified way. They also provide conversion
formulas along with tables of certain constants that allow to simulate various types of
CVD. See simulate_cvd for the corresponding simulation functions.
Machado GM, Oliveira MM, Fernandes LAF (2009). A Physiologically-Based Model for Simulation of Color Vision Deficiency. IEEE Transactions on Visualization and Computer Graphics. 15(6), 1291–1298. doi:10.1109/TVCG.2009.113 Online version with supplements at http://www.inf.ufrgs.br/~oliveira/pubs_files/CVD_Simulation/CVD_Simulation.html.
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
A graphical user interface (GUI) to check an existing jpg/png image for (possible) color constraints. The image will be converted to protanope vision, deuteranope vision, and a desaturated version (monochromatic vision). Allows a rapid check whether the colors used in the image show some constraints with respect to color deficiency or color blindness.
cvd_emulator(file, overwrite = FALSE, shiny.trace = FALSE)file |
If not set, an interactive GUI will be started. If |
overwrite |
|
shiny.trace |
|
Reto Stauffer, Claus O. Wilke, Achim Zeileis
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
Used in cvd_emulator. Takes an image object and converts
the colors using deutan, protan,
tritan, desaturate functions. The image
will be written to disc as a PNG file.
cvd_image(img, type, file, severity = 1, linear = TRUE)img |
|
type |
|
file |
|
severity |
numeric. Severity of the color vision defect, a number between 0 and 1. |
linear |
logical. Should the color vision deficiency transformation be applied to the
linearized RGB coordinates (default)? If |
Demonstration of color palettes in various kinds of statistical graphics.
demoplot(
x,
type = c("map", "heatmap", "scatter", "spine", "bar", "pie", "perspective", "mosaic",
"lines"),
...
)x |
character vector containing color hex codes. |
type |
character indicating the type of demonstration plot. |
... |
currently not used. |
To demonstrate how different kinds of color palettes work in different
kinds of statistical displays, demoplot provides a simple convenience
interface to some base graphics with (mostly artificial) data sets.
All types of demos can deal with arbitrarily many colors. However, some
displays are much more suitable for a low number of colors (e.g., the pie
chart) while others work better with more colors (e.g., the heatmap).
demoplot returns invisibly what the respective base graphics
functions return that are called internally.
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
## all built-in demos with the same sequential heat color palette
par(mfrow = c(3, 3))
cl <- sequential_hcl(5, "Heat")
for (i in c("map", "heatmap", "scatter", "spine", "bar", "pie", "perspective", "mosaic", "lines")) {
demoplot(cl, type = i)
}
## qualitative palettes: light pastel colors for shading areas (pie)
## and darker colorful palettes for points or lines
demoplot(qualitative_hcl(4, "Pastel 1"), type = "pie")
demoplot(qualitative_hcl(4, "Set 2"), type = "scatter")
demoplot(qualitative_hcl(4, "Dark 3"), type = "lines")
## sequential palettes: display almost continuous gradients with
## strong luminance contrasts (heatmap, perspective) and colorful
## sequential palette for spine plot with only a few ordered categories
demoplot(sequential_hcl(99, "Purple-Blue"), type = "heatmap")
demoplot(sequential_hcl(99, "Reds"), type = "perspective")
demoplot(sequential_hcl(4, "Viridis"), type = "spine")
## diverging palettes: display almost continuous gradient with
## strong luminance contrast bringing out the extremes (map),
## more colorful palette with lower luminance contrasts for displays
## with fewer colors (mosaic, bar)
demoplot(diverging_hcl(99, "Tropic", power = 2.5), type = "map")
demoplot(diverging_hcl(5, "Green-Orange"), type = "mosaic")
demoplot(diverging_hcl(5, "Blue-Red 2"), type = "bar")
## some palettes that work well on black backgrounds
par(mfrow = c(2, 3), bg = "black")
demoplot(sequential_hcl(9, "Oslo"), "heatmap")
demoplot(sequential_hcl(9, "Turku"), "heatmap")
demoplot(sequential_hcl(9, "Inferno", rev = TRUE), "heatmap")
demoplot(qualitative_hcl(9, "Set 2"), "lines")
demoplot(diverging_hcl(9, "Berlin"), "scatter")
demoplot(diverging_hcl(9, "Cyan-Magenta", l2 = 20), "lines")Transform a vector of given colors to the corresponding colors with chroma reduced (by a tunable amount) in HCL space.
desaturate(col, amount = 1, ...)col |
vector of R colors. Can be any of the three kinds of R colors,
i.e., either a color name (an element of |
amount |
numeric specifying the amount of desaturation where |
... |
additional arguments. If |
If input col is a vector given colors are first transformed to RGB
(either using hex2RGB or
col2rgb) and then to HCL
(polarLUV). In HCL, chroma is reduced
and then the color is transformed back to a hexadecimal
string.
If input col is a matrix with three rows named R, G, and
B (top down) they are interpreted as Red-Green-Blue values within the
range [0-255]. The desaturation takes place in the HCL space as well.
Instead of an (s)RGB color vector a matrix of the same size as the input
col with desaturated Red-Green-Blue values will be returned.
This can be handy to avoid too many conversions.
Similarly, col can be a formal color-class object, in which
case the desaturated colors are returned as a formal object of the same class as the input.
A color object as specified in the input col (hexadecimal string, RGB matrix,
or formal color class) with desaturated colors.
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
## rainbow of colors and their desaturated counterparts
rainbow_hcl(12)
desaturate(rainbow_hcl(12))
## convenience demo function
wheel <- function(col, radius = 1, ...)
pie(rep(1, length(col)), col = col, radius = radius, ...)
## compare base and colorspace palettes
## (in color and desaturated)
par(mar = rep(0, 4), mfrow = c(2, 2))
## rainbow color wheel
wheel(rainbow_hcl(12))
wheel(rainbow(12))
wheel(desaturate(rainbow_hcl(12)))
wheel(desaturate(rainbow(12)))
## apply desaturation directly on wide RGB matrix (with R/G/B channels in rows)
RGB <- diag(3) * 255
rownames(RGB) <- c("R", "G", "B")
desaturate(RGB)Diverging HCL color palettes generated through combination of two fully flexible (and possibly unbalanced) multi-hue sequential palettes.
divergingx_hcl(
n,
palette = "Geyser",
...,
fixup = TRUE,
alpha = 1,
rev = FALSE,
h1,
h2,
h3,
c1,
c2,
c3,
l1,
l2,
l3,
p1,
p2,
p3,
p4,
cmax1,
cmax2
)
divergingx_palettes(palette = NULL, plot = FALSE, n = 7L, ...)n |
the number of colors ( |
palette |
character with the name (see details). |
... |
arguments passed to |
fixup |
logical. Should the color be corrected to a valid RGB value? |
alpha |
numeric vector of values in the range |
rev |
logical. Should the palette be reversed? |
h1 |
numeric. Starting hue coordinate. |
h2 |
numeric. Center hue coordinate. |
h3 |
numeric. Ending hue coordinate. |
c1 |
numeric. Chroma coordinate corresponding to |
c2 |
numeric. Chroma coordinate corresponding to |
c3 |
numeric. Chroma coordinate corresponding to |
l1 |
numeric. Luminance coordinate corresponding to |
l2 |
numeric. Luminance coordinate corresponding to |
l3 |
numeric. Luminance coordinate corresponding to |
p1 |
numeric. Power parameter for chroma coordinates in first sequential palette. |
p2 |
numeric. Power parameter for luminance coordinates in first sequential palette (if |
p3 |
numeric. Power parameter for chroma coordinates in second sequential palette (if |
p4 |
numeric. Power parameter for luminance coordinates in second sequential palette (if |
cmax1 |
numeric. Maximum chroma coordinate in first sequential palette (not used if |
cmax2 |
numeric. Maximum chroma coordinate in second sequential palette (if |
plot |
logical. Should the selected HCL color palettes be visualized? |
The divergingx_hcl function simply calls sequential_hcl
twice with a prespecified set of hue, chroma, and luminance parameters. This is
similar to diverging_hcl but allows for more flexibility:
diverging_hcl employs two single-hue sequential palettes,
always uses zero chroma for the neutral/central color, and restricts the
chroma/luminance path to be the same in both “arms” of the palette.
In contrast, divergingx_hcl relaxes this to two full multi-hue
palettes that can thus go through a non-gray neutral color (typically light
yellow). Consequently, the chroma/luminance paths can be rather unbalanced
between the two arms.
With this additional flexibility various diverging palettes suggested by https://ColorBrewer2.org/ and CARTO (https://carto.com/carto-colors/), can be emulated along with the Zissou 1 palette from wesanderson, Cividis from viridis, and Roma from scico.
Available CARTO palettes: ArmyRose, Earth, Fall, Geyser, TealRose, Temps, and
Tropic (with Tropic also available in diverging_hcl).
Available ColorBrewer.org palettes: PuOr, RdBu, RdGy, PiYG, PRGn, BrBG, RdYlBu, RdYlGn, Spectral.
A character vector with (s)RGB codings of the colors in the palette.
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
## show emulated CARTO/ColorBrewer.org palettes
divergingx_palettes(plot = TRUE)
## compared to diverging_hcl() the diverging CARTO palettes are typically warmer
## but also less balanced with respect to chroma/luminance, see e.g.,
specplot(divergingx_hcl(7, "ArmyRose"))The app visualizes colors either along the hue-chroma plane for a given luminance value or along the luminance-chroma plane for a given hue. Colors can be entered by specifying the hue (H), chroma (C), and luminance (L) values via sliders, by entering an RGB hex code, or by clicking on a color in the hue-chroma or luminance-chroma plane. It is also possible to select individual colors and add them to a palette for comparison and future reference.
hcl_color_picker(shiny.trace = FALSE)
choose_color(shiny.trace = FALSE)shiny.trace |
logical: used for debugging the shiny interface. |
choose_color is a convenience alias for hcl_color_picker to
go along with choose_palette. Another alias is hclcolorpicker.
hclcolorpicker invisibly returns a vector of colors choosen.
If no colors have been selected NULL will be returned.
Claus O. Wilke, Reto Stauffer, Achim Zeileis
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
## Not run:
hcl_color_picker()
## End(Not run)Qualitative, sequential (single-hue and multi-hue), and diverging color palettes based on the HCL (hue-chroma-luminance) color model.
hcl_palettes(type = NULL, palette = NULL, plot = FALSE, n = 5L, ...)
## S3 method for class 'hcl_palettes'
print(x, ...)
## S3 method for class 'hcl_palettes'
summary(object, ...)
## S3 method for class 'hcl_palettes'
plot(x, n = 5L, fixup = TRUE, off = NULL, border = NULL, ...)
qualitative_hcl(
n,
h = c(0, 360 * (n - 1)/n),
c = 80,
l = 60,
fixup = TRUE,
alpha = 1,
palette = NULL,
rev = FALSE,
register = "",
...,
h1,
h2,
c1,
l1
)
sequential_hcl(
n,
h = 260,
c = 80,
l = c(30, 90),
power = 1.5,
gamma = NULL,
fixup = TRUE,
alpha = 1,
palette = NULL,
rev = FALSE,
register = "",
...,
h1,
h2,
c1,
c2,
l1,
l2,
p1,
p2,
cmax,
c.
)
diverging_hcl(
n,
h = c(260, 0),
c = 80,
l = c(30, 90),
power = 1.5,
gamma = NULL,
fixup = TRUE,
alpha = 1,
palette = NULL,
rev = FALSE,
register = "",
...,
h1,
h2,
c1,
l1,
l2,
p1,
p2,
cmax
)type |
character indicating type of HCL palette. |
palette |
character. Name of HCL color palette. |
plot |
logical. Should the selected HCL color palettes be visualized? |
n |
the number of colors ( |
... |
Other arguments passed to |
x, object
|
A |
fixup |
logical. Should the color be corrected to a valid RGB value? |
off |
numeric. Vector of length 2 indicating horizontal and vertical offsets between the color rectangles displayed. |
border |
character. Color of rectangle borders. |
h, h1, h2
|
hue value in the HCL color description, has to be in [0, 360]. |
c, c., c1, c2
|
chroma value in the HCL color description. |
l, l1, l2
|
luminance value in the HCL color description. |
alpha |
numeric vector of values in the range |
rev |
logical. Should the color palette vector be returned in reverse order? |
register |
character. If set to a non-empty character string, the corresponding palette is registered with that name for subsequent use (within the same session). |
power, p1, p2
|
control parameter determining how chroma and luminance should be increased (1 = linear, 2 = quadratic, etc.). |
gamma |
Deprecated. |
cmax |
Maximum chroma value in the HCL color description. |
The HCL (hue-chroma-luminance) color model is a perceptual color model
obtained by using polar coordinates in CIE LUV space
(i.e., polarLUV), where steps of equal size correspond to
approximately equal perceptual changes in color. By taking polar coordinates
the resulting three dimensions capture the three perceptual axes very well:
hue is the type of color, chroma the colorfulness compared
to the corresponding gray, and luminance the brightness. This makes it relatively
easy to create balanced palettes through trajectories in this HCL space.
In contrast, in the more commonly-used HSV (hue-saturation-value)
model (a simple transformation of RGB), the three axes are
confounded so that luminance changes along with the hue leading to very
unbalanced palettes (see rainbow_hcl for further illustrations).
Three types of palettes are derived based on the HCL model:
Qualitative: Designed for coding categorical information, i.e., where no particular ordering of categories is available and every color should receive the same perceptual weight.
Sequential: Designed for coding ordered/numeric information, i.e., where colors go from high to low (or vice versa).
Diverging: Designed for coding numeric information around a central neutral value, i.e., where colors diverge from neutral to two extremes.
The corresponding functions are qualitative_hcl, sequential_hcl,
and diverging_hcl. Their construction principles are explained in more detail below.
At the core is the luminance axis (i.e., light-dark contrasts):
These are easily decoded by humans and matched to high-low differences in the underlying
data. Therefore, sequential_hcl palettes are always based on a monotonic
luminance sequence whereas the colors in a qualitative_hcl palette all have the
same luminance. Finally, diverging_hcl palettes use the same monotonic
luminance sequence in both “arms” of the palette, i.e., correspond to
two balanced sequential palettes diverging from the same neutral value.
The other two axes, hue and chroma, are used to enhance the luminance information and/or
to further discriminate the color.
All three palette functions specify trajectories in HCL space and hence need either
single values or intervals of the coordinates h, c, l. Their
interfaces are always designed such that h, c, l can take vector
arguments (as needed) but alternatively or additionally h1/h2,
c1/c2/cmax, and l1/l2 can be specified. If so,
the latter coordinates overwrite the former.
qualitative_hcl distinguishes the underlying categories by a sequence of
hues while keeping both chroma and luminance constant to give each color in the
resulting palette the same perceptual weight. Thus, h should be a pair of
hues (or equivalently h1 and h2 can be used) with the starting and
ending hue of the palette. Then, an equidistant sequence between these hues is
employed, by default spanning the full color wheel (i.e, the full 360 degrees).
Chroma c (or equivalently c1) and luminance l (or equivalently
l1) are constants.
sequential_hcl codes the underlying numeric values by a monotonic sequence
of increasing (or decreasing) luminance. Thus, the l argument should provide
a vector of length 2 with starting and ending luminance (equivalently, l1 and
l2 can be used). Without chroma (i.e., c = 0), this simply corresponds
to a grayscale palette like gray.colors. For adding chroma, a simple
strategy would be to pick a single hue (via h or h1) and then decrease
chroma from some value (c or c1) to zero (i.e., gray) along with
increasing luminance. For bringing out the extremes (a dark high-chroma color vs.
a light gray) this is already very effective. For distinguishing also colors in the
middle two strategies can be employed: (a) Hue can be varied as well by specifying an
interval of hues in h (or beginning hue h1 and ending hue h2).
(b) Instead of a decreasing chroma a triangular chroma trajectory can be employed
from c1 over cmax to c2 (or equivalently a vector c of
length 3). This yields high-chroma colors in the middle of the palette that are
more easily distinguished from the dark and light extremes. Finally, instead of
employing linear trajectories, power transformations are supported in chroma and
luminance via a vector power (or separate p1 and p2). If
power[2] (or p2) for the luminance trajectory is missing, it defaults
to power[1]/p1 from the chroma trajectory.
diverging_hcl codes the underlying numeric values by a triangular luminance
sequence with different hues in the left and in the right arm of the palette. Thus,
it can be seen as a combination of two sequential palettes with some restrictions:
(a) a single hue is used for each arm of the palette, (b) chroma and luminance trajectory
are balanced between the two arms, (c) the neutral central value has zero chroma.
To specify such a palette a vector of two hues h (or equivalently h1
and h2), either a single chroma value c (or c1) or a vector
of two chroma values c (or c1 and cmax), a vector of two
luminances l (or l1 and l2), and power parameter(s) power
(or p1 and p2) are used. For more flexible diverging palettes without
the restrictrictions above (and consequently more parameters)
divergingx_hcl is available. For backward compatibility, diverge_hcl
is a copy of diverging_hcl.
To facilitate using HCL-based palettes a wide range of example palettes are
provided in the package and can be specified by a name instead of a set of
parameters/coordinates. The examples have been taken from the literature and many
approximate color palettes from other software packages such as ColorBrewer.org
(RColorBrewer), CARTO colors (rcartocolor), scico, or virids. The
function hcl_palettes can be used to query the available pre-specified palettes. It
comes with a print method (listing names and types), a summary method
(additionally listing the underlying parameters/coordinates), and a plot
method that creates a swatchplot with suitable labels.
qualitative_hcl, sequential_hcl, diverging_hcl return
a vector of n color strings (hex codes).
The function hcl_palettes returns a data frame of class "hcl_palettes"
where each row contains information about one of the requested palettes (name, type,
HCL trajectory coordinates). Suitable print, summary, and plot
methods are available.
Zeileis A, Hornik K, Murrell P (2009). Escaping RGBland: Selecting Colors for Statistical Graphics. Computational Statistics & Data Analysis, 53, 3259–3270. doi:10.1016/j.csda.2008.11.033 Preprint available from https://www.zeileis.org/papers/Zeileis+Hornik+Murrell-2009.pdf.
Stauffer R, Mayr GJ, Dabernig M, Zeileis A (2015). Somewhere Over the Rainbow: How to Make Effective Use of Colors in Meteorological Visualizations. Bulletin of the American Meteorological Society, 96(2), 203–216. doi:10.1175/BAMS-D-13-00155.1
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
## overview of all _named_ HCL palettes
hcl_palettes()
## visualize
hcl_palettes("qualitative", plot = TRUE)
hcl_palettes("sequential (single-hue)", n = 7, plot = TRUE)
hcl_palettes("sequential (multi-hue)", n = 7, plot = TRUE)
hcl_palettes("diverging", n = 7, plot = TRUE)
## inspect a specific palette
## (upper-case, spaces, etc. are ignored for matching)
hcl_palettes(palette = "Dark 2")
hcl_palettes(palette = "dark2")
## set up actual colors
qualitative_hcl(4, h = c(0, 288), c = 50, l = 60) ## by hand
qualitative_hcl(4, palette = "dark2") ## by name
qualitative_hcl(4, palette = "dark2", c = 80) ## by name plus modification
## how HCL palettes are constructed:
## by varying the perceptual properties via hue/chroma/luminance
swatchplot(
"Hue" = sequential_hcl(5, h = c(0, 300), c = c(60, 60), l = 65),
"Chroma" = sequential_hcl(5, h = 0, c = c(100, 0), l = 65, rev = TRUE, power = 1),
"Luminance" = sequential_hcl(5, h = 260, c = c(25, 25), l = c(25, 90), rev = TRUE, power = 1),
off = 0
)
## for qualitative palettes luminance and chroma are fixed, varying only hue
hclplot(qualitative_hcl(9, c = 50, l = 70))
## single-hue sequential palette (h = 260) with linear vs. power-transformed trajectory
hclplot(sequential_hcl(7, h = 260, c = 80, l = c(35, 95), power = 1))
hclplot(sequential_hcl(7, h = 260, c = 80, l = c(35, 95), power = 1.5))
## advanced single-hue sequential palette with triangular chroma trajectory
## (piecewise linear vs. power-transformed)
hclplot(sequential_hcl(7, h = 245, c = c(40, 75, 0), l = c(30, 95), power = 1))
hclplot(sequential_hcl(7, h = 245, c = c(40, 75, 0), l = c(30, 95), power = c(0.8, 1.4)))
## multi-hue sequential palette with small hue range and triangular chroma vs.
## large hue range and linear chroma trajectory
hclplot(sequential_hcl(7, h = c(260, 220), c = c(50, 75, 0), l = c(30, 95), power = 1))
hclplot(sequential_hcl(7, h = c(260, 60), c = 60, l = c(40, 95), power = 1))
## balanced diverging palette constructed from two simple single-hue sequential
## palettes (for hues 260/blue and 0/red)
hclplot(diverging_hcl(7, h = c(260, 0), c = 80, l = c(35, 95), power = 1))
## to register a particular adapted palette for re-use in the same session
## with a new name the register=... argument can be used once, e.g.,
diverging_hcl(7, palette = "Tropic", h2 = 0, register = "mytropic")
## subsequently palete="mytropic" is available in diverging_hcl() and the diverging
## ggplot2 scales such as scale_color_continuous_diverging() etc.
demoplot(diverging_hcl(11, "mytropic"), type = "map")
## to register this palette in all R sessions you could place the following
## code in a startup script (e.g., .Rprofile):
## colorspace::diverging_hcl(7, palette = "Tropic", h2 = 0, register = "mytropic")Visualization of color palettes in HCL space projections.
hclplot(
x,
type = NULL,
h = NULL,
c = NULL,
l = NULL,
xlab = NULL,
ylab = NULL,
main = NULL,
cex = 1,
axes = TRUE,
bg = "white",
lwd = 1,
size = 2.5,
...
)x |
character vector containing color hex codes, or a |
type |
type character specifying which type of palette should be visualized
( |
h |
numeric hue(s) to be used for |
c |
numeric. Maximal chroma value to be used. |
l |
numeric luminance(s) to be used for |
xlab, ylab, main
|
character strings for annotation, by default generated from the type of color palette visualized. |
cex |
numeric character extension. |
axes |
logical. Should axes be drawn? |
bg, lwd, size
|
graphical control parameters for the color palette trajectory. |
... |
currently not used. |
The function hclplot is an auxiliary function for illustrating
the trajectories of color palettes in two-dimensional HCL space projections.
It collapses over one of the three coordinates (either the hue H or the
luminance L) and displays a heatmap of colors combining the remaining
two dimensions. The coordinates for the given color palette are highlighted
to bring out its trajectory.
The function hclplot has been designed to work well with the
hcl_palettes in this package. While it is possible to apply
it to other color palettes as well, the results might look weird or confusing
if these palettes are constructed very differently (e.g., as in the highly
saturated base R palettes).
More specifically, the following palettes can be visualized well:
Qualitative with (approximately) constant luminance. In this case,
hclplot shows a hue-chroma plane (in polar coordinates), keeping
luminance at a fixed level (by default displayed in the main title of
the plot). If the luminance is, in fact, not approximately constant,
the luminance varies along with hue and chroma, using a simple linear
function (fitted by least squares).
hclplot shows a chroma-luminance plane, keeping hue at a fixed
level (by default displayed in the main title of the plot). If the hue
is, in fact, not approximately constant, the hue varies along with
chroma and luminance, using a simple linear function (fitted by least
squares.
Diverging with two (approximately) constant hues: This case is visualized with two back-to-back sequential displays.
To infer the type of display to use, by default, the following heuristic is used: If luminance is not approximately constant (range > 10) and follows rougly a triangular pattern, a diverging display is used. If luminance is not constant and follows roughly a linear pattern, a sequential display is used. Otherwise a qualitative display is used.
hclplot invisibly returns a matrix with the HCL coordinates corresponding to x.
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
## for qualitative palettes luminance and chroma are fixed, varying only hue
hclplot(qualitative_hcl(9, c = 50, l = 70))
## single-hue sequential palette (h = 260) with linear vs. power-transformed trajectory
hclplot(sequential_hcl(7, h = 260, c = 80, l = c(35, 95), power = 1))
hclplot(sequential_hcl(7, h = 260, c = 80, l = c(35, 95), power = 1.5))
## advanced single-hue sequential palette with triangular chroma trajectory
## (piecewise linear vs. power-transformed)
hclplot(sequential_hcl(7, h = 245, c = c(40, 75, 0), l = c(30, 95), power = 1))
hclplot(sequential_hcl(7, h = 245, c = c(40, 75, 0), l = c(30, 95), power = c(0.8, 1.4)))
## multi-hue sequential palette with small hue range and triangular chroma vs.
## large hue range and linear chroma trajectory
hclplot(sequential_hcl(7, h = c(260, 220), c = c(50, 75, 0), l = c(30, 95), power = 1))
hclplot(sequential_hcl(7, h = c(260, 60), c = 60, l = c(40, 95), power = 1))
## balanced diverging palette constructed from two simple single-hue sequential
## palettes (for hues 260/blue and 0/red)
hclplot(diverging_hcl(7, h = c(260, 0), c = 80, l = c(35, 95), power = 1))This functions converts color-class objects into hexadecimal strings.
hex(from, gamma = NULL, fixup = FALSE)from |
The color object to be converted. |
gamma |
Deprecated. |
fixup |
Should the color be corrected to a valid RGB value before
correction. The default is to convert out-of-gamut colors to the string
|
The color objects are first converted to sRGB color objects. They are then
multiplied by 255 and rounded to obtain an integer value. These values are
then converted to hexadecimal strings of the form "#RRGGBB" and
suitable for use as color descriptions for R graphics. Out of gamut values
are either corrected to valid RGB values by translating the the individual
primary values so that they lie between 0 and 255.
A vector of character strings.
Ross Ihaka
hex2RGB, RGB, sRGB,
HSV, XYZ, LAB,
polarLAB, LUV, polarLUV.
hsv <- HSV(seq(0, 360, length.out = 7)[-7], 1, 1)
hsv
hex(hsv)
barplot(rep(1,6), col = hex(hsv))This function takes a vector of strings of the form "#RRGGBB"
(hexadecimal color descriptions) into sRGB objects.
hex2RGB(x, gamma = FALSE)x |
a vector of hexadecimal color descriptions. |
gamma |
Whether to apply gamma-correction. |
This function converts device-dependent color descriptions of the form
"#RRGGBB" into sRGB color descriptions (linearized if gamma is
TRUE). The alpha channel will be ignored if given
("#RRGGBBAA").
An sRGB object describing the colors.
Ross Ihaka
hex, RGB, sRGB,
HSV, XYZ, polarLAB,
LUV, polarLUV.
hex2RGB(c("#FF0000","#00FF00", "#0000FF50"))This function creates colors of class HLS; a subclass of the virtual
color-class class.
HLS(H, L, S, names)
H, L, S
|
These arguments give the hue, lightness, and saturation of the
colors. The values can be provided in separate |
names |
A vector of names for the colors (by default the row names of
|
This function creates colors in an HLS color space. The hues should lie between between 0 and 360, and the lightness and saturations should lie between 0 and 1.
HLS is a relative color space; it is a transformation of an RGB color
space. Conversion of HLS colors to any other color space must first
involve a conversion to a specific RGB color space, for example the
standard sRGB color space (IEC standard 61966).
An object of class HLS which inherits from class color.
Ross Ihaka
sRGB, RGB, XYZ, LAB,
polarLAB, LUV, polarLUV.
# A rainbow of full-intensity hues
HLS(seq(0, 360, length.out = 13)[-13], 0.5, 1)This function creates colors of class HSV; a subclass of the virtual
color-class class.
HSV(H, S, V, names)
H, S, V
|
These arguments give the hue, saturation and value of the
colors. The values can be provided in separate |
names |
A vector of names for the colors (by default the row names of
|
This function creates colors in an HSV color space. The hues should lie between between 0 and 360, and the saturations and values should lie between 0 and 1.
HSV is a relative color space; it is a transformation of an RGB color
space. Conversion of HSV colors to any other color space must first
involve a conversion to a specific RGB color space, for example the
standard sRGB color space (IEC standard 61966).
An object of class HSV which inherits from class color.
Ross Ihaka
sRGB, RGB, XYZ, LAB,
polarLAB, LUV, polarLUV.
# A rainbow of full-intensity hues
HSV(seq(0, 360, length.out = 13)[-13], 1, 1)This function creates colors of class “LAB”; a subclass of the virtual
color-class class.
LAB(L, A, B, names)
L, A, B
|
these arguments give the L, A and B coordinates of the colors.
The values can be provided in separate |
names |
a vector of names for the colors (by default the row names of
|
The L, A and B values give the coordinates of the
colors in the CIE space. This is a transformation
of the 1931 CIE XYZ space which attempts to produce perceptually based axes.
Luminance takes values between 0 and 100, and the other coordinates
typically take values between -100 and 100, although these values can also
be exceeded by highly saturated colors. The and coordinates
measure positions on green/red and blue/yellow axes.
An object of class LAB which inherits from class color.
Ross Ihaka
RGB, HSV, XYZ,
LAB, polarLAB, LUV,
polarLUV.
## Show the LAB space
set.seed(1)
x <- sRGB(runif(1000), runif(1000), runif(1000))
y <- as(x, "LAB")
head(x)
head(y)
plot(y)The functions lighten and darken take a vector of R colors and adjust the colors such that
they appear lightened or darkened, respectively.
lighten(
col,
amount = 0.1,
method = c("relative", "absolute"),
space = c("HCL", "HLS", "combined"),
fixup = TRUE
)
darken(col, amount = 0.1, space = "combined", ...)col |
vector of any of the three kind of R colors, i.e., either a color
name (an element of |
amount |
numeric specifying the amount of lightening. This is applied either
multiplicatively or additively to the luminance value, depending on the
setting of |
method |
character string specifying the adjustment method. Can be either |
space |
character string specifying the color space in which adjustment happens. Can be either |
fixup |
logical If set to |
... |
Other parameters handed to the function |
The color adjustment can be calculated in three different color spaces.
If space = "HCL", the colors are transformed to HCL, (polarLUV),
the luminance component L is adjusted, and then the colors are transformed back to a hexadecimal
RGB string.
If space = "HLS", the colors are transformed to HLS, the lightness component L is adjusted,
and then the color is transformed back to a hexadecimal RGB string.
If space = "combined", the colors are first adjusted in both the HCL and HLS spaces. Then,
the adjusted HLS colors are converted into HCL, and then the chroma components of the adjusted HLS
colors are copied to the adjusted HCL colors. Thus, in effect, the combined model adjusts luminance
in HCL space but chroma in HLS space.
We have found that typically space = "HCL" performs best for lightening colors and space = "combined"
performs best for darkening colors, and these are the default settings for lighten and darken,
respectively.
Regardless of the chosen color space, the adjustment of the L component can occur by two methods, relative
(the default) and absolute. Under the absolute method, the adjustment is L +/- 100 * amount when
lightening/darkening colors. Under the relative method, the adjustment is 100 - (100 - L) * (1 - amount) when
lightening colors and L * (1 - amount) when darkening colors.
Programmatically lightening and darkening colors can yield unexpected results (see examples). In HCL space,
colors can become either too gray or overly colorful. By contrast, in HLS space it can happen that the
overall amount of lightening or darkening appears to be non-uniform among a group of colors that are
lightened or darkened jointly, and again, colors can become either too gray or overly colorful. We
recommend to try different color spaces if the default space for the chosen function (lighten
or darken) does not look right in a specific application.
A character vector with (s)RGB codings of the colors in the palette.
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
# lighten dark colors, example 1
cl <- qualitative_hcl(5)
swatchplot(list(
HCL = rbind("0%" = cl,
"15%" = lighten(cl, 0.15),
"30%" = lighten(cl, 0.3)),
HLS = rbind("0%" = cl,
"15%" = lighten(cl, 0.15, space = "HLS"),
"30%" = lighten(cl, 0.3, space = "HLS")),
combined = rbind("0%" = cl,
"15%" = lighten(cl, 0.15, space = "combined"),
"30%" = lighten(cl, 0.3, space = "combined"))),
nrow = 4, line = 2.5
)
# lighten dark colors, example 2
cl <- c("#61A9D9", "#ADD668", "#E6D152", "#CE6BAF", "#797CBA")
swatchplot(list(
HCL = rbind("0%" = cl,
"15%" = lighten(cl, 0.15),
"30%" = lighten(cl, 0.3)),
HLS = rbind("0%" = cl,
"15%" = lighten(cl, 0.15, space = "HLS"),
"30%" = lighten(cl, 0.3, space = "HLS")),
combined = rbind("0%" = cl,
"15%" = lighten(cl, 0.15, space = "combined"),
"30%" = lighten(cl, 0.3, space = "combined"))),
nrow = 4, line = 2.5
)
# darken light colors, example 1
cl <- qualitative_hcl(5, "Pastel 1")
swatchplot(list(
combined = rbind("0%" = cl,
"15%" = darken(cl, 0.15),
"30%" = darken(cl, 0.3)),
HCL = rbind("0%" = cl,
"15%" = darken(cl, 0.15, space = "HCL"),
"30%" = darken(cl, 0.3, space = "HCL")),
HLS = rbind("0%" = cl,
"15%" = darken(cl, 0.15, space = "HLS"),
"30%" = darken(cl, 0.3, space = "HLS"))),
nrow = 4, line = 2.5
)
# darken light colors, example 2
cl <- c("#CDE4F3","#E7F3D3","#F7F0C7","#EFCFE5","#D0D1E7")
swatchplot(list(
combined = rbind("0%" = cl,
"15%" = darken(cl, 0.15),
"30%" = darken(cl, 0.3)),
HCL = rbind("0%" = cl,
"15%" = darken(cl, 0.15, space = "HCL"),
"30%" = darken(cl, 0.3, space = "HCL")),
HLS = rbind("0%" = cl,
"15%" = darken(cl, 0.15, space = "HLS"),
"30%" = darken(cl, 0.3, space = "HLS"))),
nrow = 4, line = 2.5
)This function creates colors of class “LUV”; a subclass of the virtual
color-class class.
LUV(L, U, V, names)
L, U, V
|
these arguments give the L, U and V coordinates of the colors.
The values can be provided in separate |
names |
a vector of names for the colors (by default the row names of
|
The L, U and V values give the coordinates of the
colors in the CIE (1976) space. This is a
transformation of the 1931 CIE XYZ space which attempts to produce
perceptually based axes. Luminance takes values between 0 and 100, and the other coordinates
typically take values between -100 and 100, although these values can also
be exceeded by highly saturated colors. The and
coordinates measure positions on green/red and blue/yellow axes.
An object of class LUV which inherits from class color.
Ross Ihaka
RGB, HSV, XYZ,
LAB, polarLAB, polarLUV.
## Show the LUV space
set.seed(1)
x <- sRGB(runif(1000), runif(1000), runif(1000))
y <- as(x, "LUV")
head(x)
head(y)
plot(y)Compute approximately the maximum chroma possible for a given hue and luminance combination in the HCL color space.
max_chroma(h, l, floor = FALSE)
max_chroma_tableh |
hue value in the HCL color description, has to be in [0, 360]. |
l |
luminance value in the HCL color description, has to be in [0, 100]. |
floor |
logical. Should the chroma value be rounded down to the next lower integer? |
As the possible combinations of chroma and luminance depend on hue, it is
not obvious which maximum chroma can be used for a given combination of hue
and luminance prior to calling polarLUV. To avoid having to
fixup the color upon conversion to RGB hex codes, the
max_chroma function computes (approximately) the maximum chroma
possible. The computations are based on interpolations of pre-computed
maxima in max_chroma_table, containing the maximum chroma for a given
hue-luminance combination (both in integers). Hence, the result may sometimes
still be very slightly larger than the actual maximum which can be avoided
by taking the floor of the approximate value.
A numeric vector with the maximum chroma coordinates.
max_chroma(h = 0:36 * 10, l = 50)
max_chroma(h = 120, l = 0:10 * 10)This function can be used to compute the result of color mixing, assuming additive mixing (e.g., as appropriate for RGB or XYZ).
mixcolor(alpha, color1, color2, where = class(color1))alpha |
The mixed color is obtained by combining an amount
|
color1 |
The first color. |
color2 |
The second color. |
where |
The color space where the mixing is to take place. |
The mixed color. This is in the color space specified by
where.
Ross Ihaka
RGB, HSV, XYZ,
LAB, polarLAB, LUV,
polarLUV.
mixcolor(0.5, sRGB(1, 0, 0), sRGB(0, 1, 0))This function creates colors of class “polarLAB”; a subclass of the
virtual color-class class.
polarLAB(L, C, H, names)
L, C, H
|
these arguments give the L, C and H coordinates of the colors.
The values can be provided in separate |
names |
A vector of names for the colors (by default the row names of
|
The polarLAB space is a transformation of the CIE
space so that the and values are converted to polar
coordinates. The radial component measures chroma and the angular
coordinate is measures hue.
An object of class polarLAB which inherits from class color.
Ross Ihaka
RGB, HSV, XYZ,
LAB, polarLAB, LUV,
polarLUV.
## Show the polarLAB space
set.seed(1)
x <- sRGB(runif(1000), runif(1000), runif(1000))
y <- as(x, "polarLAB")
head(x)
head(y)
plot(y)This function creates colors of class “polarLUV”; a subclass of the
virtual color-class class.
polarLUV(L, C, H, names)
L, C, H
|
these arguments give the L, C and H coordinates of the colors.
The values can be provided in separate |
names |
A vector of names for the colors (by default the row names of
|
The polarLUV space is a transformation of the CIE
space so that the and values are converted to polar
coordinates. The radial component measures chroma and the angular
coordinate is measures hue. It is also known as the HCL
(hue-chroma-luminance) space.
An object of class polarLUV which inherits from class color.
Ross Ihaka
RGB, HSV, XYZ,
LAB, polarLAB, LUV,
polarLUV.
## Show the polarLUV space
set.seed(1)
x <- sRGB(runif(1000), runif(1000), runif(1000))
y <- as(x, "polarLUV")
head(x)
head(y)
plot(y)Color palettes based on the HCL (and HSV) color space to replace base R palettes.
rainbow_hcl(
n,
c = 50,
l = 70,
start = 0,
end = 360 * (n - 1)/n,
gamma = NULL,
fixup = TRUE,
alpha = 1,
...
)
heat_hcl(
n,
h = c(0, 90),
c. = c(100, 30),
l = c(50, 90),
power = c(1/5, 1),
gamma = NULL,
fixup = TRUE,
alpha = 1,
...
)
terrain_hcl(
n,
h = c(130, 0),
c. = c(80, 0),
l = c(60, 95),
power = c(1/10, 1),
gamma = NULL,
fixup = TRUE,
alpha = 1,
...
)
diverging_hsv(
n,
h = c(240, 0),
s = 1,
v = 1,
power = 1,
gamma = NULL,
fixup = TRUE,
alpha = 1,
...
)n |
the number of colors ( |
c, c.
|
chroma value in the HCL color description. |
l |
luminance value in the HCL color description. |
start |
the hue at which the rainbow begins. |
end |
the hue at which the rainbow ends. |
gamma |
Deprecated. |
fixup |
logical. Should the color be corrected to a valid RGB value before correction? |
alpha |
numeric vector of values in the range |
... |
Other arguments passed to |
h |
hue value in the HCL or HSV color description, has to be in [0, 360] for HCL and in [0, 1] for HSV colors. |
power |
control parameter determining how chroma and luminance should be increased (1 = linear, 2 = quadratic, etc.). |
s |
saturation value in the HSV color description. |
v |
value value in the HSV color description. |
Based on the general qualitative, sequential, and diverging hcl_palettes
within the colorspace package, convenience functions are provided as
alternatives to standard base R palettes (which are highly saturated
and too flashy).
rainbow_hcl computes a rainbow of colors via qualitative_hcl
defined by different hues given a single value of each chroma and luminance.
It corresponds to rainbow which computes a rainbow in HSV
space.
heat_hcl is an implementation of heat.colors in
HCL space based on a call to sequential_hcl. Similarly,
terrain_hcl palette also calls sequential_hcl with different
parameters, providing colors similar in spirit to terrain.colors
in HCL space.
diverging_hsv (and equivalently its alias diverge_hsv)
provides an HSV-based version of diverging_hcl. Its purpose
is mainly didactic to show that HSV-based diverging palettes are less
appealing, more difficult to read and more flashy than HCL-based diverging
palettes. diverging_hsv is similar to cm.colors.
A character vector with (s)RGB codings of the colors in the palette.
Zeileis A, Hornik K, Murrell P (2009). Escaping RGBland: Selecting Colors for Statistical Graphics. Computational Statistics & Data Analysis, 53, 3259–3270. doi:10.1016/j.csda.2008.11.033 Preprint available from https://www.zeileis.org/papers/Zeileis+Hornik+Murrell-2009.pdf.
Stauffer R, Mayr GJ, Dabernig M, Zeileis A (2015). Somewhere over the Rainbow: How to Make Effective Use of Colors in Meteorological Visualizations. Bulletin of the American Meteorological Society, 96(2), 203–216. doi:10.1175/BAMS-D-13-00155.1
## convenience demo function
wheel <- function(col, radius = 1, ...)
pie(rep(1, length(col)), col = col, radius = radius, ...)
## compare base and colorspace palettes
## (in color and desaturated)
par(mar = rep(0, 4), mfrow = c(2, 2))
## rainbow color wheel
wheel(rainbow_hcl(12))
wheel(rainbow(12))
wheel(desaturate(rainbow_hcl(12)))
wheel(desaturate(rainbow(12)))
## diverging red-blue colors
swatchplot(
diverging_hsv(7),
desaturate(diverging_hsv(7)),
diverging_hcl(7, c = 100, l = c(50, 90)),
desaturate(diverging_hcl(7, c = 100, l = c(50, 90))),
nrow = 2
)
## diverging cyan-magenta colors
swatchplot(
cm.colors(7),
desaturate(cm.colors(7)),
diverging_hcl(7, "Cyan-Magenta"), ## or, similarly: Tropic
desaturate(diverging_hcl(7, "Cyan-Magenta")),
nrow = 2
)
## heat colors
swatchplot(
heat.colors(12),
desaturate(heat.colors(12)),
heat_hcl(12),
desaturate(heat_hcl(12)),
nrow = 2
)
## terrain colors
swatchplot(
terrain.colors(12),
desaturate(terrain.colors(12)),
terrain_hcl(12),
desaturate(terrain_hcl(12)),
nrow = 2
)This function reads a set of hexadecimal color descriptions from a file and creates a color object containing the corresponding colors.
readhex(file = "", class = "RGB")file |
The file containing the color descriptions. |
class |
The kind of color object to be returned. |
The file is assumed to contain hexadecimal color descriptions of the form
#RRGGBB.
An color object of the specified class containing the color descriptions.
Ross Ihaka
writehex, readRGB,
hex2RGB, RGB, HSV,
XYZ, LAB, polarLAB,
LUV, polarLUV,
## Not run:
rgb <- readhex("pastel.txt")
hsv <- readhex("pastel.txt", "HSV")
## End(Not run)This function reads a set of RGB color descriptions (of the form written by
gcolorsel) from a file and creates a color object containing the
corresponding colors.
readRGB(file, class = "RGB")file |
The file containing the color descriptions. |
class |
The kind of color object to be returned. |
The file is assumed to contain RGB color descriptions consisting of three integer values in the range from 0 to 255 followed by a color name.
An color object of the specified class containing the color descriptions.
Ross Ihaka
writehex, readhex,
hex2RGB, RGB, HSV,
XYZ, LAB, polarLAB,
LUV, polarLUV.
## Not run:
rgb <- readRGB("pastel.rgb")
hsv <- readRGB("pastel.rgb", "HSV")
## End(Not run)This function creates colors of class RGB; a subclass of the virtual
color-class class.
RGB(R, G, B, names)
R, G, B
|
these arguments give the red, green and blue intensities of the
colors (the values should lie between 0 and 1). The values can be provided
in separate |
names |
A vector of names for the colors (by default the row names of
|
This function creates colors in the linearized sRGB color space (IEC standard 61966).
An object of class RGB which inherits from class color.
Ross Ihaka
sRGB, HSV, XYZ,
LAB, polarLAB, LUV,
polarLUV.
# Create a random set of colors
set.seed(1)
RGB(R = runif(20), G = runif(20), B = runif(20))Binned ggplot2 color scales using the color palettes generated by diverging_hcl.
scale_colour_binned_diverging(
palette = NULL,
c1 = NULL,
cmax = NULL,
l1 = NULL,
l2 = NULL,
h1 = NULL,
h2 = NULL,
p1 = NULL,
p2 = NULL,
alpha = 1,
rev = FALSE,
mid = 0,
na.value = "grey50",
guide = "coloursteps",
n_interp = 11,
aesthetics = "colour",
...
)
scale_color_binned_diverging(
palette = NULL,
c1 = NULL,
cmax = NULL,
l1 = NULL,
l2 = NULL,
h1 = NULL,
h2 = NULL,
p1 = NULL,
p2 = NULL,
alpha = 1,
rev = FALSE,
mid = 0,
na.value = "grey50",
guide = "coloursteps",
n_interp = 11,
aesthetics = "colour",
...
)
scale_fill_binned_diverging(..., aesthetics = "fill")palette |
The name of the palette to be used. Run |
c1 |
Chroma value at the scale endpoints. |
cmax |
Maximum chroma value. |
l1 |
Luminance value at the scale endpoints. |
l2 |
Luminance value at the scale midpoint. |
h1 |
Hue value at the first endpoint. |
h2 |
Hue value at the second endpoint. |
p1 |
Control parameter determining how chroma should vary (1 = linear, 2 = quadratic, etc.). |
p2 |
Control parameter determining how luminance should vary (1 = linear, 2 = quadratic, etc.). |
alpha |
Numeric vector of values in the range |
rev |
If |
mid |
Data value that should be mapped to the mid-point of the diverging color scale. |
na.value |
Color to be used for missing data points. |
guide |
Type of legend. Use |
n_interp |
Number of discrete colors that should be used to interpolate the binned color scale. It is important to use an odd number to capture the color at the midpoint. |
aesthetics |
The ggplot2 aesthetics to which this scale should be applied. |
... |
common continuous scale parameters: 'name', 'breaks', 'labels', and 'limits'. See
|
If both a valid palette name and palette parameters are provided then the provided palette parameters overwrite the parameters in the named palette. This enables easy customization of named palettes.
# adapted from stackoverflow: https://stackoverflow.com/a/20127706/4975218
library("ggplot2")
# generate dataset and base plot
set.seed(100)
df <- data.frame(country = LETTERS, V = runif(26, -40, 40))
df$country = factor(LETTERS, LETTERS[order(df$V)]) # reorder factors
gg <- ggplot(df, aes(x = country, y = V, fill = V)) +
geom_bar(stat = "identity") +
labs(y = "Under/over valuation in %", x = "Country") +
coord_flip() + theme_minimal()
# plot with default diverging scale
gg + scale_fill_binned_diverging(n.breaks = 6)
# plot with alternative scale
gg + scale_fill_binned_diverging(palette = "Purple-Green", n.breaks = 6)Binned ggplot2 color scales using the color palettes generated by divergingx_hcl.
scale_colour_binned_divergingx(
palette = "Geyser",
c1 = NULL,
c2 = NULL,
c3 = NULL,
l1 = NULL,
l2 = NULL,
l3 = NULL,
h1 = NULL,
h2 = NULL,
h3 = NULL,
p1 = NULL,
p2 = NULL,
p3 = NULL,
p4 = NULL,
cmax1 = NULL,
cmax2 = NULL,
alpha = 1,
rev = FALSE,
mid = 0,
na.value = "grey50",
guide = "coloursteps",
n_interp = 11,
aesthetics = "colour",
...
)
scale_color_binned_divergingx(
palette = "Geyser",
c1 = NULL,
c2 = NULL,
c3 = NULL,
l1 = NULL,
l2 = NULL,
l3 = NULL,
h1 = NULL,
h2 = NULL,
h3 = NULL,
p1 = NULL,
p2 = NULL,
p3 = NULL,
p4 = NULL,
cmax1 = NULL,
cmax2 = NULL,
alpha = 1,
rev = FALSE,
mid = 0,
na.value = "grey50",
guide = "coloursteps",
n_interp = 11,
aesthetics = "colour",
...
)
scale_fill_binned_divergingx(..., aesthetics = "fill")palette |
The name of the palette to be used. |
h1, h2, h3, c1, c2, c3, l1, l2, l3, p1, p2, p3, p4, cmax1, cmax2
|
Parameters to customize the scale. See |
alpha |
Numeric vector of values in the range |
rev |
If |
mid |
Data value that should be mapped to the mid-point of the diverging color scale. |
na.value |
Color to be used for missing data points. |
guide |
Type of legend. Use |
n_interp |
Number of discrete colors that should be used to interpolate the binned color scale. For diverging scales, it is important to use an odd number to capture the color at the midpoint. |
aesthetics |
The ggplot2 aesthetics to which this scale should be applied. |
... |
common binned scale parameters: 'name', 'breaks', 'labels', and 'limits'. See
|
Available CARTO palettes: ArmyRose, Earth, Fall, Geyser, TealRose, Temps, Tropic.
Available ColorBrewer.org palettes: Spectral, PuOr, RdYlGn, RdYlBu, RdGy, BrBG, PiYG, PRGn, RdBu.
If both a valid palette name and palette parameters are provided then the provided palette parameters overwrite the parameters in the named palette. This enables easy customization of named palettes.
library("ggplot2")
# volcano plot (difference from mean height)
nx = 87
ny = 61
df <- data.frame(diff = c(volcano) - mean(volcano), x = rep(1:nx, ny), y = rep(1:ny, each = nx))
ggplot(df, aes(x, y, fill=diff)) +
geom_raster() + scale_fill_binned_divergingx(palette = "Fall", rev = TRUE) +
coord_fixed(expand = FALSE)
# adapted from stackoverflow: https://stackoverflow.com/a/20127706/4975218
# generate dataset and base plot
set.seed(100)
df <- data.frame(country = LETTERS, V = runif(26, -40, 40))
df$country = factor(LETTERS, LETTERS[order(df$V)]) # reorder factors
gg <- ggplot(df, aes(x = country, y = V, fill = V)) +
geom_bar(stat = "identity") +
labs(y = "Under/over valuation in %", x = "Country") +
coord_flip() + theme_minimal()
# plot with diverging scale "Geyser"
gg + scale_fill_binned_divergingx(palette = "Geyser", n.breaks = 6)Binned ggplot2 color scales using the color palettes generated by qualitative_hcl. These scales are provided
for completeness. It is not normally a good idea to color a continuous, binned variable using a qualitative scale.
scale_colour_binned_qualitative(
palette = NULL,
c1 = NULL,
l1 = NULL,
h1 = NULL,
h2 = NULL,
alpha = 1,
rev = FALSE,
begin = 0,
end = 1,
na.value = "grey50",
guide = "coloursteps",
aesthetics = "colour",
n_interp = 11,
...
)
scale_color_binned_qualitative(
palette = NULL,
c1 = NULL,
l1 = NULL,
h1 = NULL,
h2 = NULL,
alpha = 1,
rev = FALSE,
begin = 0,
end = 1,
na.value = "grey50",
guide = "coloursteps",
aesthetics = "colour",
n_interp = 11,
...
)
scale_fill_binned_qualitative(..., aesthetics = "fill")palette |
The name of the palette to be used. Run |
c1 |
Chroma value, used for all colors in the scale. |
l1 |
Luminance value, used for all colors in the scale. |
h1 |
Beginning hue value. |
h2 |
Ending hue value. |
alpha |
Numeric vector of values in the range |
rev |
If |
begin |
Number in the range of |
end |
Number in the range of |
na.value |
Color to be used for missing data points. |
guide |
Type of legend. Use |
aesthetics |
The ggplot2 aesthetics to which this scale should be applied. |
n_interp |
Number of discrete colors that should be used to interpolate the binned color scale. 11 will work fine in most cases. |
... |
common binned scale parameters: 'name', 'breaks', 'labels', and 'limits'. See
|
If both a valid palette name and palette parameters are provided then the provided palette parameters overwrite the parameters in the named palette. This enables easy customization of named palettes.
library("ggplot2")
# none of these examples are necessarily good ideas
gg <- ggplot(iris, aes(x = Species, y = Sepal.Width, color = Sepal.Length)) +
geom_jitter(width = 0.3) + theme_minimal()
gg + scale_color_binned_qualitative(palette = "Dynamic")
gg + scale_color_binned_qualitative(palette = "Dark3", l1 = 70)
nx = 87
ny = 61
df <- data.frame(height = c(volcano), x = rep(1:nx, ny), y = rep(1:ny, each = nx))
ggplot(df, aes(x, y, fill=height)) +
geom_raster() + scale_fill_binned_qualitative(palette = "Dark 3") +
coord_fixed(expand = FALSE)Binned ggplot2 color scales using the color palettes generated by sequential_hcl.
scale_colour_binned_sequential(
palette = NULL,
c1 = NULL,
c2 = NULL,
cmax = NULL,
l1 = NULL,
l2 = NULL,
h1 = NULL,
h2 = NULL,
p1 = NULL,
p2 = NULL,
alpha = 1,
rev = TRUE,
begin = 0,
end = 1,
na.value = "grey50",
guide = "coloursteps",
aesthetics = "colour",
n_interp = 11,
...
)
scale_color_binned_sequential(
palette = NULL,
c1 = NULL,
c2 = NULL,
cmax = NULL,
l1 = NULL,
l2 = NULL,
h1 = NULL,
h2 = NULL,
p1 = NULL,
p2 = NULL,
alpha = 1,
rev = TRUE,
begin = 0,
end = 1,
na.value = "grey50",
guide = "coloursteps",
aesthetics = "colour",
n_interp = 11,
...
)
scale_fill_binned_sequential(..., aesthetics = "fill")palette |
The name of the palette to be used. Run |
c1 |
Beginning chroma value. |
c2 |
Ending chroma value. |
cmax |
Maximum chroma value. |
l1 |
Beginning luminance value. |
l2 |
Ending luminance value. |
h1 |
Beginning hue value. |
h2 |
Ending hue value. If set to |
p1 |
Control parameter determining how chroma should vary (1 = linear, 2 = quadratic, etc.). |
p2 |
Control parameter determining how luminance should vary (1 = linear, 2 = quadratic, etc.). |
alpha |
Numeric vector of values in the range |
rev |
If |
begin |
Number in the range of |
end |
Number in the range of |
na.value |
Color to be used for missing data points. |
guide |
Type of legend. Use |
aesthetics |
The ggplot2 aesthetics to which this scale should be applied. |
n_interp |
Number of discrete colors that should be used to interpolate the binned color scale. 11 will work fine in most cases. |
... |
common binned scale parameters: 'name', 'breaks', 'labels', and 'limits'. See
|
If both a valid palette name and palette parameters are provided then the provided palette parameters overwrite the parameters in the named palette. This enables easy customization of named palettes.
Compared to sequential_hcl the ordering of the colors in the sequential ggplot2 scale
are reversed by default (i.e., rev = TRUE) to be more consistent with ggplot2's own scales such as
scale_color_fermenter. For most named palettes this leads to darker and more
colorful colors for larger values on the scale. This is typically the better default on light/white
backgrounds.
library("ggplot2")
# volcano plot
df <- data.frame(height = c(volcano), x = c(row(volcano)), y = c(col(volcano)))
ggplot(df, aes(x, y, fill = height)) +
geom_raster() + scale_fill_binned_sequential(palette = "Terrain", rev = FALSE) +
coord_fixed(expand = FALSE)Continuous ggplot2 color scales using the color palettes generated by diverging_hcl.
scale_colour_continuous_diverging(
palette = NULL,
c1 = NULL,
cmax = NULL,
l1 = NULL,
l2 = NULL,
h1 = NULL,
h2 = NULL,
p1 = NULL,
p2 = NULL,
alpha = 1,
rev = FALSE,
mid = 0,
na.value = "grey50",
guide = "colourbar",
n_interp = 11,
aesthetics = "colour",
...
)
scale_color_continuous_diverging(
palette = NULL,
c1 = NULL,
cmax = NULL,
l1 = NULL,
l2 = NULL,
h1 = NULL,
h2 = NULL,
p1 = NULL,
p2 = NULL,
alpha = 1,
rev = FALSE,
mid = 0,
na.value = "grey50",
guide = "colourbar",
n_interp = 11,
aesthetics = "colour",
...
)
scale_fill_continuous_diverging(..., aesthetics = "fill")palette |
The name of the palette to be used. Run |
c1 |
Chroma value at the scale endpoints. |
cmax |
Maximum chroma value. |
l1 |
Luminance value at the scale endpoints. |
l2 |
Luminance value at the scale midpoint. |
h1 |
Hue value at the first endpoint. |
h2 |
Hue value at the second endpoint. |
p1 |
Control parameter determining how chroma should vary (1 = linear, 2 = quadratic, etc.). |
p2 |
Control parameter determining how luminance should vary (1 = linear, 2 = quadratic, etc.). |
alpha |
Numeric vector of values in the range |
rev |
If |
mid |
Data value that should be mapped to the mid-point of the diverging color scale. |
na.value |
Color to be used for missing data points. |
guide |
Type of legend. Use |
n_interp |
Number of discrete colors that should be used to interpolate the continuous color scale. It is important to use an odd number to capture the color at the midpoint. |
aesthetics |
The ggplot2 aesthetics to which this scale should be applied. |
... |
common continuous scale parameters: 'name', 'breaks', 'labels', and 'limits'. See
|
If both a valid palette name and palette parameters are provided then the provided palette parameters overwrite the parameters in the named palette. This enables easy customization of named palettes.
# adapted from stackoverflow: https://stackoverflow.com/a/20127706/4975218
library("ggplot2")
# generate dataset and base plot
set.seed(100)
df <- data.frame(country = LETTERS, V = runif(26, -40, 40))
df$country = factor(LETTERS, LETTERS[order(df$V)]) # reorder factors
gg <- ggplot(df, aes(x = country, y = V, fill = V)) +
geom_bar(stat = "identity") +
labs(y = "Under/over valuation in %", x = "Country") +
coord_flip() + theme_minimal()
# plot with default diverging scale
gg + scale_fill_continuous_diverging()
# plot with alternative scale
gg + scale_fill_continuous_diverging(palette = "Purple-Green")
# plot with modified alternative scale
gg + scale_fill_continuous_diverging(palette = "Blue-Red 3", l1 = 30, l2 = 100, p1 = .9, p2 = 1.2)Continuous ggplot2 color scales using the color palettes generated by divergingx_hcl.
scale_colour_continuous_divergingx(
palette = "Geyser",
c1 = NULL,
c2 = NULL,
c3 = NULL,
l1 = NULL,
l2 = NULL,
l3 = NULL,
h1 = NULL,
h2 = NULL,
h3 = NULL,
p1 = NULL,
p2 = NULL,
p3 = NULL,
p4 = NULL,
cmax1 = NULL,
cmax2 = NULL,
alpha = 1,
rev = FALSE,
mid = 0,
na.value = "grey50",
guide = "colourbar",
n_interp = 11,
aesthetics = "colour",
...
)
scale_color_continuous_divergingx(
palette = "Geyser",
c1 = NULL,
c2 = NULL,
c3 = NULL,
l1 = NULL,
l2 = NULL,
l3 = NULL,
h1 = NULL,
h2 = NULL,
h3 = NULL,
p1 = NULL,
p2 = NULL,
p3 = NULL,
p4 = NULL,
cmax1 = NULL,
cmax2 = NULL,
alpha = 1,
rev = FALSE,
mid = 0,
na.value = "grey50",
guide = "colourbar",
n_interp = 11,
aesthetics = "colour",
...
)
scale_fill_continuous_divergingx(..., aesthetics = "fill")palette |
The name of the palette to be used. |
h1, h2, h3, c1, c2, c3, l1, l2, l3, p1, p2, p3, p4, cmax1, cmax2
|
Parameters to customize the scale. See |
alpha |
Numeric vector of values in the range |
rev |
If |
mid |
Data value that should be mapped to the mid-point of the diverging color scale. |
na.value |
Color to be used for missing data points. |
guide |
Type of legend. Use |
n_interp |
Number of discrete colors that should be used to interpolate the continuous color scale. For diverging scales, it is important to use an odd number to capture the color at the midpoint. |
aesthetics |
The ggplot2 aesthetics to which this scale should be applied. |
... |
common continuous scale parameters: 'name', 'breaks', 'labels', and 'limits'. See
|
Available CARTO palettes: ArmyRose, Earth, Fall, Geyser, TealRose, Temps, Tropic.
Available ColorBrewer.org palettes: Spectral, PuOr, RdYlGn, RdYlBu, RdGy, BrBG, PiYG, PRGn, RdBu.
If both a valid palette name and palette parameters are provided then the provided palette parameters overwrite the parameters in the named palette. This enables easy customization of named palettes.
library("ggplot2")
# volcano plot (difference from mean height)
nx = 87
ny = 61
df <- data.frame(diff = c(volcano) - mean(volcano), x = rep(1:nx, ny), y = rep(1:ny, each = nx))
ggplot(df, aes(x, y, fill=diff)) +
geom_raster() + scale_fill_continuous_divergingx(palette = "Fall", rev = TRUE) +
coord_fixed(expand = FALSE)
# adapted from stackoverflow: https://stackoverflow.com/a/20127706/4975218
# generate dataset and base plot
set.seed(100)
df <- data.frame(country = LETTERS, V = runif(26, -40, 40))
df$country = factor(LETTERS, LETTERS[order(df$V)]) # reorder factors
gg <- ggplot(df, aes(x = country, y = V, fill = V)) +
geom_bar(stat = "identity") +
labs(y = "Under/over valuation in %", x = "Country") +
coord_flip() + theme_minimal()
# plot with diverging scale "Geyser"
gg + scale_fill_continuous_divergingx(palette = "Geyser")
# plot with diverging scale "ArmyRose"
gg + scale_fill_continuous_divergingx(palette = "ArmyRose")Continuous ggplot2 color scales using the color palettes generated by qualitative_hcl. These scales are provided
for completeness. It is not normally a good idea to color a continuous variable using a qualitative scale.
scale_colour_continuous_qualitative(
palette = NULL,
c1 = NULL,
l1 = NULL,
h1 = NULL,
h2 = NULL,
alpha = 1,
rev = FALSE,
begin = 0,
end = 1,
na.value = "grey50",
guide = "colourbar",
aesthetics = "colour",
n_interp = 11,
...
)
scale_color_continuous_qualitative(
palette = NULL,
c1 = NULL,
l1 = NULL,
h1 = NULL,
h2 = NULL,
alpha = 1,
rev = FALSE,
begin = 0,
end = 1,
na.value = "grey50",
guide = "colourbar",
aesthetics = "colour",
n_interp = 11,
...
)
scale_fill_continuous_qualitative(..., aesthetics = "fill")palette |
The name of the palette to be used. Run |
c1 |
Chroma value, used for all colors in the scale. |
l1 |
Luminance value, used for all colors in the scale. |
h1 |
Beginning hue value. |
h2 |
Ending hue value. |
alpha |
Numeric vector of values in the range |
rev |
If |
begin |
Number in the range of |
end |
Number in the range of |
na.value |
Color to be used for missing data points. |
guide |
Type of legend. Use |
aesthetics |
The ggplot2 aesthetics to which this scale should be applied. |
n_interp |
Number of discrete colors that should be used to interpolate the continuous color scale. 11 will work fine in most cases. |
... |
common continuous scale parameters: 'name', 'breaks', 'labels', and 'limits'. See
|
If both a valid palette name and palette parameters are provided then the provided palette parameters overwrite the parameters in the named palette. This enables easy customization of named palettes.
library("ggplot2")
# none of these examples are necessarily good ideas
gg <- ggplot(iris, aes(x = Species, y = Sepal.Width, color = Sepal.Length)) +
geom_jitter(width = 0.3) + theme_minimal()
gg + scale_color_continuous_qualitative(palette = "Warm")
gg + scale_color_continuous_qualitative(palette = "Cold", l1 = 60)
gg + scale_color_continuous_qualitative(palette = "Harmonic", rev = TRUE)
nx = 87
ny = 61
df <- data.frame(height = c(volcano), x = rep(1:nx, ny), y = rep(1:ny, each = nx))
ggplot(df, aes(x, y, fill=height)) +
geom_raster() + scale_fill_continuous_qualitative(palette = "Dark 3") +
coord_fixed(expand = FALSE)Continuous ggplot2 color scales using the color palettes generated by sequential_hcl.
scale_colour_continuous_sequential(
palette = NULL,
c1 = NULL,
c2 = NULL,
cmax = NULL,
l1 = NULL,
l2 = NULL,
h1 = NULL,
h2 = NULL,
p1 = NULL,
p2 = NULL,
alpha = 1,
rev = TRUE,
begin = 0,
end = 1,
na.value = "grey50",
guide = "colourbar",
aesthetics = "colour",
n_interp = 11,
...
)
scale_color_continuous_sequential(
palette = NULL,
c1 = NULL,
c2 = NULL,
cmax = NULL,
l1 = NULL,
l2 = NULL,
h1 = NULL,
h2 = NULL,
p1 = NULL,
p2 = NULL,
alpha = 1,
rev = TRUE,
begin = 0,
end = 1,
na.value = "grey50",
guide = "colourbar",
aesthetics = "colour",
n_interp = 11,
...
)
scale_fill_continuous_sequential(..., aesthetics = "fill")palette |
The name of the palette to be used. Run |
c1 |
Beginning chroma value. |
c2 |
Ending chroma value. |
cmax |
Maximum chroma value. |
l1 |
Beginning luminance value. |
l2 |
Ending luminance value. |
h1 |
Beginning hue value. |
h2 |
Ending hue value. If set to |
p1 |
Control parameter determining how chroma should vary (1 = linear, 2 = quadratic, etc.). |
p2 |
Control parameter determining how luminance should vary (1 = linear, 2 = quadratic, etc.). |
alpha |
Numeric vector of values in the range |
rev |
If |
begin |
Number in the range of |
end |
Number in the range of |
na.value |
Color to be used for missing data points. |
guide |
Type of legend. Use |
aesthetics |
The ggplot2 aesthetics to which this scale should be applied. |
n_interp |
Number of discrete colors that should be used to interpolate the continuous color scale. 11 will work fine in most cases. |
... |
common continuous scale parameters: 'name', 'breaks', 'labels', and 'limits'. See
|
If both a valid palette name and palette parameters are provided then the provided palette parameters overwrite the parameters in the named palette. This enables easy customization of named palettes.
Compared to sequential_hcl the ordering of the colors in the sequential ggplot2 scale
are reversed by default (i.e., rev = TRUE) to be more consistent with ggplot2's own scales such as
scale_color_brewer. For most named palettes this leads to darker and more
colorful colors for larger values on the scale. This is typically the better default on light/white
backgrounds.
library("ggplot2")
# base plot
gg <- ggplot(iris, aes(x = Species, y = Sepal.Width, color = Sepal.Length)) +
geom_jitter(width = 0.3) + theme_minimal()
# default settings
gg + scale_color_continuous_sequential()
# switch palette and overwrite some default values
gg + scale_color_continuous_sequential(palette = "Reds", l1 = 20, c2 = 70, p1 = 1)
# select a range out of the entire palette
gg + scale_color_continuous_sequential(palette = "Heat", begin = 0.2, end = 0.8)
# volcano plot
df <- data.frame(height = c(volcano), x = c(row(volcano)), y = c(col(volcano)))
ggplot(df, aes(x, y, fill = height)) +
geom_raster() + scale_fill_continuous_sequential(palette = "Terrain", rev = FALSE) +
coord_fixed(expand = FALSE)Discrete ggplot2 color scales using the color palettes generated by diverging_hcl.
scale_colour_discrete_diverging(
palette = NULL,
c1 = NULL,
cmax = NULL,
l1 = NULL,
l2 = NULL,
h1 = NULL,
h2 = NULL,
p1 = NULL,
p2 = NULL,
alpha = 1,
rev = FALSE,
nmax = NULL,
order = NULL,
aesthetics = "colour",
...
)
scale_color_discrete_diverging(
palette = NULL,
c1 = NULL,
cmax = NULL,
l1 = NULL,
l2 = NULL,
h1 = NULL,
h2 = NULL,
p1 = NULL,
p2 = NULL,
alpha = 1,
rev = FALSE,
nmax = NULL,
order = NULL,
aesthetics = "colour",
...
)
scale_fill_discrete_diverging(..., aesthetics = "fill")palette |
The name of the palette to be used. Run |
c1 |
Chroma value at the scale endpoints. |
cmax |
Maximum chroma value. |
l1 |
Luminance value at the scale endpoints. |
l2 |
Luminance value at the scale midpoint. |
h1 |
Hue value at the first endpoint. |
h2 |
Hue value at the second endpoint. |
p1 |
Control parameter determining how chroma should vary (1 = linear, 2 = quadratic, etc.). |
p2 |
Control parameter determining how luminance should vary (1 = linear, 2 = quadratic, etc.). |
alpha |
Numeric vector of values in the range |
rev |
If |
nmax |
Maximum number of different colors the palette should contain. If not provided, is calculated automatically from the data. |
order |
Numeric vector listing the order in which the colors should be used. Default is |
aesthetics |
The ggplot2 aesthetics to which this scale should be applied. |
... |
common discrete scale parameters: |
If both a valid palette name and palette parameters are provided then the provided palette parameters overwrite the parameters in the named palette. This enables easy customization of named palettes.
library("ggplot2")
# default colors with slightly darkened midpoint
ggplot(iris, aes(Sepal.Length, Sepal.Width, color = Species)) +
geom_point() + theme_minimal() +
scale_color_discrete_diverging(l2=75)
# color scale "Green-Orange"
ggplot(iris, aes(Sepal.Length, fill = Species)) +
geom_density(alpha = 0.7) + theme_classic() +
scale_fill_discrete_diverging(palette = "Green-Orange", rev = TRUE)
# use `nmax` and `order` to skip some colors
ggplot(iris, aes(Sepal.Length, fill = Species)) +
geom_density(alpha = 0.7) + theme_classic() +
scale_fill_discrete_diverging(palette = "Green-Orange", nmax = 5, order = c(1, 4, 5))Discrete ggplot2 color scales using the color palettes generated by divergingx_hcl.
scale_colour_discrete_divergingx(
palette = "Geyser",
c1 = NULL,
c2 = NULL,
c3 = NULL,
l1 = NULL,
l2 = NULL,
l3 = NULL,
h1 = NULL,
h2 = NULL,
h3 = NULL,
p1 = NULL,
p2 = NULL,
p3 = NULL,
p4 = NULL,
cmax1 = NULL,
cmax2 = NULL,
alpha = 1,
rev = FALSE,
nmax = NULL,
order = NULL,
aesthetics = "colour",
...
)
scale_color_discrete_divergingx(
palette = "Geyser",
c1 = NULL,
c2 = NULL,
c3 = NULL,
l1 = NULL,
l2 = NULL,
l3 = NULL,
h1 = NULL,
h2 = NULL,
h3 = NULL,
p1 = NULL,
p2 = NULL,
p3 = NULL,
p4 = NULL,
cmax1 = NULL,
cmax2 = NULL,
alpha = 1,
rev = FALSE,
nmax = NULL,
order = NULL,
aesthetics = "colour",
...
)
scale_fill_discrete_divergingx(..., aesthetics = "fill")palette |
The name of the palette to be used. |
h1, h2, h3, c1, c2, c3, l1, l2, l3, p1, p2, p3, p4, cmax1, cmax2
|
Parameters to customize the scale. See |
alpha |
Numeric vector of values in the range |
rev |
If |
nmax |
Maximum number of different colors the palette should contain. If not provided, is calculated automatically from the data. |
order |
Numeric vector listing the order in which the colors should be used. Default is |
aesthetics |
The ggplot2 aesthetics to which this scale should be applied. |
... |
common discrete scale parameters: |
Available CARTO palettes: ArmyRose, Earth, Fall, Geyser, TealRose, Temps, Tropic.
Available ColorBrewer.org palettes: Spectral, PuOr, RdYlGn, RdYlBu, RdGy, BrBG, PiYG, PRGn, RdBu.
If both a valid palette name and palette parameters are provided then the provided palette parameters overwrite the parameters in the named palette. This enables easy customization of named palettes.
library("ggplot2")
# default color scale
ggplot(iris, aes(Sepal.Length, Sepal.Width, color = Species)) +
geom_point() + theme_minimal() +
scale_color_discrete_divergingx()
# color scale "Tropic"
ggplot(iris, aes(Sepal.Length, fill = Species)) +
geom_density(alpha = 0.7) + theme_classic() +
scale_fill_discrete_divergingx(palette = "Tropic", rev = TRUE)
# use `nmax` and `order` to skip some colors
ggplot(iris, aes(Sepal.Length, fill = Species)) +
geom_density(alpha = 0.7) + theme_classic() +
scale_fill_discrete_divergingx(palette = "Tropic", nmax = 5, order = c(1, 4, 5))Discrete ggplot2 color scales using the color palettes generated by qualitative_hcl.
scale_colour_discrete_qualitative(
palette = NULL,
c1 = NULL,
l1 = NULL,
h1 = NULL,
h2 = NULL,
alpha = 1,
rev = FALSE,
nmax = NULL,
order = NULL,
aesthetics = "colour",
...
)
scale_color_discrete_qualitative(
palette = NULL,
c1 = NULL,
l1 = NULL,
h1 = NULL,
h2 = NULL,
alpha = 1,
rev = FALSE,
nmax = NULL,
order = NULL,
aesthetics = "colour",
...
)
scale_fill_discrete_qualitative(..., aesthetics = "fill")palette |
The name of the palette to be used. Run |
c1 |
Chroma value, used for all colors in the scale. |
l1 |
Luminance value, used for all colors in the scale. |
h1 |
Beginning hue value. |
h2 |
Ending hue value. |
alpha |
Numeric vector of values in the range |
rev |
If |
nmax |
Maximum number of different colors the palette should contain. If not provided, is calculated automatically from the data. |
order |
Numeric vector listing the order in which the colors should be used. Default is |
aesthetics |
The ggplot2 aesthetics to which this scale should be applied. |
... |
common discrete scale parameters: |
If both a valid palette name and palette parameters are provided then the provided palette parameters overwrite the parameters in the named palette. This enables easy customization of named palettes.
library("ggplot2")
# default colors
ggplot(iris, aes(Sepal.Length, Sepal.Width, color = Species)) +
geom_point() + theme_minimal() +
scale_color_discrete_qualitative()
# color scale "Harmonic"
ggplot(iris, aes(Sepal.Length, fill = Species)) +
geom_density(alpha = 0.7) + scale_fill_discrete_qualitative(palette = "Harmonic")Discrete ggplot2 color scales using the color palettes generated by sequential_hcl.
scale_colour_discrete_sequential(
palette = NULL,
c1 = NULL,
c2 = NULL,
cmax = NULL,
l1 = NULL,
l2 = NULL,
h1 = NULL,
h2 = NULL,
p1 = NULL,
p2 = NULL,
alpha = 1,
rev = TRUE,
nmax = NULL,
order = NULL,
aesthetics = "colour",
...
)
scale_color_discrete_sequential(
palette = NULL,
c1 = NULL,
c2 = NULL,
cmax = NULL,
l1 = NULL,
l2 = NULL,
h1 = NULL,
h2 = NULL,
p1 = NULL,
p2 = NULL,
alpha = 1,
rev = TRUE,
nmax = NULL,
order = NULL,
aesthetics = "colour",
...
)
scale_fill_discrete_sequential(..., aesthetics = "fill")palette |
The name of the palette to be used. Run |
c1 |
Beginning chroma value. |
c2 |
Ending chroma value. |
cmax |
Maximum chroma value. |
l1 |
Beginning luminance value. |
l2 |
Ending luminance value. |
h1 |
Beginning hue value. |
h2 |
Ending hue value. If set to |
p1 |
Control parameter determining how chroma should vary (1 = linear, 2 = quadratic, etc.). |
p2 |
Control parameter determining how luminance should vary (1 = linear, 2 = quadratic, etc.). |
alpha |
Numeric vector of values in the range |
rev |
If |
nmax |
Maximum number of different colors the palette should contain. If not provided, is calculated automatically from the data. |
order |
Numeric vector listing the order in which the colors should be used. Default is |
aesthetics |
The ggplot2 aesthetics to which this scale should be applied. |
... |
common discrete scale parameters: |
If both a valid palette name and palette parameters are provided then the provided palette parameters overwrite the parameters in the named palette. This enables easy customization of named palettes.
Compared to sequential_hcl the ordering of the colors in the sequential ggplot2 scale
are reversed by default (i.e., rev = TRUE) to be more consistent with ggplot2's own scales such as
scale_color_brewer. For most named palettes this leads to darker and more
colorful colors for larger values on the scale. This is typically the better default on light/white
backgrounds.
library("ggplot2")
# default colors
ggplot(iris, aes(Sepal.Length, Sepal.Width, color = Species)) +
geom_point() + scale_color_discrete_sequential() + theme_classic()
# customization of named palette
ggplot(iris, aes(Sepal.Length, Sepal.Width, color = Species)) +
geom_point() + scale_colour_discrete_sequential(palette = "Reds", nmax = 4, p2 = 1.5) +
theme_classic()
# color scale "Terrain"
ggplot(iris, aes(Sepal.Length, fill = Species)) +
geom_density(alpha = 0.7) + scale_fill_discrete_sequential(palette = "Terrain") + theme_minimal()Transformation of R colors by simulating color vision deficiencies, based on a CVD transform matrix.
simulate_cvd(col, cvd_transform, linear = TRUE)
deutan(col, severity = 1, linear = TRUE)
protan(col, severity = 1, linear = TRUE)
tritan(col, severity = 1, linear = TRUE)
interpolate_cvd_transform(cvd, severity = 1)col |
vector of R colors. Can be any of the three kinds of R colors,
i.e., either a color name (an element of |
cvd_transform |
numeric 3x3 matrix, specifying the color vision deficiency transform matrix. |
linear |
logical. Should the color vision deficiency transformation be applied to the
linearized RGB coordinates (default)? If |
severity |
numeric. Severity of the color vision defect, a number between 0 and 1. |
cvd |
list of cvd transformation matrices. See |
Using the physiologically-based model for simulating color vision deficiency (CVD)
of Machado et al. (2009), different kinds of limitations can be
emulated: deuteranope (green cone cells defective), protanope (red cone cells defective),
and tritanope (blue cone cells defective).
The workhorse function to do so is simulate_cvd which can take any vector
of valid R colors and transform them according to a certain CVD transformation
matrix (see cvd) and transformation equation.
The functions deutan, protan, and tritan are the high-level functions for
simulating the corresponding kind of colorblindness with a given severity.
Internally, they all call simulate_cvd along with a (possibly interpolated)
version of the matrices from cvd. Matrix interpolation can be carried out with
the function interpolate_cvd_transform (see examples).
If input col is a matrix with three rows named R, G, and
B (top down) they are interpreted as Red-Green-Blue values within the
range [0-255]. Then the CVD transformation is applied directly to these
coordinates avoiding any further conversions.
Finally, if col is a formal color-class object, then its
coordinates are transformed to (s)RGB coordinates, as described above, and returned as a formal
object of the same class after the color vision deficiency simulation.
Up to version 2.0-3 of the package, the CVD transformations had been applied
directly to the gamma-corrected sRGB coordinates (corresponding to the hex coordinates
of the colors), following the illustrations of Machado et al. (2009). However,
the paper implicitly relies on a linear RGB space (see page 1294, column 1) where their
linear matrix transformations for simulating color vision deficiencies are applied.
Therefore, starting from version 2.1-0 of the package, a new argument linear = TRUE
has been added that first maps the provided colors to linearized RGB coordinates, applies
the color vision deficiency transformation, and then maps back to gamma-corrected sRGB
coordinates. Optionally, linear = FALSE can be used to restore the behavior
from previous versions. For most colors the difference between the two strategies is
negligible but for some highly-saturated colors it becomes more noticable, e.g., for
red, purple, or orange.
A color object as specified in the input col (hexadecimal string, RGB matrix,
or formal color class) with simulated color vision deficiency.
Machado GM, Oliveira MM, Fernandes LAF (2009). “A Physiologically-Based Model for Simulation of Color Vision Deficiency.” IEEE Transactions on Visualization and Computer Graphics. 15(6), 1291–1298. doi:10.1109/TVCG.2009.113 Online version with supplements at http://www.inf.ufrgs.br/~oliveira/pubs_files/CVD_Simulation/CVD_Simulation.html.
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
# simulate color-vision deficiency by calling `simulate_cvd` with specified matrix
simulate_cvd(c("#005000", "blue", "#00BB00"), tritanomaly_cvd["6"][[1]])
# simulate color-vision deficiency by calling the shortcut high-level function
tritan(c("#005000", "blue", "#00BB00"), severity = 0.6)
# simulate color-vision deficiency by calling `simulate_cvd` with interpolated cvd matrix
simulate_cvd(c("#005000", "blue", "#00BB00"),
interpolate_cvd_transform(tritanomaly_cvd, severity = 0.6))
# apply CVD directly on wide RGB matrix (with R/G/B channels in rows)
RGB <- diag(3) * 255
rownames(RGB) <- c("R", "G", "B")
deutan(RGB)Visualization of color palettes (given as hex codes) in HCL and/or RGB coordinates.
specplot(
x,
y = NULL,
rgb = FALSE,
hcl = TRUE,
fix = TRUE,
cex = 1,
type = "l",
lwd = 2 * cex,
lty = 1,
pch = NULL,
mar = NULL,
oma = NULL,
main = NULL,
legend = TRUE,
palette = TRUE,
plot = TRUE,
...
)x |
character vector containing color hex codes. |
y |
optional second character vector containing further color hex codes,
to be used for comparing two palettes ( |
rgb |
logical or color specification. Should the RGB spectrum be visualized? Can also be a vector of three colors for the legend of R/G/B coordinates. |
hcl |
logical or color specification. Should the HCL spectrum be visualized? Can also be a vector of three colors for the legend of H/C/L coordinates. |
fix |
logical. Should the hues be fixed to be on a smooth(er) curve? For details see below. |
cex |
numeric. Character extension for figure axes and labels. |
type, lwd, lty, pch
|
plotting parameters passed to
|
mar, oma
|
numeric or logical. Either numeric vectors of length 4 giving
the (outer) margins or a logical indicating whether |
main |
character. Main title of the plot. |
legend |
logical. Should legends for the coordinates be plotted? |
palette |
logical. Should the given palette |
plot |
logical. Should the RGB and/or HCL coordinates be plotted? |
... |
currently not used. |
The function specplot transforms a given color palette in hex codes
into their HCL (polarLUV) and/or RGB
(sRGB) coordinates. As the hues for low-chroma
colors are not (or poorly) identified, by default a smoothing is applied to
the hues (fix = TRUE). Also, to avoid jumps from 0 to 360 or vice
versa, the hue coordinates are shifted suitably.
By default (plot = TRUE), the resulting HCL and optionally RGB coordinates are
visualized by simple line plots along with the color palette x
itself. The x-axis simply gives the ordering of the colors in the palette
The y-axis depicts the following information: (1) Hue is drawn in red and
coordinates are indicated on the axis on the right with range [0, 360] or
(if necessary) [-360, 360]. (2) Chroma is drawn in green with coordinates on
the left axis. The range [0, 100] is used unless the palette necessitates
higher chroma values. (3) Luminance is drawn in blue with coordinates on the
left axis in the range [0, 100]. Luminance (and hence also chroma) is on
the left axis because it is arguably most important for understanding the
type of palette (qualitative vs. sequential vs. diverging). To facilitate
reading the legend the reversed order Luminance / Chroma / Hue is used so that
the legend labels are closer to the axis they pertain to.
For comparing two palettes, specplot(x, y) can be used which adds
lines (dashed, by default) corresponding to the y palette HCL/RGB
coordinates in the display.
specplot invisibly returns a list with components
HCL |
a matrix of HCL coordinates, |
RGB |
a matrix of sRGB coordinates, |
hex |
original color palette |
Reto Stauffer, Achim Zeileis
Zeileis A, Hornik K, Murrell P (2009). Escaping RGBland: Selecting Colors for Statistical Graphics. Computational Statistics & Data Analysis, 53, 3259–3270. doi:10.1016/j.csda.2008.11.033 Preprint available from https://www.zeileis.org/papers/Zeileis+Hornik+Murrell-2009.pdf.
Stauffer R, Mayr GJ, Dabernig M, Zeileis A (2015). Somewhere over the Rainbow: How to Make Effective Use of Colors in Meteorological Visualizations. Bulletin of the American Meteorological Society, 96(2), 203–216. doi:10.1175/BAMS-D-13-00155.1
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
## spectrum of the (in)famous RGB rainbow palette (in both RGB and HCL)
specplot(rainbow(100), rgb = TRUE)
## spectrum of HCL-based palettes: qualitative/sequential/diverging
specplot(qualitative_hcl(100, "Set 2"))
specplot(sequential_hcl(100, "Blues 2"))
specplot(diverging_hcl(100, "Blue-Red"))
## return computed RGB and HCL coordinates
res <- specplot(rainbow(10), plot = FALSE)
print(res)This function creates colors of class sRGB; a subclass of the virtual
color-class class.
sRGB(R, G, B, names)
R, G, B
|
these arguments give the red, green and blue intensities of the
colors (the values should lie between 0 and 1). The values can be provided
in separate |
names |
A vector of names for the colors (by default the row names of
|
This function creates colors in the standard sRGB color space (IEC standard 61966).
An object of class sRGB which inherits from class color.
Ross Ihaka
RGB, HSV, XYZ,
LAB, polarLAB, LUV,
polarLUV.
# Create a random set of colors
set.seed(1)
sRGB(R = runif(20), G = runif(20), B = runif(20))Visualization of color palettes in columns of color swatches.
swatchplot(
x,
...,
nrow = 20,
border = NULL,
sborder = NULL,
off = NULL,
mar = NULL,
line = NULL,
cex = NULL,
font = 1:2,
cvd = FALSE
)x |
character vector/matrix (or list of character vectors/matrices) containing color hex codes. |
... |
further (possibly named) character vectors/matrices with color hex codes. |
nrow |
integer specifying the maximal number of rows of swatches. (The actual number might be lower in order to balance the rows used in each column.) |
border |
color for border of individual color rectangles. By default
|
sborder |
color for border of the entire palette swatch. By default
|
off |
numeric vector of length 2. Offset in horizontal and vertical direction
(specified as a fraction of the rectangle for one color). By default, the
horizontal offset is |
mar |
numeric vector of length 4, specifying the margins of column of color swatches. |
line |
numeric. Line in which the palette names (if any) are printed in the margin. |
cex, font
|
numeric vectors of length 1 or 2. Specifications for the annotation text for the individual palettes and lists of palettes, respectively. |
cvd |
logical or character indicating whether color vision deficiencies
should be emulated with |
The function swatchplot is a convenience function for displaying
collections of palettes that can be specified as lists or matrices of
character color specifications. Essentially, the function just calls
rect but the value-added are the heuristics used
for choosing default labels, margins, spacings, borders. These are selected
to work well for hcl_palettes and might need further tweaking
in future versions.
swatchplot invisibly returns a matrix with colors and annotations.
Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49. doi:10.18637/jss.v096.i01
## swatches of several palette vectors
swatchplot(
"Hue" = sequential_hcl(5, h = c(0, 300), c = c(60, 60), l = 65),
"Chroma" = sequential_hcl(5, h = 0, c = c(100, 0), l = 65, rev = TRUE, power = 1),
"Luminance" = sequential_hcl(5, h = 260, c = c(25, 25), l = c(25, 90), rev = TRUE, power = 1),
off = 0
)
## swatches of named palette matrices
bprg <- c("Blues", "Purples", "Reds", "Greens")
swatchplot(
"Single-hue" = t(sapply(paste(bprg, 2), sequential_hcl, n = 7)),
"Single-hue (advanced)" = t(sapply(paste(bprg, 3), sequential_hcl, n = 7)),
"Multi-hue (advanced)" = t(sapply(bprg, sequential_hcl, n = 7)),
nrow = 5
)
## swatches with color vision deficiency emulation
swatchplot(sequential_hcl(7, "Viridis"), cvd = TRUE)
swatchplot(
"YlGnBu" = sequential_hcl(7, "YlGnBu"),
"Viridis" = sequential_hcl(7, "Viridis"),
cvd = c("deutan", "desaturate")
)County polygons for Alabama, Georgia, and South Carolina plus an artifical variable used for coloring.
data("USSouthPolygon")A data frame with coordinates of the vertices of the county polygons
(x, y) and an artificial variable z constructed for
illustrating colored maps.
Polygon data taken from maps package of Becker, Wilks, Brownrigg, and Minka (2012). Version 2.2-6. https://CRAN.R-project.org/package=maps
## generate color palette
pal <- diverging_hcl(9)
n <- length(pal)
## draw shaded polygons
plot(0, 0, type = "n", xlab = "", ylab = "", xaxt = "n", yaxt = "n", bty = "n",
xlim = c(-88.5, -78.6), ylim = c(30.2, 35.2), asp = 1)
polygon(USSouthPolygon, col = pal[cut(na.omit(USSouthPolygon$z), breaks = 0:n/n)])This function can be used to control the single global whitepoint that affects all color conversions within the package (that require a whitepoint, i.e., go through XYZ).
whitepoint(white, ...)
white, ...
|
Either missing (to query the whitepoint) or
|
whitepoint returns an XYZ color object for the whitepoint
(invisibly in case a new whitepoint was set).
XYZ and color-class.
# query current whitepoint (D65 by default)
whitepoint()
# Illuminant E
whitepoint(XYZ(100, 100, 100))
# equivalently
whitepoint(100, 100, 100)
whitepoint(c(100, 100, 100))
whitepoint(cbind(100, 100, 100))
whitepoint()
## reset
whitepoint(NULL)
whitepoint()Given a color object, this function writes a file containing the hexadecimal representation of the colors in the object.
writehex(x, file = "")x |
a color object. |
file |
the name of the file to be written. |
This function converts the given color object to RGB and then writes
hexadecimal strings (of the form #RRGGBB) representing the colors to
the specified file.
The name of the file is returned as the value of the function.
Ross Ihaka
readhex, readRGB,
hex2RGB, RGB, HSV,
XYZ, LAB, polarLAB,
LUV, polarLUV.
set.seed(1)
x <- sRGB(runif(10), runif(10), runif(10))
## IGNORE_RDIFF_BEGIN
writehex(x, file.path(tempdir(), "random.txt"))
## IGNORE_RDIFF_ENDThis function creates colors of class XYZ; a subclass of the virtual
color-class class.
XYZ(X, Y, Z, names)
X, Y, Z
|
these arguments give the X, Y and Z coordinates of the colors.
The values can be provided in separate |
names |
A vector of names for the colors (by default the row names of
|
The X, Y and Z values are the levels of the CIE primaries. These are scaled so that the luminance of the display white-point is 100. The white-point is taken to be D65, which means that its coordinates are 95.047, 100.000, 108.883.
An object of class XYZ which inherits from class color.
Ross Ihaka
RGB, HSV, LAB,
polarLAB, LUV, polarLUV.
## Generate white in XYZ space
XYZ(95.047, 100.000, 108.883)