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