### Authors

Jason C. Fisher, Reto Stauffer, Achim Zeileis

## Graphical User Interface for Choosing HCL Color Palettes

### Description

A graphical user interface (GUI) for viewing, manipulating, and choosing HCL color palettes.

### Details

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

### Value

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.

## HCL Color Palettes

### Description

Qualitative, sequential (single-hue and multi-hue), and diverging color palettes based on the HCL (hue-chroma-luminance) color model.

### Details

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.

### Value

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

## Color Spectrum Plot

### Description

Visualization of color palettes (given as hex codes) in HCL and/or RGB coordinates.

### Details

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.

### Value

`specplot` invisibly returns a list with components

`HCL` | a matrix of HCL coordinates,
`RGB` | a matrix of sRGB coordinates,
`hex` | original color palette `x`.

## Palette Plot in HCL Space

### Description

Visualization of color palettes in HCL space projections.

### 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`.

### References

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