Jam Color manipulation functions • colorjam

Why colorjam?

colorjam provides visually distinct categorical colors of arbitrary length, optimized for distinctive colors. It is similar in concept to rainbow() and colorspace::rainbow_hcl() except that those functions do not attempt to make colors distinctive.

Visually distinct.: Improved color contrast.
Scalable. Categorical colors of arbitrary length.
- rainbowJam(n)
- ggplot2 functions: theme_jam(), or
  scale_color_jam(), scale_fill_jam()
Color-blindness friendly. Optimized color wheel across the three major types of color blindness.
Flexible. Custom color wheels: "dichromat", "ryb", "rgb"
Optimized for statistical design. Colors begin with gold for control group.
Helpful Utilities:
- theme_jam() - ggplot2 theme which uses colorjam categorical colors.
- closestRcolor() - assign R color name
- closest_named_color() - assign very diverse color name
- group2colors() - assign colors to unique group terms
- add_colors() - add distinctive colors to existing categorical colors.
- color_complement() - complement colors with custom color wheel.
- col_div_xf() - divergent numeric-to-color function for heatmaps, bar charts, plots. Applies numeric max, and optional numeric floor.
- col_linear_xf() - linear numeric-to-color function for heatmaps, bar charts, plots. Applies numeric max, and optional numeric floor.
- sort_colors(), subset_colors() - sort or subset colors using numerous HCL, HSL, LUV color space properties.

Installation

Install colorjam using the remotes package:

remotes::install_github("jmw86069/colorjam");

OR use pak:

### if necessary, install pacman:
# install.packages("pak")
pak::pkg_install("jmw86069/colorjam")

colorjam is being prepared for CRAN.

Command reference

The full command reference is available here:

colorjam command reference

Quick start with colorjam

For the examples below, two packages are loaded:

library(colorjam);
library(jamba);

Categorical colors

dichromat (default)

Let’s generate n=5 categorical colors, displayed by jamba::showColors().

showColors(rainbowJam(5));

Default rainbowJam output with 5 colors.

Alternatively, color_pie() displays colors in a pie circle.

color_pie(rainbowJam(5));

Default rainbowJam output with 5 colors, shown with colors in pie wedges.

Categorical colors are scalable.

color_pie(rainbowJam(15));

Pie colors of rainbowJam output with 15 colors.

Label the colors using the 4994 named_colors:

color_pie(rainbowJam(15, nameStyle="closest_named_color"));

rainbowJam with 15 colors, labeled by colorjam color names.

Gradually increase the number of colors, then use color_pie() to plot them in concentric circles.

colorList <- lapply(nameVector(c(36, 24, 12)), function(n){
   rainbowJam(n, nameStyle="n");
});
color_pie(colorList,
   main="preset='dichromat2' (default)");

rainbowJam output, with increasing number of colors in concentric circles.

What is “dichromat” here?

Every color system has a “color wheel” - something like red-green-blue (RGB) or red-yellow-blue (RYB).

We defined a new color wheel "dichromat" to maximize the visual distinction between color hues for people with color blindness. The process was driven by R package dichromat, so we gave it that name out of respect.

The "dichromat" color wheel allocates approximately equal halves of the color wheel to be visually distinct for "deutan", "protan", and "tritan" forms of color blindness. Roughly akin to using “cool”/“warm” colors for each half the color wheel, for each simulated color. The wheel avoids colors which are the most difficult to distinguish in the color wheel.

It isn’t perfect.

However colorjam does provide the first scalable method (we have seen) to produce categorical colors optimized for the three major forms of color-blindness. Other excellent resources that provide color-blindness friendly colors, which are not scalable. However to be fair, fixed colors may be the best realistic approach, so colorjam may not be the ideal solution.

red-yellow-blue

The “full rainbow” color wheel “red-yellow-blue” is recommended over default RGB to provide the best full rainbow. It performs particularly well for color blending (see Color-blending) for additive paint-like mixing.

preset="ryb": red-yellow-blue

color_pie(rainbowJam(12, preset="ryb"),
   main="Red-Yellow-Blue\npreset='ryb' (starting at red)");

rainbowJam using red-yellow-blue color wheel, showing 12 colors.

preset="ryb2": yellow-red-blue

color_pie(rainbowJam(12, preset="ryb2"),
   main="Yellow-Red-Blue\npreset='ryb2' (starting at yellow)");

rainbowJam using yellow-red-blue color wheel, showing 12 colors.

red-green-blue

Similarly, the R default “red-green-blue” color wheel:

preset="rgb": R default RGB color wheel

color_pie(
   rainbowJam(16, preset="rgb"),
   main="Red-Green-Blue\npreset='rgb' (starting at red)");

rainbowJam using R default RGB color wheel, showing 16 colors.

*(Look how much of this color wheel is blue-green!)

preset="rgb2": R default RGB color wheel starting with yellow

color_pie(
   rainbowJam(16, preset="rgb2"),
   main="Red-Green-Blue\npreset='rgb2' (starting at yellow)");

rainbowJam using RGB color wheel starting at yellow, showing 16 colors.

More about color wheels

The 4994 colors provided in named_colors (see next section) are collated from numerous sources. These are 4,994 unique colors that people were motivated to name.

More than half the circle represents red/orange/yellow! Very little includes green, in contrast to the RGB color wheel above.

Here, named_colors are filtered for at least Chroma 40 using subset_colors(named_colors, C > 40)

color_pie(unname(
   subset_colors(named_colors, C > 40)))

Color wheel using 2,742 named colors from colorjam named_colors, filtered for chroma and luminance.

Clearly people can see many more red-orange-yellow, and comparatively very few green/blue colors. This bias is partly from lower sensitivity of colors such as “cyan”, and partly due to RGB color monitors being unable to produce high saturation colors with that hue. Color theory is fascinating, and endlessly complex, in part because each person is slightly different.

Color matching / Color naming

Two functions are provided to match colors to a reference set, which is a convenient way to assign color names.

closestRcolor()
- matches colors to the 657 colors in grDevices::colors(), custom reference colors can be supplied.
closest_named_color()
- matches colors to 4883 named_colors, which adds 4447 colors from meodai/named-colors (amazing!) and 436 colors not already represented from grDevices::colors().

The argument showPalette=TRUE will plot the original colors and the closest matched color for comparison.

cnc <- closest_named_color(c(rainbowJam(12), "grey"),
   showPalette=TRUE,
   main="closest_named_color() using colorjam `named_colors`");

Color palettes are shown where colors are named by closest matching named colors.

crc <- closestRcolor(c(rainbowJam(12), "grey"),
   showPalette=TRUE,
   main="closestRcolor() using R `colors()`");

Color palettes are shown where colors are named by closest matching named colors.

Greyscale colors are matches separately to a subset of grayscale reference colors, to avoid using hue in unsaturated colors.

Color-blending

blend_colors() has some useful features:

Paint-style blending. blue + yellow = green. (For default RGB: blue + yellow = grey)
Scalable number of colors. Able to mix more than two colors.
Transparency-aware. Accounts for color transparency during mixing.

The argument do_plot=TRUE will plot a visual summary of the mixing results.

blent1 <- blend_colors(c("red", "blue"), do_plot=TRUE);