---
title: "Customize"
author: "David Gerbing"
output: 
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{5. Customize: Colors}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---


```{r include=FALSE}
knitr::opts_chunk$set(fig.width=6, fig.height=3.5)
```

```{r include=FALSE}
suppressPackageStartupMessages(library("lessR"))
```
Use the `style()` function to turn off text output for the following function calls.

```{r}
style(quiet=TRUE)
```


## Color Palettes

Many color models exist that describe colors in three dimensions. One of the more useful models defines the `HCL` color space. The colors are generated with the base R `hcl()` function, which has three parameters to specify a color: `h` for hue, `c` for chroma (saturation), and `l` for luminescence (brightness). 


### Qualitative Scales

The default output of `getColors()` is a color spectrum of 12 `hcl` colors presented in the order in which they are assigned to discrete levels of a categorical variable. For clarity in the following function call, the default value of the `pal` or _palette_ parameter is explicitly set to its name, `"hues"`.


```{r}
getColors("hues")
```

```{r echo=FALSE}
getColors("hues", output=TRUE)
```


To maintain equal brightness/intensity across the colors, all default colors generated by `getColors()` are based on chroma set at `c=65` and luminescence set at `l=60`.  

A color's hue is based on integers around the color wheel from 0 to 360, starting at 0 for red. Use `getColors()` to display an `hcl` color wheel of 36 ordered hues around the wheel. The `hcl` color space numbers the hues from 0 to 360, with 0 arbitrarily indicating red.

```{r, fig.height=6, fig.width=6}
getColors(n=36, shape="wheel", border="off")
```

```{r echo=FALSE, fig.height=6, fig.width=6}
getColors(n=36, shape="wheel", border="off", output=TRUE)
```

Obtain deep, rich colors for an HCL qualitative palette by lowering chroma and luminance from their default values.

```{r}
getColors(c=50, l=30)
```

```{r echo=FALSE}
getColors(c=50, l=30, output=TRUE)
```

The primary purpose of the color palettes is their application to data visualizations. Here, illustrate the deep, rich colors applied to a bar chart with the `fill` parameter that indicates the color of the bar interiors. Turn off text output with the `quiet` parameter set to `TRUE`.

```{r}
d <- Read("Employee", quiet=TRUE)
BarChart(Dept, fill=getColors(c=50, l=30), quiet=TRUE)
```

Or, display pastels by setting chroma and luminescence high. Because the bars are so light colored, change the color of the displayed percentage on each bar with parameter `values_color` to a dark gray specified by `"gray20"` (on the gray scale, `"gray0"` is black and `"gray100"` is white).

In this example, generate the color palette separately from the call to `BarChart()`. When doing so, specify the number of colors to generate with the parameter `n`. When `getColors()` is called apart from `BarChart()`, the number of colors must be separately specified.

```{r}
myColors <- getColors(c=90, l=80, n=5)
BarChart(Dept, fill=myColors, values_color="gray20", quiet=TRUE)
```


### Sequential Scales

__lessR__ provides pre-defined sequential color scales across the range of hues around the color wheel in 30 degree increments: `"reds"`, `"rusts"`, `"browns"`, `"olives"`, `"greens"`, `"emeralds"`, `"turqoises"`, `"aquas"`, `"blues"`, `"purples"`, `"biolets"`, `"magentas"`, and `"grays"`.


To view the scales, use the function `showPalettes()`. Here it is commented out by the `#` sign in the first column because it writes the output to a pdf.

```{r}
#showPalettes()
```  

Generate a palette of 12 blue hues for the default value of parameter `n` set to 12..

```{r}
getColors("blues")
```

```{r echo=FALSE}
getColors("blues", output=TRUE)
```

Generate an `hcl` blue sequence with `c=60` and vary `l`.

```{r}
getColors("blues", c=60, l=c(30,80))
```

```{r echo=FALSE}
getColors("blues", c=60, l=c(30,80), output=TRUE)
```


Vary chroma for a yellow `hcl` sequence. To do so, specify parameter `c` as a vector, here with values that vary from 20 to 90.

```{r}
getColors("browns", c=c(20,90), l=60)
```

```{r echo=FALSE}
getColors("browns", c=c(20,90), l=60, output=TRUE)
```

Here, illustrate `getColors()` in a data visualization. Stack three time series. According to the `area_fill` parameter, use `Plot()` to fill under each curve with a version of the sequential range `"reds"` with some transparency according to parameter `trans`. The data frame _d2_ is not the default data frame _d_, so explicitly specify with the `data` parameter.

```{r, fig.width=6}
d2 <- Read("StockPrice", quiet=TRUE)
Plot(date, Price, by=Company, stack=TRUE, area_fill="reds", trans=0.4, data=d2)
```


### Divergent Scales

To create a divergent color palette, specify beginning and an ending color palettes, which provide values for the  parameters `pal` and `end_pal`, where `pal` abbreviates palette. Here, generate colors from rust to blue.

```{r}
getColors("rusts", "blues")
```

```{r echo=FALSE}
getColors("rusts", "blues", output=TRUE)
```

Add a custom value of chroma, `c`, to make more saturated than provided by the default value of chroma of 50.

```{r}
getColors("rusts", "blues", c=75)
```

```{r echo=FALSE}
getColors("rusts", "blues", c=75, output=TRUE)
```


### Other Scales

The family of color-friendly viridis scales are available: "viridis", "cividis", "magma", "inferno", and "plasma".
```{r}
getColors("viridis")
```

```{r echo=FALSE}
getColors("viridis", output=TRUE)
```

For something different, can use palettes based on many of Wes Anderson's movies: "BottleRocket1", "BottleRocket2", "Rushmore1", "Rushmore", "Royal1", "Royal2", "Zissou1", "Darjeeling1", "Darjeeling2", "Chevalier1", "FantasticFox1", "Moonrise1", "Moonrise2", "Moonrise3", "Cavalcanti1", "GrandBudapest1", "GrandBudapest2", "IsleofDogs1", and "IsleofDogs2".

```{r}
getColors("Royal1")
```

```{r echo=FALSE}
getColors("Royal1", output=TRUE)
```

To maximally differentiate colors based on hue, use the pre-defined palette "distinct".

```{r}
getColors("distinct")
```

```{r echo=FALSE}
getColors("distinct", output=TRUE)
```


### Manual Specification of Colors

Consider an item on an attitude survey that is assessed on a 7-point Likert scale with responses that range from Strongly Disagree to Neutral to Strongly Agree. The goal is to create a bar chart with different sequential color palettes for the Disagree and Agree sides of the responses, with gray for the Neutral response. First, simulate some data for the item responses. Of course, these steps are not part of the usual data analysis because you would have your data, the responses to the item of interest.

```{r}
values <- c(rep(1,2), rep(2,5), rep(3,4), rep(4,3), rep(5,6), rep(6,7), rep(7,8))
Responses <- sample(values, size=100, replace=TRUE)

LikertCats <- c("Strongly Disagree", "Disagree", "Slightly Disagree",
                "Neutral", "Slightly Agree", "Agree", "Strongly Agree")
Responses <- factor(Responses, levels=1:7, labels=LikertCats)
```

Create the two vectors, a sequential red scale for the Disagree responses and a sequential blue scale for the Agree responses. Indicate that each scale should encompass three colors with the parameter `n`. 

```{r}
red <- getColors("reds", n=3, c=c(75,35), l=c(27,63))
blue <- getColors("blues", n=3)
```

Another way to build the `fill` vector would be to examine the text output of `getColors()` for each palette and then copy and paste the displayed colors in either hexadecimal or `rgb` formats.

With the data, create a bar chart according to a vector of the seven colors.

```{r}
BarChart(Responses, fill=c(red, "gray50", blue))
```



## Visualization Themes

The `style()` function specifies broad color themes, as well as individual characteristics of a visualization. Changes based on a theme change are persistent across subsequent visualizations unless again modified.

In addition to the default theme  `"colors"`, other available themes are `"lightbronze"`, `"dodgerblue"`, `"darkred"`, `slatered`, `"gray"`, `"gold"`, `"darkgreen"`, `"blue"`, `"red"`, `"rose"`, `"slatered"`, `"green"`, `"purple"`, `"sienna"`, `"brown"`, `"orange"`, `"white"`, and `"light"`.

```{r}
d <- Read("Employee")
```


Obtain grayscale visualizations by setting the theme to `"gray"`.

```{r}
style("gray")
BarChart(Dept)
```

Here, invoke the `"darkred"` theme. With themes other than the default `"colors"` theme, the bars in a bar chart and boxes in a box charts are plotted with the same color. Do not need the text output, so set parameter `quiet` to `TRUE`.

```{r}
style("darkred")
BarChart(Dept, quiet=TRUE)
```

```{r fig.height=6}
Plot(Salary, by1=Dept, quiet=TRUE)
```


Return to the default `colors` for the `theme` parameter by either explicitly specifying, or just go with no specification, as in `style()`.

Individual characteristics of a visualization can also be specified. Here change the background color of the visualization window. The `theme` parameter can also be attached to a single call to the visualization functions such as `BarChart()`. 

```{r}
style(window_fill="aliceblue")
BarChart(Dept, theme="sienna")
```

View all modifiable individual characteristics with the `show` parameter set to `TRUE`.

```{r}
style(show=TRUE)
```

```{r echo=FALSE}
style()
```


## Full Manual

Use the base R `help()` function to view the full manual for `getColors()` or `style()`. Simply enter a question mark followed by the name of the function.

```
?getColors
?style
```

