Colorspace: a Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49

Home , CIELUV, Color, HCL color space, Palette (computing), RGB color space, SRGB

Package ‘colorspace’

June 24, 2021 Version 2.0-2 Date 2021-06-24 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 and in the accompanying scientific paper: Zeileis et al. (2020, Journal of Statistical Software, ). Depends R (>= 3.0.0), methods Imports graphics, grDevices, stats Suggests datasets, utils, KernSmooth, MASS, kernlab, mvtnorm, vcd, tcltk, shiny, shinyjs, ggplot2, dplyr, scales, grid, png, jpeg, knitr, rmarkdown, RColorBrewer, rcartocolor, scico, viridis, wesanderson VignetteBuilder knitr License BSD_3_clause + file LICENSE

URL https://colorspace.R-Forge.R-project.org/, https://hclwizard.org/

BugReports https://colorspace.R-Forge.R-project.org/contact.html LazyData yes RoxygenNote 7.1.1 NeedsCompilation yes

1 2 R topics documented:

Author 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 Repository CRAN Date/Publication 2021-06-24 07:00:06 UTC

R topics documented:

adjust_transparency ...... 3 choose_palette ...... 5 color-class ...... 7 contrast_ratio ...... 8 coords ...... 10 cvd...... 10 cvd_emulator ...... 11 cvd_image ...... 12 demoplot ...... 12 desaturate ...... 14 divergingx_hcl ...... 15 hclplot ...... 18 hcl_color_picker ...... 20 hcl_palettes ...... 21 hex...... 27 hex2RGB ...... 28 HLS...... 29 HSV...... 30 LAB...... 31 lighten ...... 32 LUV...... 34 max_chroma ...... 36 mixcolor ...... 37 polarLAB ...... 38 polarLUV ...... 39 rainbow_hcl ...... 40 readhex ...... 43 readRGB ...... 44 RGB...... 45 scale_colour_binned_diverging ...... 46 scale_colour_binned_divergingx ...... 48 scale_colour_binned_qualitative ...... 50 scale_colour_binned_sequential ...... 52 adjust_transparency 3

scale_colour_continuous_diverging ...... 55 scale_colour_continuous_divergingx ...... 57 scale_colour_continuous_qualitative ...... 60 scale_colour_continuous_sequential ...... 62 scale_colour_discrete_diverging ...... 64 scale_colour_discrete_divergingx ...... 66 scale_colour_discrete_qualitative ...... 69 scale_colour_discrete_sequential ...... 70 simulate_cvd ...... 73 specplot ...... 74 sRGB ...... 77 swatchplot ...... 78 USSouthPolygon ...... 79 whitepoint ...... 80 writehex ...... 81 XYZ...... 82

Index 84

adjust_transparency Adjust or Extract Transparency of Colors

Description Adjust (i.e., add, remove, or modify) or extract alpha transparency of a vector of colors.

Usage adjust_transparency(col, alpha = TRUE)

extract_transparency(col, mode = "numeric", default = 1)

Arguments col vector of R colors. Can be any of the three kinds of R colors, i.e., either a color name (an element of colors), a hexadecimal (hex) string of the form "#rrggbb" or "#rrggbbaa" (see rgb), or an integer i meaning palette()[i]. Addition- ally, col can be a formal color-class object or a matrix with three rows containing R/G/B (0-255) values. alpha either a new alpha transparency value or logical (to add/remove alpha) or NULL. See details. mode character specifying the output mode for the alpha transparency, can be "numeric", "integer", "character" or "hexmode". See details. 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. 4 adjust_transparency

Details Alpha transparency is useful for making colors semi-transparent, e.g., for overlaying different ele- ments 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.

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

References 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

See Also

desaturate

Examples

# 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) 10 cvd

coords Extract the Numerical Coordinates of a Color

Description This function returns a matrix with three columns which give the coordinates of a color in its natural color space.

Usage coords(color)

Arguments color A color.

Value A numeric matrix giving the coordinates of the color.

Author(s) Ross Ihaka

See Also RGB, XYZ, LAB, polarLAB, LUV, polarLUV, mixcolor.

Examples x <- RGB(1, 0, 0) coords(as(x, "HSV"))

cvd Color Vision Deﬁciency (CVD) Conversion Tables

Description Conversion tables for simulating different types of color vision deﬁciency (CVD): Protanomaly, deutanomaly, tritanomaly.

Usage protanomaly_cvd

deutanomaly_cvd

tritanomaly_cvd cvd_emulator 11

Format Lists of 3x3 RGB-color transformation matrices for the various types of CVD. Each list contains 11 transformation matrices representing increasingly severe color vision deﬁciency.

Details Machado et al. (2009) have established a novel model, that allows to handle normal color vision, anomalous trichromacy, and dichromacy in a uniﬁed 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.

References Machado GM, Oliveira MM, Fernandes LAF (2009). A Physiologically-Based Model for Sim- ulation of Color Vision Deﬁciency. IEEE Transactions on Visualization and Computer Graph- ics. 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

See Also

polarLUV, hex, lighten

Examples

## 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 RGB values RGB <- t(hex2RGB(rainbow(3))@coords * 255) desaturate(RGB)

divergingx_hcl (More) Flexible Diverging HCL Palettes

Description

Diverging HCL color palettes generated through combination of two fully ﬂexible (and possibly unbalanced) multi-hue sequential palettes. 16 divergingx_hcl

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

Arguments n the number of colors (≥ 1) to be in the palette. palette character with the name (see details). ... arguments passed to hex. fixup logical. Should the color be corrected to a valid RGB value? alpha numeric vector of values in the range [0,1] for alpha transparency channel (0 means transparent and 1 means opaque). 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 h1. c2 numeric. Chroma coordinate corresponding to h2 (if NA, set to 0). c3 numeric. Chroma coordinate corresponding to h3. l1 numeric. Luminance coordinate corresponding to h1. l2 numeric. Luminance coordinate corresponding to h2. divergingx_hcl 17

l3 numeric. Luminance coordinate corresponding to h3 (if NA, l1 is used). p1 numeric. Power parameter for chroma coordinates in first sequential palette. p2 numeric. Power parameter for luminance coordinates in first sequential palette (if NA, p1 is used). p3 numeric. Power parameter for chroma coordinates in second sequential palette (if NA, p1 is used). p4 numeric. Power parameter for luminance coordinates in second sequential palette (if NA, p3 is used). cmax1 numeric. Maximum chroma coordinate in first sequential palette (not used if NA). cmax2 numeric. Maximum chroma coordinate in second sequential palette (if NA, cmax1 is used). plot logical. Should the selected HCL color palettes be visualized?

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

Value A character vector with (s)RGB codings of the colors in the palette.

See Also sequential_hcl, diverging_hcl 18 hclplot

Examples ## 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"))

hclplot Palette Plot in HCL Space

Description Visualization of color palettes in HCL space projections.

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

Arguments x character vector containing color hex codes, or a color-class object. type type character specifying which type of palette should be visualized ("qualitative", "sequential", or "diverging"). For qualitative palettes a hue-chroma plane is used, otherwise a chroma-luminance plane. By default, the type is inferred from the luminance trajectory corresponding to x. h numeric hue(s) to be used for type = "sequential" and type = "diverging". By default, these are inferred from the colors in x. c numeric. Maximal chroma value to be used. l numeric luminance(s) to be used for type = "qualitative". By default, this is inferred from the colors in x. hclplot 19

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.

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

Value hclplot invisibly returns a matrix with the HCL coordinates corresponding to x.

See Also

sRGB, RGB, XYZ, LAB, polarLAB, LUV, polarLUV.

Examples

# A rainbow of full-intensity hues HLS(seq(0, 360, length.out = 13)[-13], 0.5, 1) 30 HSV

HSV Create HSV Colors

Description

This function creates colors of class HSV; a subclass of the virtual color-class class.

Usage HSV(H, S, V, names)

Arguments

H, S, V These arguments give the hue, saturation and value of the colors. The values can be provided in separate H, S and V vectors or in a three-column matrix passed as H. names A vector of names for the colors (by default the row names of H are used).

Details

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 ﬁrst involve a conversion to a speciﬁc RGB color space, for example the standard sRGB color space (IEC standard 61966).

Value

An object of class HSV which inherits from class color.

Author(s)

Ross Ihaka

See Also

sRGB, RGB, XYZ, LAB, polarLAB, LUV, polarLUV.

Examples

# A rainbow of full-intensity hues HSV(seq(0, 360, length.out = 13)[-13], 1, 1) LAB 31

LAB Create LAB Colors

Description This function creates colors of class “LAB”; a subclass of the virtual color-class class.

Usage LAB(L, A, B, names)

Arguments L, A, B these arguments give the L, A and B coordinates of the colors. The values can be provided in separate L, A and B vectors or in a three-column matrix passed as L. names a vector of names for the colors (by default the row names of L are used).

Details The L, A and B values give the coordinates of the colors in the CIE L∗a∗b∗ 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 a and b coordinates measure positions on green/red and blue/yellow axes.

Value An object of class LAB which inherits from class color.

Author(s) Ross Ihaka

See Also RGB, HSV, XYZ, LAB, polarLAB, LUV, polarLUV.

Examples ## Show the LAB space set.seed(1) x <- RGB(runif(1000), runif(1000), runif(1000)) y <- as(x, "LAB") head(x) head(y) plot(y) 32 lighten

lighten Algorithmically Lighten or Darken Colors

Description The functions lighten and darken take a vector of R colors and adjust the colors such that they appear lightened or darkened, respectively.

Usage lighten( col, amount = 0.1, method = c("relative", "absolute"), space = c("HCL", "HLS", "combined"), fixup = TRUE )

darken(col, amount = 0.1, space = "combined", ...)

Arguments col vector of any of the three kind of R colors, i.e., either a color name (an element of colors), a hexadecimal string of the form "#rrggbb" or "#rrggbbaa" (see rgb), or an integer i meaning palette()[i]. amount numeric specifying the amount of lightening. This is applied either multiplica- tively or additively to the luminance value, depending on the setting of method (either relative or absolute). Negative numbers cause darkening. method character string specifying the adjustment method. Can be either "relative" or "absolute". space character string specifying the color space in which adjustment happens. Can be either "HLS" or "HCL". fixup logical If set to TRUE, colors that fall outside of the RGB color gamut are slightly modiﬁed by translating individual primary values so they lie between 0 and 255. If set to FALSE, out-of-gamut colors are replaced by NA. ... Other parameters handed to the function lighten().

Details The color adjustment can be calculated in three different color spaces.

1. 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. 2. 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. lighten 33

3. If space = "combined", the colors are ﬁrst 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 speciﬁc application.

Value A character vector with (s)RGB codings of the colors in the palette.

See Also

RGB, HSV, XYZ, LAB, polarLAB, polarLUV.

Examples

## Show the LUV space set.seed(1) x <- RGB(runif(1000), runif(1000), runif(1000)) y <- as(x, "LUV") head(x) head(y) plot(y) 36 max_chroma

max_chroma Compute Maximum Chroma for Given Hue and Luminance in HCL

Description Compute approximately the maximum chroma possible for a given hue and luminance combination in the HCL color space.

Usage max_chroma(h, l, floor = FALSE)

max_chroma_table

Arguments h 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?

Details 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 inter- polations 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.

Value A numeric vector with the maximum chroma coordinates.

See Also

RGB, HSV, XYZ, LAB, polarLAB, LUV, polarLUV.

Examples

mixcolor(0.5, RGB(1, 0, 0), RGB(0, 1, 0)) 38 polarLAB

polarLAB Create polarLAB Colors

Description This function creates colors of class “polarLAB”; a subclass of the virtual color-class class.

Usage polarLAB(L, C, H, names)

Arguments L, C, H these arguments give the L, C and H coordinates of the colors. The values can be provided in separate L, C and H vectors or in a three-column matrix passed as L. names A vector of names for the colors (by default the row names of L are used).

Details The polarLAB space is a transformation of the CIE L∗a∗b∗ space so that the a and b values are converted to polar coordinates. The radial component C measures chroma and the angular coordinate H is measures hue.

Value An object of class polarLAB which inherits from class color.

Author(s) Ross Ihaka

See Also RGB, HSV, XYZ, LAB, polarLAB, LUV, polarLUV.

Examples ## Show the polarLAB space set.seed(1) x <- RGB(runif(1000), runif(1000), runif(1000)) y <- as(x, "polarLAB") head(x) head(y) plot(y) polarLUV 39

polarLUV Create polarLUV (HCL) Colors

Description This function creates colors of class “polarLUV”; a subclass of the virtual color-class class.

Usage polarLUV(L, C, H, names)

Details The polarLUV space is a transformation of the CIE L∗u∗v∗ space so that the u and v values are converted to polar coordinates. The radial component C measures chroma and the angular coordinate H is measures hue. It is also known as the HCL (hue-chroma-luminance) space.

Value An object of class polarLUV which inherits from class color.

Author(s) Ross Ihaka

See Also RGB, HSV, XYZ, LAB, polarLAB, LUV, polarLUV.

Examples ## Show the polarLUV space set.seed(1) x <- RGB(runif(1000), runif(1000), runif(1000)) y <- as(x, "polarLUV") head(x) head(y) plot(y) 40 rainbow_hcl

rainbow_hcl HCL (and HSV) Color Palettes Corresponding to Base R Palettes

Description Color palettes based on the HCL (and HSV) color space to replace base R palettes.

Usage 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, rainbow_hcl 41

h = c(240, 0), s = 1, v = 1, power = 1, gamma = NULL, fixup = TRUE, alpha = 1, ... )

Arguments n the number of colors (≥ 1) to be in the palette. 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 [0,1] for alpha transparency channel (0 means transparent and 1 means opaque). ... Other arguments passed to hex. 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.

Details 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. 42 rainbow_hcl

Value A character vector with (s)RGB codings of the colors in the palette.

See Also

sRGB, HSV, XYZ, LAB, polarLAB, LUV, polarLUV.

Examples

# Create a random set of colors set.seed(1) RGB(R = runif(20), G = runif(20), B = runif(20)) 46 scale_colour_binned_diverging

scale_colour_binned_diverging HCL-Based Binned Diverging Color Scales for ggplot2

Description Binned ggplot2 color scales using the color palettes generated by diverging_hcl.

Usage 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_colour_binned_diverging 47

... )

scale_fill_binned_diverging(..., aesthetics = "fill")

Arguments palette The name of the palette to be used. Run hcl_palettes(type = "diverging") for available options. 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 ﬁrst 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 [0,1] for alpha transparency channel (0 means transparent and 1 means opaque). rev If TRUE, reverses the order of the colors in the color scale. 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 "coloursteps" for color bar with discrete steps. 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 binned_scale for more details.

Examples # 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)) 48 scale_colour_binned_divergingx

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)

scale_colour_binned_divergingx HCL-Based Binned Flexible Diverging Scales for ggplot2

Description Binned ggplot2 color scales using the color palettes generated by divergingx_hcl.

Usage 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_colour_binned_divergingx 49

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

Arguments 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 divergingx_hcl for details. alpha Numeric vector of values in the range [0,1] for alpha transparency channel (0 means transparent and 1 means opaque). rev If TRUE, reverses the order of the colors in the color scale. 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 "coloursteps" for color bar with discrete steps. 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 binned_scale for more details. 50 scale_colour_binned_qualitative

Details

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.

Examples

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)

scale_colour_binned_qualitative HCL-Based Binned Qualitative Color Scales for ggplot2

Description

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 51

Usage 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")

rev If TRUE, reverses the order of the colors in the color scale. begin Number in the range of [0,1] indicating to which point in the color scale the smallest data value should be mapped. end Number in the range of [0,1] indicating to which point in the color scale the largest data value should be mapped. na.value Color to be used for missing data points. guide Type of legend. Use "coloursteps" for color bar with discrete steps. 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 ﬁne in most cases. ... common binned scale parameters: ‘name‘, ‘breaks‘, ‘labels‘, and ‘limits‘. See binned_scale for more details.

Details

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.

Examples

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)

scale_colour_binned_sequential HCL-Based Binned Sequential Color Scales for ggplot2

Description

Binned ggplot2 color scales using the color palettes generated by sequential_hcl. scale_colour_binned_sequential 53

Usage

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") 54 scale_colour_binned_sequential

Arguments

palette The name of the palette to be used. Run hcl_palettes(type = "sequential") for available options. 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 NA, generates a single-hue scale. 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 [0,1] for alpha transparency channel (0 means transparent and 1 means opaque). rev If TRUE (default), reverses the order of the colors in the color scale (compared to sequential_hcl). begin Number in the range of [0,1] indicating to which point in the color scale the smallest data value should be mapped. end Number in the range of [0,1] indicating to which point in the color scale the largest data value should be mapped. na.value Color to be used for missing data points. guide Type of legend. Use "coloursteps" for color bar with discrete steps. 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 ﬁne in most cases. ... common binned scale parameters: ‘name‘, ‘breaks‘, ‘labels‘, and ‘limits‘. See binned_scale for more details.

Details

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. scale_colour_continuous_diverging 55

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

scale_colour_continuous_diverging HCL-Based Continuous Diverging Color Scales for ggplot2

Description Continuous ggplot2 color scales using the color palettes generated by diverging_hcl.

Usage 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, 56 scale_colour_continuous_diverging

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

Arguments palette The name of the palette to be used. Run hcl_palettes(type = "diverging") for available options. 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 ﬁrst 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 [0,1] for alpha transparency channel (0 means transparent and 1 means opaque). rev If TRUE, reverses the order of the colors in the color scale. 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 "colourbar" for continuous color bar. 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 continuous_scale for more details.

Examples # adapted from stackoverflow: https://stackoverflow.com/a/20127706/4975218

library("ggplot2")

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

scale_colour_continuous_divergingx HCL-Based Continuous Flexible Diverging Scales for ggplot2

Description Continuous ggplot2 color scales using the color palettes generated by divergingx_hcl.

Usage 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, 58 scale_colour_continuous_divergingx

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

rev If TRUE, reverses the order of the colors in the color scale. 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 "colourbar" for continuous color bar. 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 continuous_scale for more details.

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

Examples 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

# plot with diverging scale "Geyser" gg + scale_fill_continuous_divergingx(palette = "Geyser")

# plot with diverging scale "ArmyRose" gg + scale_fill_continuous_divergingx(palette = "ArmyRose") 60 scale_colour_continuous_qualitative

scale_colour_continuous_qualitative HCL-Based Continuous Qualitative Color Scales for ggplot2

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

Usage 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") scale_colour_continuous_qualitative 61

Arguments palette The name of the palette to be used. Run hcl_palettes(type = "qualitative") for available options. 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 [0,1] for alpha transparency channel (0 means transparent and 1 means opaque). rev If TRUE, reverses the order of the colors in the color scale. begin Number in the range of [0,1] indicating to which point in the color scale the smallest data value should be mapped. end Number in the range of [0,1] indicating to which point in the color scale the largest data value should be mapped. na.value Color to be used for missing data points. guide Type of legend. Use "colourbar" for continuous color bar. 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 ﬁne in most cases. ... common continuous scale parameters: ‘name‘, ‘breaks‘, ‘labels‘, and ‘limits‘. See continuous_scale for more details.

Examples 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) 62 scale_colour_continuous_sequential

scale_colour_continuous_sequential HCL-Based Continuous Sequential Color Scales for ggplot2

Description Continuous ggplot2 color scales using the color palettes generated by sequential_hcl.

Usage 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, scale_colour_continuous_sequential 63

na.value = "grey50", guide = "colourbar", aesthetics = "colour", n_interp = 11, ... )

scale_fill_continuous_sequential(..., aesthetics = "fill")

Arguments

palette The name of the palette to be used. Run hcl_palettes(type = "sequential") for available options. 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 NA, generates a single-hue scale. 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 [0,1] for alpha transparency channel (0 means transparent and 1 means opaque). rev If TRUE (default), reverses the order of the colors in the color scale (compared to sequential_hcl). begin Number in the range of [0,1] indicating to which point in the color scale the smallest data value should be mapped. end Number in the range of [0,1] indicating to which point in the color scale the largest data value should be mapped. na.value Color to be used for missing data points. guide Type of legend. Use "colourbar" for continuous color bar. 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 ﬁne in most cases. ... common continuous scale parameters: ‘name‘, ‘breaks‘, ‘labels‘, and ‘limits‘. See continuous_scale for more details. 64 scale_colour_discrete_diverging

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

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

scale_colour_discrete_diverging HCL-Based Discrete Diverging Color Scales for ggplot2

Description Discrete ggplot2 color scales using the color palettes generated by diverging_hcl.

Usage scale_colour_discrete_diverging( palette = NULL, c1 = NULL, cmax = NULL, l1 = NULL, l2 = NULL, h1 = NULL, scale_colour_discrete_diverging 65

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

rev If TRUE, reverses the order of the colors in the color scale. 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 1:nmax. aesthetics The ggplot2 aesthetics to which this scale should be applied. ... common discrete scale parameters: name, breaks, labels, na.value, limits and guide. See discrete_scale for more details.

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

scale_colour_discrete_divergingx HCL-Based Discrete Flexible Diverging Scales for ggplot2

Description Discrete ggplot2 color scales using the color palettes generated by divergingx_hcl.

Usage scale_colour_discrete_divergingx( palette = "Geyser", c1 = NULL, c2 = NULL, scale_colour_discrete_divergingx 67

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") 68 scale_colour_discrete_divergingx

Arguments

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 divergingx_hcl for details. alpha Numeric vector of values in the range [0,1] for alpha transparency channel (0 means transparent and 1 means opaque). rev If TRUE, reverses the order of the colors in the color scale. 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 1:nmax. aesthetics The ggplot2 aesthetics to which this scale should be applied. ... common discrete scale parameters: name, breaks, labels, na.value, limits and guide. See discrete_scale for more details.

Details

Examples

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)) scale_colour_discrete_qualitative 69

scale_colour_discrete_qualitative HCL-Based Discrete Qualitative Color Scales for ggplot2

Description Discrete ggplot2 color scales using the color palettes generated by qualitative_hcl.

Usage 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")

h1 Beginning hue value. h2 Ending hue value. alpha Numeric vector of values in the range [0,1] for alpha transparency channel (0 means transparent and 1 means opaque). rev If TRUE, reverses the order of the colors in the color scale. 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 1:nmax. aesthetics The ggplot2 aesthetics to which this scale should be applied. ... common discrete scale parameters: name, breaks, labels, na.value, limits and guide. See discrete_scale for more details.

Examples 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")

scale_colour_discrete_sequential HCL-Based Discrete Sequential Color Scales for ggplot2

Description Discrete ggplot2 color scales using the color palettes generated by sequential_hcl.

Usage scale_colour_discrete_sequential( palette = NULL, c1 = NULL, c2 = NULL, cmax = NULL, scale_colour_discrete_sequential 71

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

Arguments palette The name of the palette to be used. Run hcl_palettes(type = "sequential") for available options. 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 NA, generates a single-hue scale. 72 scale_colour_discrete_sequential

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 [0,1] for alpha transparency channel (0 means transparent and 1 means opaque). rev If TRUE (default), reverses the order of the colors in the color scale (compared to sequential_hcl). 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 1:nmax. aesthetics The ggplot2 aesthetics to which this scale should be applied. ... common discrete scale parameters: name, breaks, labels, na.value, limits and guide. See discrete_scale for more details.

Details

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.

Examples

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() simulate_cvd 73

simulate_cvd Simulate Color Vision Deﬁciency

Description

Transformation of R colors by simulating color vision deﬁciencies, based on a CVD transform matrix.

Usage simulate_cvd(col, cvd_transform)

deutan(col, severity = 1)

protan(col, severity = 1)

tritan(col, severity = 1)

interpolate_cvd_transform(cvd, severity = 1)

Arguments

col character. A color or vector of colors, e.g., "#FFA801" or "blue". Input col can also be a matrix with three rows containing R/G/B (0-255) values, see details. cvd_transform numeric 3x3 matrix, specifying the color vision deﬁciency transform matrix. severity numeric. Severity of the color vision defect, a number between 0 and 1. cvd list of cvd transformation matrices. See cvd for available options.

Details

Using the physiologically-based model for simulating color vision deﬁciency (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]. Instead of an (s)RGB color vector a matrix of the same size as the input col with the corresponding simulated Red-Green-Blue values will be returned. This can be handy to avoid too many conversions. 74 specplot

See Also

RGB, HSV, XYZ, LAB, polarLAB, LUV, polarLUV.

Examples

# Create a random set of colors set.seed(1) sRGB(R = runif(20), G = runif(20), B = runif(20)) 78 swatchplot

swatchplot Palette Swatch Plot

Description Visualization of color palettes in columns of color swatches.

Usage swatchplot( x, ..., nrow = 20, border = NULL, sborder = NULL, off = NULL, mar = NULL, line = NULL, cex = NULL, font = 1:2, cvd = FALSE )

Arguments 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 "lightgray" for up to 9 colors, "transparent" otherwise. sborder color for border of the entire palette swatch. By default "lightgray" if border is "transparent" and "lightgray" otherwise (if off = 0). 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 0.3 for up to 5 colors and 0 otherwise, and the vertical offset is 0.1. 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 desaturate, deutan, protan, tritan. USSouthPolygon 79

Details The function swatchplot is a convenience function for displaying collections of palettes that can be speciﬁed as lists or matrices of character color speciﬁcations. 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.

Value swatchplot invisibly returns a matrix with colors and annotations.

Examples

## 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") )

USSouthPolygon Polygon for County Map of US South States: Alabama, Georgia, and South Carolina 80 whitepoint

Description County polygons for Alabama, Georgia, and South Carolina plus an artiﬁcal variable used for col- oring.

Usage data("USSouthPolygon")

Format A data frame with coordinates of the vertices of the county polygons (x, y) and an artiﬁcial variable z constructed for illustrating colored maps.

Source Polygon data taken from maps package of Becker, Wilks, Brownrigg, and Minka (2012). Version 2.2-6. https://CRAN.R-project.org/package=maps

Examples ## 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)])

whitepoint Access or Modify the Whitepoint

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

Usage whitepoint(white, ...)

Arguments white, ... Either missing (to query the whitepoint) or NULL or a speciﬁcation of the XYZ coordinates of the whitepoint (to set the whitepoint, see examples). NULL corresponds to CIE D65 with XYZ coordinates 95.047, 100.000, 108.883. writehex 81

Value whitepoint returns an XYZ color object for the whitepoint (invisibly in case a new whitepoint was set).