getColors: Hue, Chroma, Luminance (HCL) Color Wheel or Specified Colors

Description

Generates character strings of HCL colors for qualitative and sequential color scales and displays colors, both those generated and also arbitrary colors manually specified. To avoid bias in the comparison of differently colored regions of a visualization, generates HCL colors by default with fixed values of chroma (saturation) and luminance (brightness) for a range of hues, by default ordered so that adjacent colors are as separated as possible. Also generates a sequence of HCL colors according to any chosen hue value in which chroma and luminance can be varied by implicit calls to Zeileis's et al. sequential_hcl function from Ihaka's et al. colorspace package, and also with pre-defined values such as "blues". Also processes any arbitrarily specified set of colors that are specified, or generated from a custom range according to a beginning and ending specified color.

In terms of workflow, use the function by itself to select a set of colors from the resulting color rectangle/wheel. The function outputs the colors so that the function call can serve as an argument to parameters in other functions that require a sequence of one or more colors as input, in which case the visualization of the color wheel or rectangle is not generated. So after the colors are selected, pass to an argument for a visualization function such as for the fill parameter.

Usage

getColors(clr=NULL, end.clr=NULL,
         n=12, h=0, h2=NULL, c=NULL, l=NULL, trans=0,
         in.order=FALSE, fixup=TRUE,
         shape=c("rectangle", "wheel"), radius=0.9, border="lightgray",
         main=NULL, labels=NULL, labels.cex=0.8, lty="solid",
         output=NULL, quiet=getOption("quiet"), …)

Arguments

clr

Optional specified colors to plot. If a set of specified colors, then the following parameters are not relevant. Can also be pre-defined color codes that trigger a sequence of colors from light to dark, such as "blues".

end.clr

If specified, then generate a color continuum that begins at clr and ends at end.clr.

Number of colors to display.

Beginning HCL hue, 0 to 360.

Ending HCL hue, 0 to 360. Defaults to a value close to 360. Requires in.order to be FALSE.

Value of HCL chroma (saturation). Respective default values for qualitative, sequential, and divergent scales are 65, c(35,75), and 50.

Value of HCL luminance (brightness). Respective default values for qualitative, sequential, and divergent scales are 55, c(80,25), and c(40,70).

trans

Transparency factor of the area of each slice from 0, no transparency to 1, full transparency.

in.order

If TRUE, orders the colors in order of their HCL hue values. Otherwise maximizes the difference between adjacent colors hues to prepare for inclusion in visualizations with qualitative, discrete color scales.

fixup

R parameter name. If TRUE, then HCL values outside of the displayable RGB color space are transformed to fit into that space so as to display.

shape

Default is a "rectangle", or specify a "wheel".

radius

Size of wheel. Not applicable to the rectangular shape.

border

Color of the borders of each slice. Set to "off" or "transparent" to turn off.

main

Title.

labels

If TRUE, then displayed. For HCL qualitative scale, default is TRUE, otherwise FALSE

labels.cex

Character expansion factor of labels relative to 1.

lty

Line type of the border.

output

Default to evaluate if function call at top level, so produce text and graphics output, or embedded in another function call, so do not produce that output. If set to "on", then do output. If set to "off" then do not do output.

quiet

If set to TRUE, no list of colors. Can change system default with style function.

…

Other parameter values.

Value

Colors are invisibly returned as a character string vector.

Details

I. HCL COLORS Generate a palette of colors according to the parameter clr in the form of a character string vector of their names, and also as a color wheel if not called from another function. The default value (for all but grayscale or white color themes) of clr is "colors", which generates a qualitative palette of the specified number, n, of discrete HCL colors at the same chroma and luminance, respective default values of 65 and 55. With constant chroma and luminance the HCL color space provides a palette of colors with the same gray-scale intensities if desaturated. That means no brightness bias for viewing different colors that represent different areas, such as in a bar chart of two variables, or a pie chart. The primary qualification is that the HCL color space is not in a one-to-one correspondence with the RGB color space of computer monitors, so some HCL colors are approximated (with the default setting of the fixup parameter set to TRUE).

For "colors", the default, the hue values and associated colors are expressed as HEX and RGB values. The first 12 generated discrete colors are blue (240), brown (60), green (120), red (0), purple (275), turquoise (180), rust (30), olive (90), aqua (210), mulberry (330), emerald (150), and violet (300).

To have the generated colors be in the sequential order of hues, set in.order to FALSE. For about up to five or six colors adjacent values are still reasonably well distinguished even if in sequential order of hue number in the hcl space.

II. COLOR SEQUENCE A second possibility is to generate a sequence of colors according to the value of n from a given start color to an ending color. To specify a custom range, set clr as the value of the first color, and then end.clr as the value of the last color in the color range. The colors in the sequence may or may not be of the same hue.

Or, access implicit calls Zeileis (2009) sequential_hcl and diverge_hcl functions from the colorspace package to access pre-defined color ranges including "grays", which is the default if the color theme is "gray" or "white". Other predefined sequences are shown in the following table. Also can invoke the standard R color ranges of "heat", "terrain", and "rainbow". Can specify any value of hue with h. Can also provide custom values of chroma (c) and luminance (l), with either one a range of values defined as a vector of two values. Default values are c=100 and l=c(75,35). That is, the color sequence is generated according to the given hue, h, with a chroma of 100 and luminance varying from 75 to the darker 45.

The predefined sequences consist of the following hues and color names, defined in 30 degree increments around the HCL color wheel.

colors	param	value
-----------	-----	-----
`"reds"`	h	0
`"rusts"`	h	30
`"yellows"`	h	60
`"olives"`	h	90
`"greens"`	h	120
`"emeralds"`	h	150
`"turquoises"`	h	180
`"aquas"`	h	210
`"blues"`	h	240
`"purples"`	h	270
`"violets"`	h	300
`"magentas"`	h	330
`"grays"`	c	0
-----------	-----	-----

The predefined color name can be provided as the first argument of the function call, that is, the value of clr, or the corresponding value of h (or c for gray scale) can be specified. The specifications are equivalent. To specify a divergent color scale, provide both the value of clr as the beginning value and the value of end.clr as the last value, such that both values are one of the pre-specified color ranges. In either situation, of sequential or divergent color scales, custom values of c and l can be provided.

III. SPECIFIED COLORS The third possibility is to generate a color wheel from a specified set of color values. Set the value of clr according to the vector of these values. Specify the values with R color names (see the lessR function showColors), RGB values according to the rgb function or from related R color space functions such as hcl, or as hexadecimal codes.

FUNCTION USAGE Use the function on its own, in which case the color rectangle/wheel visualization is generated as are the color values. The vector of color values may be saved in its own R object as the output of the function call. Or, use the function to set colors for other parameter values in other function calls. See the examples.

Examples

Run this code

# NOT RUN {
# HCL color wheels/rectangles
#----------------------------
# set in.order to TRUE for hues ordered by their number

# color spectrum of 12 hcl colors ordered by hue from 0
#   by intervals of 360/12 = 30 degrees
getColors(in.order=TRUE)

# pastel hcl colors, set luminance to 85 from default of 55
getColors(in.order=TRUE, l=85)

# color wheel of 36 ordered hues around the wheel
getColors(n=36, shape="wheel", border="off", in.order=TRUE)

# ggplot qualitative colors, here for 3 colors generated
#   in order of their hue numbers across the color wheel
#   starting at a hue of 15 degrees and luminance of 60
getColors(h=15, n=3, l=60, in.order=TRUE)


# HCL Qualitative Scale
# ---------------------
# default pre-defined 12 hcl colors that were manually reordered
#   so that adjacent colors achieve maximum separation
getColors()

# deep rich colors for HCL qualitative scale
getColors(c=90, l=45)


# HCL Sequential Scales
# ---------------------
# generate hcl blue sequence with c=65 and vary l
getColors("blues", labels=FALSE)

# generate yellow hcl sequence with varying chroma
getColors("yellows", c=c(20,90), l=65)

# generate custom hue color sequence close to colorbrewer Blues
# library(RColorBrewer)
# getColors(brewer.pal(6,"Blues"))
# compare, vary both l and c
getColors(h=230, n=6, l=c(96,30), c=c(5,80))

# a standard R color sequence
getColors("heat")


# HCL Divergent Scales
# --------------------
# seven colors from rust to blue
getColors("rusts", "blues", n=7)

# add a custom value of chroma, c, to make less saturated
getColors("rusts", "blues", n=7, c=45)


# Manual Specification of Colors
# ------------------------------
# individually specified colors
getColors(c("black", "blue", "red"))

# custom sequential range of colors
getColors(clr="aliceblue", end.clr="blue")


# Plots
# -----
mydata <- rd("Employee", in.lessR=TRUE)

# default quantitative scale
bc(Dept, fill=getColors())
# or with implicit call to getColors
bc(Dept, fill="colors")
# or an implicit call with the blues
bc(Dept, fill="blues")

# even though we have a bar graph, also want the
#  graph of the colors as well as the text listing of the colors
bc(Dept, fill=getColors("blues", output="on"))

# custom hue with different chroma levels (saturations)
BarChart(Dept, fill=getColors(h=230, c=c(20,60), l=65, n=5))

# custom hue with different luminance levels (brightness)
# if explicitly calling getColors need to also specify n
Histogram(Salary, fill=getColors(h=230, c=65, l=c(90,30), n=10))

# use the default qualitative viridis color scale
# library(viridis)
# bc(Dept, fill=getColors(viridis_pal()(5)))
# }