Conveniently maps data values (numeric or factor/character) to colors according to a given palette, which can be provided in a variety of formats.

## Usage

```
colorNumeric(
palette,
domain,
na.color = "#808080",
alpha = FALSE,
reverse = FALSE
)
colorBin(
palette,
domain,
bins = 7,
pretty = TRUE,
na.color = "#808080",
alpha = FALSE,
reverse = FALSE,
right = FALSE
)
colorQuantile(
palette,
domain,
n = 4,
probs = seq(0, 1, length.out = n + 1),
na.color = "#808080",
alpha = FALSE,
reverse = FALSE,
right = FALSE
)
colorFactor(
palette,
domain,
levels = NULL,
ordered = FALSE,
na.color = "#808080",
alpha = FALSE,
reverse = FALSE
)
```

## Arguments

- palette
The colors or color function that values will be mapped to

- domain
The possible values that can be mapped.

For

`colorNumeric()`

and`colorBin()`

, this can be a simple numeric range (e.g.,`c(0, 100)`

);`colorQuantile()`

needs representative numeric data; and`colorFactor()`

needs categorical data.If

`NULL`

, then whenever the resulting color function is called, the`x`

value will represent the domain. This implies that if the function is invoked multiple times, the encoding between values and colors may not be consistent; if consistency is needed, you must provide a non-`NULL`

domain.- na.color
The color to return for

`NA`

values. Note that`na.color = NA`

is valid.- alpha
Whether alpha channels should be respected or ignored. If

`TRUE`

then colors without explicit alpha information will be treated as fully opaque.- reverse
Whether the colors (or color function) in

`palette`

should be used in reverse order. For example, if the default order of a palette goes from blue to green, then`reverse = TRUE`

will result in the colors going from green to blue.- bins
Either a numeric vector of two or more unique cut points or a single number (greater than or equal to 2) giving the number of intervals into which the domain values are to be cut.

- pretty
Whether to use the function

`pretty()`

to generate the bins when the argument`bins`

is a single number. When`pretty = TRUE`

, the actual number of bins may not be the number of bins you specified. When`pretty = FALSE`

,`seq()`

is used to generate the bins and the breaks may not be "pretty".- right
parameter supplied to cut. See Details

- n
Number of equal-size quantiles desired. For more precise control, use

`probs`

instead.- probs
See

`stats::quantile()`

. If provided,`n`

is ignored.- levels
An alternate way of specifying levels; if specified, domain is ignored

- ordered
If

`TRUE`

and`domain`

needs to be coerced to a factor, treat it as already in the correct order

## Value

A function that takes a single parameter `x`

; when called with a
vector of numbers (except for `colorFactor()`

, which expects
factors/characters), #RRGGBB color strings are returned (unless
`alpha = TRUE`

in which case #RRGGBBAA may also be possible).

## Details

`colorNumeric()`

is a simple linear mapping from continuous numeric data
to an interpolated palette.

`colorBin()`

also maps continuous numeric data, but performs
binning based on value (see the `base::cut()`

function). `colorBin()`

defaults for the `base::cut()`

function are `include.lowest = TRUE`

and `right = FALSE`

.

`colorQuantile()`

similarly bins numeric data, but via `stats::quantile()`

.

`colorFactor()`

maps factors to colors. If the palette is
discrete and has a different number of colors than the number of factors,
interpolation is used.

The `palette`

argument can be any of the following:

A character vector of RGB or named colors. Examples:

`palette()`

,`c("#000000", "#0000FF", "#FFFFFF")`

,`topo.colors(10)`

The name of an RColorBrewer palette, e.g.,

`"BuPu"`

or`"Greens"`

.The full name of a viridis palette:

`"magma"`

,`"inferno"`

,`"plasma"`

,`"viridis"`

,`"cividis"`

,`"rocket"`

,`"mako"`

, or`"turbo"`

A function that receives a single value between 0 and 1 and returns a color. Examples:

`colorRamp(c("#000000", "#FFFFFF"), interpolate = "spline")`

.

## Examples

```
pal <- colorBin("Greens", domain = 0:100)
pal(runif(10, 60, 100))
#> [1] "#31A354" "#31A354" "#31A354" "#31A354" "#31A354" "#31A354" "#006D2C"
#> [8] "#31A354" "#006D2C" "#006D2C"
if (interactive()) {
# Exponential distribution, mapped continuously
previewColors(colorNumeric("Blues", domain = NULL), sort(rexp(16)))
# Exponential distribution, mapped by interval
previewColors(colorBin("Blues", domain = NULL, bins = 4), sort(rexp(16)))
# Exponential distribution, mapped by quantile
previewColors(colorQuantile("Blues", domain = NULL), sort(rexp(16)))
# Categorical data; by default, the values being colored span the gamut...
previewColors(colorFactor("RdYlBu", domain = NULL), LETTERS[1:5])
# ...unless the data is a factor, without droplevels...
previewColors(colorFactor("RdYlBu", domain = NULL), factor(LETTERS[1:5], levels = LETTERS))
# ...or the domain is stated explicitly.
previewColors(colorFactor("RdYlBu", levels = LETTERS), LETTERS[1:5])
}
```