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 colros 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
#> #c8cb70  62       0.47      0.62
#> #c96c74 355       0.47      0.61
#> #70a3c8 205       0.45      0.61
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #c8cb70 #c96c74
#> #c96c74      22        
#> #70a3c8      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
#> #b32eb6 298       0.60     0.449
#> #9eba25  71       0.66     0.440
#> #071e06 117       0.67     0.073
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #b32eb6 #9eba25
#> #9eba25      32        
#> #071e06      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
#> #c96c74 355       0.47      0.61
#> #6d6cc9 241       0.47      0.61
#> #d890cb 310       0.48      0.71
#> #7dbdcf 193       0.46      0.65
#> #c1e4d3 150       0.40      0.83
#> #e5bbbd 357       0.45      0.82
#> #c49670  27       0.42      0.61
#> #8acb6c 102       0.48      0.61
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #c96c74 #6d6cc9 #d890cb #7dbdcf #c1e4d3 #e5bbbd #c49670
#> #6d6cc9      22                                                
#> #d890cb      14      16                                        
#> #7dbdcf      25      19      22                                
#> #c1e4d3      25      25      23      13                        
#> #e5bbbd      14      22      13      20      17                
#> #c49670      12      25      18      22      19      12        
#> #8acb6c      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
#> #c8cb70  62       0.47      0.62
#> #c96c74 355       0.46      0.61
#> #70a3c8 205       0.44      0.61
#> #9467ca 267       0.48      0.60
#> #e6c5e5 301       0.39      0.84
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #c8cb70 #c96c74 #70a3c8 #9467ca
#> #c96c74      22                        
#> #70a3c8      24      24                
#> #9467ca      29      19      18        
#> #e6c5e5      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)))
} # }