% File src/library/grDevices/man/palettes.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2019 R Core Team
% Distributed under GPL 2 or later

\name{Palettes}
\alias{rainbow}
\alias{heat.colors}
\alias{terrain.colors}
\alias{topo.colors}
\alias{cm.colors}
\alias{hcl.colors}
\alias{hcl.pals}
\title{Color Palettes}
\encoding{UTF-8}
\description{
  Create a vector of \code{n} contiguous colors.
}
\usage{
hcl.colors(n, palette = "viridis", alpha = NULL, rev = FALSE, fixup = TRUE)
hcl.pals(type = NULL)

rainbow(n, s = 1, v = 1, start = 0, end = max(1, n - 1)/n,
        alpha = 1, rev = FALSE)
heat.colors(n, alpha = 1, rev = FALSE)
terrain.colors(n, alpha = 1, rev = FALSE)
topo.colors(n, alpha = 1, rev = FALSE)
cm.colors(n, alpha = 1, rev = FALSE)
}
\arguments{
  \item{n}{the number of colors (\eqn{\ge 1}) to be in the
    palette.}
  \item{palette}{the name of the palette to generate colors from.
    The name is matched to the list of available palettes (listed in the
    details), ignoring upper vs. lower case, spaces, dashes, etc. in the
    matching.}
  \item{alpha}{the alpha transparency, a number in [0,1], see argument
    \code{alpha} in \code{\link{hsv}} and \code{\link{hcl}}, respectively.}
  \item{rev}{logical indicating whether the ordering of the colors should
    be reversed.}
  \item{fixup}{logical indicating whether the resulting color should be
    corrected to RGB coordinates in [0,1], see \code{\link{hcl}}.}
  \item{type}{the type of palettes to list: \code{"qualitative"},
    \code{"sequential"}, \code{"diverging"}, or \code{"divergingx"}.
    \code{NULL} lists all palettes.}
  \item{s, v}{the \sQuote{saturation} and \sQuote{value} to be used
    to complete the HSV color descriptions.}
  \item{start}{the (corrected) hue in [0,1] at which the rainbow
    begins.}
  \item{end}{the (corrected) hue in [0,1] at which the rainbow ends.}
}
\details{
All of these functions (except the helper function \code{hcl.pals}) create a
vector of \code{n} contiguous colors, either based on the HSV color space
(rainbow, heat, terrain, topography, and cyan-magenta colors) or the
perceptually-based HCL color space.

HSV (hue-saturation-value) is a simple transformation of the RGB
(red-green-blue) space which was therefore a convenient choice for color
palettes in many software systems (see also \code{\link{hsv}}). However, HSV
colors capture the perceptual properties hue, colorfulness/saturation/chroma,
and lightness/brightness/luminance/value only poorly and consequently
the corresponding palettes are typically not a good choice for statistical
graphics and data visualization.

In contrast, HCL (hue-chroma-luminance) colors are much more suitable for
capturing human color perception (see also \code{\link{hcl}} and better color
palettes can be derived based on HCL coordinates.
Conceptually, three types of palettes are often distinguished:
\itemize{
  \item Qualitative: For coding categorical information, i.e., where no
    particular ordering of categories is available and every color should
    receive the same perceptual weight.
  \item Sequential: For coding ordered/numeric information, i.e., where colors
    go from high to low (or vice versa).
  \item Diverging: Designed for coding numeric information around a central
    neutral value, i.e., where colors diverge from neutral to two extremes.
}
The \code{hcl.colors} function provides a basic and lean implementation of
the pre-specified palettes in the \pkg{colorspace} package. In addition to the
types above, the functions distinguish \dQuote{diverging} palettes where the two
arms are restricted to be rather balanced as opposed to flexible
\dQuote{divergingx} palettes that combine two sequential palettes without any
restrictions. The latter group also includes the cividis palette as it is based
on two different hues (blue and yellow) but it is actually a sequential palette
(going from dark to light).

The names of all available HCL palettes can be queried with the \code{hcl.pals}
function and they are also visualized by color swatches in the examples. Many of
the palettes closely approximate palettes of the same name from various other
packages (including \pkg{RColorBrewer}, \pkg{rcartocolor}, \pkg{viridis},
\pkg{scico}, among others). 

The default HCL palette is the widely used viridis palette which is a sequential
palette with relatively high chroma throughout so that it also works reasonably
well as a qualitative palette. However, while viridis is a rather robust default
palette, more suitable HCL palettes are available for most visualizations.

Note that the \code{rainbow} function implements the (in-)famous rainbow (or
jet) color palette that was used very frequently in many software packages but
has been widely criticized for its many perceptual problems.
It is specified by a \code{start} and \code{end} hue with red = 0,
yellow = \eqn{\frac 1 6}{1/6}, green = \eqn{\frac 2 6}{2/6},
cyan = \eqn{\frac 3 6}{3/6}, blue = \eqn{\frac 4 6}{4/6}, and
magenta = \eqn{\frac 5 6}{5/6}. However, these are very flashy and unbalanced
with respect to both chroma and luminance which can lead to various optical
illusions. Also, the hues that are equispaced in RGB space tend to cluster at
the red, green, and blue primaries. Therefore, it is recommended to use a
suitable palette from \code{hcl.colors} instead of
\code{rainbow}.
}
\value{A character vector \code{cv} containing either palette names (for
  \code{hcl.pals}) or \code{n} hex color codes (for all other functions).
  The latter can be used either to create a user-defined color palette for
  subsequent graphics by \code{\link{palette}(cv)}, a \code{col =} specification
  in graphics functions or in \code{par}.
}
\references{
  Wikipedia (2019).
  HCL color space -- Wikipedia, The Free Encyclopedia.
  \url{https://en.wikipedia.org/w/index.php?title=HCL_color_space&oldid=883465135}.
  Accessed March 26, 2019.

  Zeileis, A., Fisher, J. C., Hornik, K., Ihaka, R., McWhite, C. D., Murrell, P., Stauffer, R. and Wilke, C. O. (2019).
  \dQuote{ccolorspace: A toolbox for manipulating and assessing colors and palettes.}
  arXiv:1903.06490, arXiv.org E-Print Archive.
  \url{http://arxiv.org/abs/1903.06490}.

  Ihaka, R. (2003).
  \dQuote{Colour for presentation graphics.}
  Proceedings of the 3rd International Workshop on Distributed Statistical Computing (DSC 2003),
  March 20-22, 2003, Technische Universität Wien, Vienna, Austria.
  \url{http://www.ci.tuwien.ac.at/Conferences/DSC-2003}.

  Zeileis, A., Hornik, K. and Murrell, P. (2009).
  Escaping RGBland: Selecting colors for statistical graphics.
  \emph{Computational Statistics & Data Analysis}, \bold{53}, 3259--3270.
  \doi{10.1016/j.csda.2008.11.033}.
}
\seealso{
  \code{\link{colors}}, \code{\link{palette}},
  \code{\link{gray.colors}},
  \code{\link{hsv}},
  \code{\link{hcl}}, \code{\link{rgb}}, \code{\link{gray}} and
  \code{\link{col2rgb}} for translating to RGB numbers.
}
\examples{
require("graphics")

# color wheels in RGB/HSV and HCL space
par(mfrow = c(2, 2))
pie(rep(1, 12), col = rainbow(12), main = "RGB/HSV")
pie(rep(1, 12), col = hcl.colors(12, "Set 2"), main = "HCL")
par(mfrow = c(1, 1))

## color swatches for RGB/HSV palettes
demo.pal <-
  function(n, border = if (n < 32) "light gray" else NA,
           main = paste("color palettes;  n=", n),
           ch.col = c("rainbow(n, start=.7, end=.1)", "heat.colors(n)",
                      "terrain.colors(n)", "topo.colors(n)",
                      "cm.colors(n)"))
{
    nt <- length(ch.col)
    i <- 1:n; j <- n / nt; d <- j/6; dy <- 2*d
    plot(i, i+d, type = "n", yaxt = "n", ylab = "", main = main)
    for (k in 1:nt) {
        rect(i-.5, (k-1)*j+ dy, i+.4, k*j,
             col = eval(parse(text = ch.col[k])), border = border)
        text(2*j,  k * j + dy/4, ch.col[k])
    }
}
demo.pal(16)

## color swatches for HCL palettes
hcl.swatch <- function(type = NULL, n = 5, nrow = 11,
  border = if (n < 15) "black" else NA) {
    palette <- hcl.pals(type)
    cols <- sapply(palette, hcl.colors, n = n)
    ncol <- ncol(cols)
    nswatch <- min(ncol, nrow)

    par(mar = rep(0.1, 4),
        mfrow = c(1, min(5, ncol \%/\% nrow + 1)),
        pin = c(1, 0.5 * nswatch),
        cex = 0.7)

    while (length(palette)) {
        subset <- 1:min(nrow, ncol(cols))
        plot.new()
        plot.window(c(0, n), c(0, nrow + 1))
        text(0, rev(subset) + 0.1, palette[subset], adj = c(0, 0))
        y <- rep(subset, each = n)
        rect(rep(0:(n-1), n), rev(y), rep(1:n, n), rev(y) - 0.5,
             col = cols[, subset], border = border)
        palette <- palette[-subset]
        cols <- cols[, -subset]
    }

    par(mfrow = c(1, 1), mar = c(5.1, 4.1, 4.1, 2.1), cex = 1)
}
hcl.swatch()
hcl.swatch("qualitative")
hcl.swatch("sequential")
hcl.swatch("diverging")
hcl.swatch("divergingx")

## heat maps with sequential HCL palette (purple)
image(volcano, col = hcl.colors(11, "purples", rev = TRUE))
filled.contour(volcano, nlevels = 10,
               color.palette = function(n, ...)
                   hcl.colors(n, "purples", rev = TRUE, ...))

## list available HCL color palettes
hcl.pals("qualitative")
hcl.pals("sequential")
hcl.pals("diverging")
hcl.pals("divergingx")
}
\keyword{color}
\keyword{dplot}