rainbowJam: rainbow categorical colors using varied luminance and chroma

In jmw86069/colorjam: Jam Color manipulation functions

rainbow categorical colors using varied luminance and chroma

Description

rainbow categorical colors using varied luminance and chroma

Usage

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"),
  min_requested_n = 3,
  test_color_model = c("HCL", "HSL"),
  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
min_requested_n	numeric experimental value which defines the minimum internal color hues to use when n is low. Typically this argument restricts the first several color hues to prevent unusual colors.
test_color_model	logical default FALSE, enables a test mode which enables HSL color space. The method uses an adjustment that takes an average of the HCL chroma/luminance converted to HSL saturation/lightness, then averages with the Cvals,Lvals originally used for HCL. The effect is a somewhat muted version of HSL which otherwise would be too neon saturated. The output is closer to HSL, with generally more vibrant colors than the HCL equivalent, because certain color hues tend to become more saturated based upon the range of opportunity for each color hue. HCL does not account for the available chroma for a hue, it simply caps the chroma.
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 closest_named_color() when nameStyle="closest_named_color" closestRcolor() when nameStyle="closestRcolor" jamba::makeNames() when nameStyle is anything except "none".

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().

Value

character vector of categorical colors

See Also

Other colorjam core: blend_colors(), closestRcolor(), color_complement(), colors_to_df(), group2colors(), sort_colors(), subset_colors()

Examples

rainbowJam(12);

# 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(rainbowJam(6, nameStyle="closestRcolor"));
# or use the closest R color itself
jamba::showColors(names(rainbowJam(6, nameStyle="closestRcolor")));

# be fancy and label colors using the closest named_color
jamba::showColors(rainbowJam(6, nameStyle="closest_named_color"));

# be even fancier and use the nearest named color by its name
jamba::showColors(named_colors[names(rainbowJam(6, nameStyle="closest_named_color"))]);

# comparison of version 0.0.19.900 and update with version 0.0.20.900
cat19 <- rainbowJam_v1(n=12)
cat20 <- rainbowJam(n=12)
jamba::showColors(list(version19=cat19, version20=cat20))

jmw86069/colorjam documentation built on June 10, 2025, 12:02 p.m.