1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/specplot.R
3\name{specplot}
4\alias{specplot}
5\title{Color Spectrum Plot}
6\usage{
7specplot(
8  x,
9  y = NULL,
10  rgb = FALSE,
11  hcl = TRUE,
12  fix = TRUE,
13  cex = 1,
14  type = "l",
15  lwd = 2 * cex,
16  lty = 1,
17  pch = NULL,
18  mar = NULL,
19  oma = NULL,
20  main = NULL,
21  legend = TRUE,
22  palette = TRUE,
23  plot = TRUE,
24  ...
25)
26}
27\arguments{
28\item{x}{character vector containing color hex codes.}
29
30\item{y}{optional second character vector containing further color hex codes,
31to be used for comparing two palettes (\code{x} vs. \code{y}).}
32
33\item{rgb}{logical or color specification. Should the RGB spectrum be
34visualized? Can also be a vector of three colors for the legend of R/G/B coordinates.}
35
36\item{hcl}{logical or color specification. Should the HCL spectrum be
37visualized? Can also be a vector of three colors for the legend of H/C/L coordinates.}
38
39\item{fix}{logical. Should the hues be fixed to be on a smooth(er) curve?
40For details see below.}
41
42\item{cex}{numeric. Character extension for figure axes and labels.}
43
44\item{type, lwd, lty, pch}{plotting parameters passed to
45\code{\link[graphics]{lines}} for drawing the RGB and HCL coordinates,
46respectively. Can be vectors of length 3.}
47
48\item{mar, oma}{numeric or logical. Either numeric vectors of length 4 giving
49the (outer) margins or a logical indicating whether \code{mar}/\code{oma}
50should be set.}
51
52\item{main}{character. Main title of the plot.}
53
54\item{legend}{logical. Should legends for the coordinates be plotted?}
55
56\item{palette}{logical. Should the given palette \code{x} be plotted?}
57
58\item{plot}{logical. Should the RGB and/or HCL coordinates be plotted?}
59
60\item{\dots}{currently not used.}
61}
62\value{
63\code{specplot} invisibly returns a list with components
64\item{HCL}{a matrix of HCL coordinates,}
65\item{RGB}{a matrix of sRGB coordinates,}
66\item{hex}{original color palette \code{x}.}
67}
68\description{
69Visualization of color palettes (given as hex codes) in HCL and/or RGB
70coordinates.
71}
72\details{
73The function \code{specplot} transforms a given color palette in hex codes
74into their HCL (\code{\link[colorspace]{polarLUV}}) and/or RGB
75(\code{\link[colorspace]{sRGB}}) coordinates. As the hues for low-chroma
76colors are not (or poorly) identified, by default a smoothing is applied to
77the hues (\code{fix = TRUE}). Also, to avoid jumps from 0 to 360 or vice
78versa, the hue coordinates are shifted suitably.
79
80By default (\code{plot = TRUE}), the resulting HCL and optionally RGB coordinates are
81visualized by simple line plots along with the color palette \code{x}
82itself. The x-axis simply gives the ordering of the colors in the palette
83The y-axis depicts the following information: (1) Hue is drawn in red and
84coordinates are indicated on the axis on the right with range [0, 360] or
85(if necessary) [-360, 360]. (2) Chroma is drawn in green with coordinates on
86the left axis. The range [0, 100] is used unless the palette necessitates
87higher chroma values. (3) Luminance is drawn in blue with coordinates on the
88left axis in the range [0, 100]. Luminance (and hence also chroma) is on
89the left axis because it is arguably most important for understanding the
90type of palette (qualitative vs. sequential vs. diverging). To facilitate
91reading the legend the reversed order Luminance / Chroma / Hue is used so that
92the legend labels are closer to the axis they pertain to.
93
94For comparing two palettes, \code{specplot(x, y)} can be used which adds
95lines (dashed, by default) corresponding to the \code{y} palette HCL/RGB
96coordinates in the display.
97}
98\examples{
99## spectrum of the (in)famous RGB rainbow palette (in both RGB and HCL)
100specplot(rainbow(100), rgb = TRUE)
101
102## spectrum of HCL-based palettes: qualitative/sequential/diverging
103specplot(qualitative_hcl(100, "Set 2"))
104specplot(sequential_hcl(100, "Blues 2"))
105specplot(diverging_hcl(100, "Blue-Red"))
106
107## return computed RGB and HCL coordinates
108res <- specplot(rainbow(10), plot = FALSE)
109print(res)
110}
111\references{
112Zeileis A, Hornik K, Murrell P (2009).  Escaping RGBland:
113Selecting Colors for Statistical Graphics.  \emph{Computational Statistics &
114Data Analysis}, \bold{53}, 3259--3270.
115\doi{10.1016/j.csda.2008.11.033}
116Preprint available from
117\url{https://www.zeileis.org/papers/Zeileis+Hornik+Murrell-2009.pdf}.
118
119Stauffer R, Mayr GJ, Dabernig M, Zeileis A (2015).  Somewhere over the
120Rainbow: How to Make Effective Use of Colors in Meteorological
121Visualizations.  \emph{Bulletin of the American Meteorological Society},
122\bold{96}(2), 203--216.
123\doi{10.1175/BAMS-D-13-00155.1}
124
125Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020).
126\dQuote{colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.}
127\emph{Journal of Statistical Software}, \bold{96}(1), 1--49. \doi{10.18637/jss.v096.i01}
128}
129\seealso{
130\code{\link{hcl_palettes}}, \code{\link{hclplot}}
131}
132\author{
133Reto Stauffer, Achim Zeileis
134}
135\keyword{hplot}
136