colour_values {colourvalues}

Colour Values

Description

maps colours to values, returning a vector of hex strings

Usage

colour_values(
  x,
  palette = "viridis",
  alpha = 255,
  na_colour = "#808080FF",
  include_alpha = TRUE,
  summary = FALSE,
  n_summaries = 0,
  format = TRUE,
  digits = 2
)

color_values(
  x,
  palette = "viridis",
  alpha = 255,
  na_colour = "#808080FF",
  include_alpha = TRUE,
  summary = FALSE,
  n_summaries = 0,
  format = TRUE,
  digits = 2
)

## S3 method for class 'character'
colour_values_to_hex(
  x,
  palette,
  alpha,
  na_colour,
  include_alpha,
  summary,
  n_summaries,
  format,
  digits
)

## S3 method for class 'logical'
colour_values_to_hex(
  x,
  palette,
  alpha,
  na_colour,
  include_alpha,
  summary,
  n_summaries,
  format,
  digits
)

## S3 method for class 'factor'
colour_values_to_hex(
  x,
  palette,
  alpha,
  na_colour,
  include_alpha,
  summary,
  n_summaries,
  format,
  digits
)

## S3 method for class 'Date'
colour_values_to_hex(
  x,
  palette,
  alpha,
  na_colour,
  include_alpha,
  summary,
  n_summaries,
  format,
  digits
)

## S3 method for class 'POSIXct'
colour_values_to_hex(
  x,
  palette,
  alpha,
  na_colour,
  include_alpha,
  summary,
  n_summaries,
  format,
  digits
)

## S3 method for class 'POSIXlt'
colour_values_to_hex(
  x,
  palette,
  alpha,
  na_colour,
  include_alpha,
  summary,
  n_summaries,
  format,
  digits
)

Arguments

x

vector of values to map to a colour

palette

colour palette. See details and examples

alpha

optional. Single value in [0,255] applied to all colours, or a decimal in [0, 1) (to indicate a percentage, noting 1 is excluded), or a vector of numeric values the same length as x. The numeric vector will be scaled into the range [0,255]. If a matrix palette is supplied this argument is ignored.

na_colour

hex string colour to use for NA values in the form #RRGGBBAA.

include_alpha

logical indicating if the returned hex or matrix should include the alpha values. Defaults to TRUE.

summary

logical indicating if a summary of the colours should be returned as well as the full colour mapping. This will be the unique elements of x mapped to the colour.

n_summaries

positive integer. If supplied a summary colour palette will be returned in a list, containing n_summaries equally spaced values of x in the range [min(x),max(x)], and their associated colours. If a non-numeric x is used this value is ignored

format

logical indicating if the summary values should be formatted.

digits

number of decimal places to show in the summary

Details

The palette can either be

• String - use colour_palettes() to view available palettes

• Matrix - At least 5 rows, and 3 (or 4) columns representing the red, green and blue (and alpha) values

The matrix palette requires 5 rows because the colours are interpolated using a cubic b-spline. This method requires 5 values.

See Also

colour_values_rgb

Examples

## in-built palettes
colour_values(x = 1:5) ## default is "viridis"
colour_values(x = 1:5, palette = "inferno")
colour_values(x = 1:5, palette = "plasma")
colour_values(x = 1:5, palette = "magma")
colour_values(x = 1:5, palette = "cividis")
colour_values(x = 1:5, palette = "rainbow")

## matrix palette
n <- 100
m <- grDevices::colorRamp(c("red", "green"))( (1:n)/n )
df <- data.frame(a = 10, x = 1:n)
df$col <- colour_values(df$x, palette = m)
barplot(height = df$a, col = df$col, border = NA, space = 0)

## with an alpha column on the palette
n <- 100
m <- grDevices::colorRamp(c("red", "green"))( (1:n)/n )
m <- cbind(m, seq(0, 255, length.out = 100))
df <- data.frame(a = 10, x = 1:n)
df$col <- colour_values(df$x, palette = m)
barplot(height = df$a, col = df$col, border = NA, space = 0)

## single alpha value for all colours
df <- data.frame(a = 10, x = 1:255)
df$col <- colour_values(df$x, alpha = 50)
barplot(height = df$a, col = df$col, border = NA, space = 0)

## vector of alpha values
df <- data.frame(a = 10, x = 1:300, y = rep(c(1:50, 50:1), 3) )
df$col <- colour_values(df$x, alpha = df$y)
barplot(height = df$a, col = df$col, border = NA, space = 0)

## returning a summary palette
colour_values(-10:10, n_summaries = 5)

colour_values(x = runif(20, 0, 1), n_summaries = 3, digits = 2)
colour_values(x = runif(20, 0, 1), n_summaries = 3, digits = 10)

## Formatting output
## default is TRUE
colour_values(
  x = seq(as.Date("2023-01-01"), as.Date("2023-01-31"), by = 1)
  , n_summaries = 5
)
colour_values(
  x = seq(as.Date("2023-01-01"), as.Date("2023-01-31"), by = 1)
  , n_summaries = 5
  , format = FALSE
)