Skip to contents

Generate qualitative color palettes

Source: R/qualpal.R
qualpal.Rd

Given a collection of colors, qualpal() algorithmically tries to select to n most distinct colors from the provided input colors, optionally taking color vision deficiency into account.

Usage

qualpal(
  n,
  colorspace = list(h = c(0, 360), s = c(0.2, 0.5), l = c(0.6, 0.85)),
  cvd = c(protan = 0, deutan = 0, tritan = 0),
  cvd_severity,
  bg = NULL,
  metric = c("ciede2000", "din99d", "cie76"),
  extend = NULL
)

Arguments

n

The number of colors to generate.

colorspace

A color space to generate colors from. Can be any of the following:

  • A list that describes a color space in either HSL or LCHab color space. In the first case (HSL), the list must contain the following named vectors, each of length two, giving a range for each item.

    h

    Hue, in range from -360 to 360

    s

    Saturation, in the range from 0 to 1

    l

    Lightness, in the range from 0 to 1

    In the second case (LCHab), the list must contain the following named vectors, each of length two, giving a range for each item.

    h

    Hue, in range from -360 to 360

    c

    Chroma, in the range from 0 to infinity

    l

    Lightness, in the range from 0 to 100

    In these cases, qualpal() will generate

  • A character vector of length one in the form of "Source:Palette", where Domain is the name of a source that provides a color palette, and Palette is the name of a color palette from that source. See list_palettes() for available palettes.

  • A matrix or data frame of RGB values (with values between 0 and 1).

cvd

Color vision deficiency adaptation. This must be a named vector with names protan, deutan, and tritan and values between 0 and 1, where 0 means no adaptation and 1 means full adaptation.

cvd_severity

DEPRECATED. Use a named cvd vector instead, e.g. c(protan = 0.5, deutan = 0.2, tritan = 0).

bg

Background color to consider (but not include) when generating the palette. This is useful to avoid colors that are too close to the background/canvas color. If NULL (the default), the background color is not considered at all. Any color that is convertable via col2rgb is acceptable, including hex colors.

metric

The color metric to use for the color distance matrix.

extend

A palette of colors to use as a fixed set of initial colors in the palette, which can be either a matrix or data frame of RGB values (with values between 0 and 1) or a character vector of hex colors (or any other format that's acceptable in grDevices::col2rgb()).

Value

A list of class qualpal with the following components.

HSL

A matrix of the colors in the HSL color space.

RGB

A matrix of the colors in the sRGB color space.

hex

A character vector of the colors in hex notation.

de_DIN99d

A distance matrix of color differences according to the metric used. The name is misleading, bu kept for backwards compatibility.

hex

A character vector of the colors in hex notation.

min_de_DIN99d

The minimum pairwise DIN99d color difference among all colors in the palette.

Details

The main idea is to compute a distance matrix from all the input colors, and then try to select the most distinct colors based on the color differences between them. It does this iteratively by first selecting the first n colors from the input colors, then iterates over the palette, putting colors back into the total set and replaces it with a new color until it has gone through the whole range without changing any of the colors.

Optionally, qualpal can adapt palettes to cater to color vision deficiency (CVD). This is accomplished by taking the colors provided by the user and transforming them to colors that someone with CVD would see, that is, simulating CVD qualpal then chooses colors from these new colors.

See also

plot.qualpal(), pairs.qualpal(), list_palettes()

Examples

# Generate 3 distinct colors from the default color space
qualpal(3)
#> ---------------------------------------- 
#> Colors in the HSL color space 
#> 
#>         Hue Saturation Lightness
#> #c9cb70  62       0.47      0.62
#> #ca6c74 355       0.47      0.61
#> #70a4c8 205       0.45      0.61
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #c9cb70 #ca6c74
#> #ca6c74      22        
#> #70a4c8      24      24

# Provide a custom color space
qualpal(n = 3, list(h = c(35, 360), s = c(0.5, 0.7), l = c(0, 0.45)))
#> ---------------------------------------- 
#> Colors in the HSL color space 
#> 
#>         Hue Saturation Lightness
#> #b32eb7 298       0.60     0.449
#> #9ebb26  71       0.66     0.440
#> #071f06 117       0.67     0.073
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #b32eb7 #9ebb26
#> #9ebb26      32        
#> #071f06      30      29

qualpal(3, "ColorBrewer:Set2")
#> ---------------------------------------- 
#> Colors in the HSL color space 
#> 
#>         Hue Saturation Lightness
#> #a6d854  83       0.63      0.59
#> #fc8d62  17       0.96      0.69
#> #8da0cb 222       0.37      0.67
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #a6d854 #fc8d62
#> #fc8d62      22        
#> #8da0cb      26      24

# Adapt palette to deuteranopia
qualpal(5, "ColorBrewer:Dark2", cvd = c(deutan = 1))
#> ---------------------------------------- 
#> Colors in the HSL color space 
#> 
#>         Hue Saturation Lightness
#> #e6ab02  44       0.98      0.45
#> #a6761d  39       0.70      0.38
#> #1b9e77 162       0.71      0.36
#> #7570b3 244       0.31      0.57
#> #e7298a 329       0.80      0.53
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #e6ab02 #a6761d #1b9e77 #7570b3
#> #a6761d      12                        
#> #1b9e77      24      23                
#> #7570b3      29      26      24        
#> #e7298a      26      22      31      20

# Adapt palette to protanomaly with severity 0.4
qualpal(8, cvd = c(protan = 0.4))
#> ---------------------------------------- 
#> Colors in the HSL color space 
#> 
#>         Hue Saturation Lightness
#> #ca6c74 355       0.47      0.61
#> #6e6cca 241       0.47      0.61
#> #d890cc 310       0.48      0.71
#> #7dbdd0 193       0.46      0.65
#> #c1e4d3 150       0.40      0.83
#> #e6bbbd 357       0.45      0.82
#> #c59671  27       0.42      0.61
#> #8acc6d 102       0.48      0.61
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #ca6c74 #6e6cca #d890cc #7dbdd0 #c1e4d3 #e6bbbd #c59671
#> #6e6cca      22                                                
#> #d890cc      14      16                                        
#> #7dbdd0      25      19      22                                
#> #c1e4d3      25      25      23      13                        
#> #e6bbbd      14      22      13      20      17                
#> #c59671      12      25      18      22      19      12        
#> #8acc6d      26      29      27      19      14      22      19

# Generate and extend a palette with 3 colors, using the DIN99d
# metric
pal <- qualpal(3)
qualpal(5, extend = pal$hex, metric = "din99d")
#> ---------------------------------------- 
#> Colors in the HSL color space 
#> 
#>         Hue Saturation Lightness
#> #c9cb70  61       0.47      0.62
#> #ca6c74 355       0.47      0.61
#> #70a4c8 205       0.44      0.61
#> #9468ca 267       0.48      0.60
#> #e6c6e6 301       0.39      0.84
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #c9cb70 #ca6c74 #70a4c8 #9468ca
#> #ca6c74      22                        
#> #70a4c8      24      24                
#> #9468ca      29      19      18        
#> #e6c6e6      22      18      18      17

if (FALSE) { # \dontrun{
# The range of hue cannot exceed 360
qualpal(3, list(h = c(-20, 360), s = c(0.5, 0.7), l = c(0, 0.45)))
} # }