R: Color mapping

col_numeric {scales} | R Documentation

## Color mapping

### Description

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

    col_numeric(palette, domain, na.color = "#808080")

    col_bin(palette, domain, bins = 7, pretty = TRUE, na.color = "#808080")

    col_quantile(palette, domain, n = 4, probs = seq(0, 1, length.out = n + 1),
      na.color = "#808080")

    col_factor(palette, domain, levels = NULL, ordered = FALSE,
      na.color = "#808080")

### Arguments

`palette` | The colors or color function that values will be mapped to
`domain` | The possible values that can be mapped. For `col_numeric` and `col_bin`, this can be a simple numeric range (e.g. `c(0, 100)`); `col_quantile` needs representative numeric data; and `col_factor` 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.
`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".
`n` | Number of equal-size quantiles desired. For more precise control, use the `probs` argument instead.
`probs` | See `quantile`. If provided, the `n` argument 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

### Details

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

`col_bin` also maps continuous numeric data, but performs binning based on value (see the `cut` function).

`col_quantile` similarly bins numeric data, but via the `quantile` function.

`col_factor` 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:

1. A character vector of RGB or named colors. Examples: `palette()`, `c("#000000", "#0000FF", "#FFFFFF")`, `topo.colors(10)`

2. The name of an RColorBrewer palette, e.g. `"BuPu"` or `"Greens"`.

3. A function that receives a single value between 0 and 1 and returns a color. Examples: `colorRamp(c("#000000", "#FFFFFF"), interpolate="spline")`.

### Value

A function that takes a single parameter `x`; when called with a vector of numbers (except for `col_factor`, which expects factors/characters), #RRGGBB color strings are returned.

### Examples

    pal <- col_bin("Greens", domain = 0:100)
    show_col(pal(sort(runif(10, 60, 100))))

    # Exponential distribution, mapped continuously
    show_col(col_numeric("Blues", domain = NULL)(sort(rexp(16))))
    # Exponential distribution, mapped by interval
    show_col(col_bin("Blues", domain = NULL, bins = 4)(sort(rexp(16))))
    # Exponential distribution, mapped by quantile
    show_col(col_quantile("Blues", domain = NULL)(sort(rexp(16))))

    # Categorical data; by default, the values being colored span the gamut...
    show_col(col_factor("RdYlBu", domain = NULL)(LETTERS[1:5]))
    # ...unless the data is a factor, without droplevels...
    show_col(col_factor("RdYlBu", domain = NULL)(factor(LETTERS[1:5], levels=LETTERS)))
    # ...or the domain is stated explicitly.
    show_col(col_factor("RdYlBu", levels = LETTERS)(LETTERS[1:5]))

[Package scales version 0.4.1 Index]