1% File src/library/grDevices/man/palette.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2019 R Core Team
4% Distributed under GPL 2 or later
5
6\name{palette}
7\alias{palette}
8\alias{palette.pals}
9\alias{palette.colors}
10\title{Set or View the Graphics Palette}
11\usage{
12palette(value)
13palette.pals()
14palette.colors(n = NULL, palette = "Okabe-Ito", alpha, recycle = FALSE)
15}
16\arguments{
17  \item{value}{an optional character vector specifying a new palette
18    (see Details).}
19  \item{n}{the number of colors to select from a palette.  The default
20    \code{\link{NULL}} selects all colors of the given palette.}
21  \item{palette}{a valid palette name (one of \code{palette.pals()}).
22    The name is matched to the list of available palettes, ignoring
23    upper vs. lower case, spaces, dashes, etc. in the matching.}
24  \item{alpha}{an alpha-transparency level in the range [0,1]
25    (0 means transparent and 1 means opaque).}
26  \item{recycle}{logical indicating what happens in case \code{n >
27      length(palette(.))}.  By default (\code{recycle = FALSE}), the
28    result is as for \code{n = NULL}, but with a warning.}
29}
30\description{
31  View or manipulate the color palette which is used when \code{col=}
32  has a numeric index and supporting functions.
33}
34\details{
35  The \code{palette()} function gets or sets the current palette,
36  the \code{palette.pals()} function  lists the available predefined
37  palettes, and the \code{palette.colors()} function
38  selects colors from the predefined palettes.
39
40  The color palette and referring to colors by number (see
41  e.g.\sspace{}\code{\link{par}}) was provided for compatibility with S.
42  \R extends and improves on the available set of palettes.
43
44  If \code{value} has length 1, it is taken to be the name of a built-in
45  color palette.  The available palette names are returned by
46  \code{palette.pals()}.  It is also possible to specify \code{"default"}.
47
48  If \code{value} has length greater than 1 it is assumed to contain a
49  description of the colors which are to make up the new palette.
50  The maximum size for a palette is 1024
51  entries.
52
53  If \code{value} is omitted, no change is made to the current palette.
54
55  There is only one palette setting for all devices in an \R session.  If
56  the palette is changed, the new palette applies to all subsequent
57  plotting.
58
59  The current palette also applies to re-plotting (for example if an
60  on-screen device is resized or \code{\link{dev.copy}} or
61  \code{\link{replayPlot}} is used).  The palette is recorded on the
62  displaylist at the start of each page and when it is changed.
63}
64
65\value{
66  \code{palette()} returns a character vector giving the colors from the
67  palette which \emph{was} in effect.
68  This is \code{\link{invisible}} unless the argument is omitted.
69
70  \code{palette.pals()} returns a character vector giving the names
71  of predefined palettes.
72
73  \code{palette.colors()} returns a vector of R colors.
74}
75\seealso{
76  \code{\link{colors}} for the vector of built-in named colors;
77  \code{\link{hsv}}, \code{\link{gray}},
78  \code{\link{hcl.colors}}, \dots to construct colors.
79
80  \code{\link{adjustcolor}}, e.g., for tweaking existing palettes;
81  \code{\link{colorRamp}} to interpolate colors, making custom palettes;
82  \code{\link{col2rgb}} for translating colors to RGB 3-vectors.
83}
84\examples{
85require(graphics)
86
87palette()               # obtain the current palette
88palette("R3");palette() # old default palette
89palette("ggplot2")      # ggplot2-style palette
90palette()
91
92palette(hcl.colors(8, "viridis"))
93
94(palette(gray(seq(0,.9,length.out = 25)))) # gray scales; print old palette
95matplot(outer(1:100, 1:30), type = "l", lty = 1,lwd = 2, col = 1:30,
96        main = "Gray Scales Palette",
97        sub = "palette(gray(seq(0, .9, len=25)))")
98palette("default")      # reset back to the default
99
100## on a device where alpha transparency is supported,
101##  use 'alpha = 0.3' transparency with the default palette :
102mycols <- adjustcolor(palette(), alpha.f = 0.3)
103opal <- palette(mycols)
104x <- rnorm(1000); xy <- cbind(x, 3*x + rnorm(1000))
105plot (xy, lwd = 2,
106       main = "Alpha-Transparency Palette\n alpha = 0.3")
107xy[,1] <- -xy[,1]
108points(xy, col = 8, pch = 16, cex = 1.5)
109palette("default")
110
111## List available built-in palettes
112palette.pals()
113
114## Demonstrate the colors 1:8 in different palettes using a custom matplot()
115sinplot <- function(main=NULL) {
116    x <- outer(
117	seq(-pi, pi, length.out = 50),
118	seq(0, pi, length.out = 8),
119	function(x, y) sin(x - y)
120    )
121    matplot(x, type = "l", lwd = 4, lty = 1, col = 1:8, ylab = "", main=main)
122}
123sinplot("default palette")
124
125palette("R3");        sinplot("R3")
126palette("Okabe-Ito"); sinplot("Okabe-Ito")
127palette("Tableau")  ; sinplot("Tableau")
128palette("default") # reset
129
130## color swatches for palette.colors()
131palette.swatch <- function(palette = palette.pals(), n = 8, nrow = 8,
132                           border = "black", cex = 1, ...)
133{
134     cols <- sapply(palette, palette.colors, n = n, recycle = TRUE)
135     ncol <- ncol(cols)
136     nswatch <- min(ncol, nrow)
137     op <- par(mar = rep(0.1, 4),
138               mfrow = c(1, min(5, ceiling(ncol/nrow))),
139     	       cex = cex, ...)
140     on.exit(par(op))
141     while (length(palette)) {
142 	subset <- seq_len(min(nrow, ncol(cols)))
143 	plot.new()
144 	plot.window(c(0, n), c(0.25, nrow + 0.25))
145 	y <- rev(subset)
146 	text(0, y + 0.1, palette[subset], adj = c(0, 0))
147 	y <- rep(y, each = n)
148 	rect(rep(0:(n-1), n), y, rep(1:n, n), y - 0.5,
149 	     col = cols[, subset], border = border)
150 	palette <- palette[-subset]
151 	cols    <- cols [, -subset, drop = FALSE]
152     }
153}
154
155palette.swatch()
156
157palette.swatch(n = 26) # show full "Alphabet"; recycle most others
158}
159\keyword{color}
160\keyword{sysdata}
161