rainbow categorical colors using varied luminance and chroma

Source: R/colorjam-rainbowjam.R

rainbow categorical colors using varied luminance and chroma

rainbowJam(
  n = NULL,
  preset = getOption("colorjam.preset", "dichromat2"),
  step = getOption("colorjam.step", "default"),
  Hstart = 0,
  alpha = 1,
  hues = NULL,
  warpHue = NULL,
  h1 = NULL,
  h2 = NULL,
  Cvals = NULL,
  Lvals = NULL,
  Crange = NULL,
  Lrange = NULL,
  phase = 1,
  direction = c("1", "-1"),
  do_hue_pad = FALSE,
  hue_pad_percent = 0,
  nameStyle = c("none", "n", "closest_named_color", "closestRcolor", "hcl", "color"),
  doTest = FALSE,
  verbose = FALSE,
  ...
)

Arguments

n

integer number of categorical colors to return

preset

character string matching one entry in colorjam_presets(), which defines the color wheel to use. define the color wheel, only used when warpHue=TRUE.

step

character string matching one entry in colorjam_steps(), which defines the sequence of Chroma and Luminance values across the range of color hues.

Hstart

numeric hue to use for the first hue value in the color sequence. This value represents the first color in the color wheel defined by preset, and colors are arrayed across 360 degrees.

alpha

numeric alpha transparency of colors, values ranging from 0 to 1. If multiple values are supplied, they are applied in order to the categorical colors returned.

hues

numeric optional vector with specific hues to use instead of using Hstart and filling the 360 degree color wheel with colors.

warpHue

logical (deprecated) formerly to enable or disable the color warping for custom color wheel. To disable a custom color wheel use preset="rgb".

h1, h2

numeric (deprecated) in favor of argument preset to define the h1 and h2 values. To use custom values for h1 and h2 use add_colorjam_preset() to define a new preset name, then use the name with preset.

Cvals, Lvals

numeric (deprecated) in favor of argument step to define the sequence of Chroma and Luminance values. To define custom values, use add_colorjam_step() to define a new step name, then use the name with step.

Crange, Lrange

numeric optional permitted ranges for Chroma and Luminance values. These adjustments may be useful to impose a darker or lighter set of categorical colors.

  • When any Chroma value is outside the given Crange, all color Chroma values are scaled to fit this range using jamba::normScale(). This process scales the lowest observed Chroma to the minimum Crange, and the highest observed Chroma to the maximum Crange, in order to preserve intermediate gradient values.

  • When any Luminance value is outside the given Lrange, all color Luminance values are scaled to fit this range using jamba::normScale().

phase

integer starting step value to use from the sequence of Chroma and Luminance values defined by colorjam_steps().

  • Default phase=1 begins with the first value; phase=2 begins with the second value.

  • When phase is negative, the Chroma and Luminance values are each reversed, then the absolute value of phase is used. For example phase=-1 reverses the sequence, then uses the first value. So it would begin with the last Chroma value, and the last Luminance value.

direction

character value indicating the direction to travel around the color wheel, permitting the color wheel to be reversed. When using direction="-1" it may also be helpful to use a negative phase=-1.

  • "1" (default) travels forward, clockwise around the color wheel

  • "-1" travels in reverse, counter-clockwise around the color wheel

do_hue_pad

logical indicating whether to apply padding to the end of the color hue sequence. This padding increases distinction between the first and last colors.

hue_pad_percent

numeric value between 0 and 100, used when do_hue_pad=TRUE to apply a padding between the first and last color hues.

nameStyle

character string for the style of name assigned:

  • "none" assigns no names

  • "n" assigns names in numerical order

  • "closest_named_color" assigns the closest matching color from named_colors, calling closest_named_color() using ... for additional arguments.

  • "closestRcolor" assigns names from closestRcolors(), using ... for additional arguments.

  • "hcl" assigns names using H, C, L values

  • "color" assigns names by hex color

doTest

logical indicating whether to perform a visual test for n number of colors produced.

verbose

logical whether to print verbose output

...

additional arguments are passed to

Value

character vector of categorical colors

Details

This function customizes similar functions grDevices::rainbow, colorspace::rainbow_hcl(), and scales::hue_pal() in two main ways:

  1. It uses the warped color wheel (see h2hw() which compresses the green component of the standard HCL color hue wheel, extending the yellow.

  2. It uses a varying luminance and chroma vector which was selected to optimize visual distinctiveness of adjacent colors. There is still a limit to the maximum number of effectively different categorical colors, however this function appears to improve other available methods.

This function is also intended to enable use of a custom color wheel, for example a set of color mappings could define color-blind friendly ranges of colors when using the warped hue functions h2hw() and hw2h(). When warpHue=TRUE the values for h1 and h2 are used to define a mapping from warped hues to standard hues recognized by hcl().

Examples

rainbowJam(12);
#>  [1] "#E8C421" "#B06C00" "#E6861C" "#D27058" "#FF8CA0" "#F56296" "#FFA4E7"
#>  [8] "#9D63F8" "#A7A0FF" "#748FE9" "#76D0FF" "#00ACFE"
#> attr(,"preset")
#> [1] "dichromat2"

# show colors
jamba::showColors(rainbowJam(10));


# show colors
color_pie(rainbowJam(10));


# be fancy and label colors using the closest R named color
jamba::showColors(names(rainbowJam(6, nameStyle="closestRcolor")));


# comparison of version 0.0.19.900 and update with version 0.0.20.900
cat19 <- rainbowJam(n=12,
   Cvals=c(140, 150, 160, 130, 200, 100),
   Lvals=c( 47,  85,  62,  42,  77,  54))
#> Warning: ! `Cvals` and `Lvals` are deprecated, use argument `step`.
cat20 <- rainbowJam(n=12,
   Cvals=c(200, 120, 160,  90, 180, 150),
   Lvals=c( 44,  88,  74,  58,  80,  65))
#> Warning: ! `Cvals` and `Lvals` are deprecated, use argument `step`.
jamba::showColors(list(version19=cat19, version20=cat20))