add_colors: Add categorical colors to an existing color set

In jmw86069/colorjam: Jam Color manipulation functions

Add categorical colors to an existing color set

Description

Add categorical colors to an existing color set

Usage

add_colors(
  given_colors = NULL,
  n = 1,
  return_type = c("new", "full", "list"),
  color_fn = rainbowJam,
  check_internal = FALSE,
  max_iterations = 50,
  min_distance = 30,
  step_distance = -1,
  use_white = "F5",
  method = "cie2000",
  do_plot = FALSE,
  verbose = FALSE,
  seed = 123,
  ...
)

Arguments

given_colors	character vector of colors, default NULL. When given_colors is NULL, n new colors will be returned.
n	integer number of colors to add to given_colors
return_type	character, default "new", what colors to return: "new" - return only the newly assigned colors "full" - return input colors and assigned colors together, in order: given, then new colors.
color_fn	function, default rainbowJam(). The first argument n is expected to be the integer number of colors to return, and the function should return n color values. Other arguments in ... are passed to this function for custom options. Alternatively, character input is expanded using jamba::color2gradient(), although this process is not well-tested.
check_internal	logical default FALSE whether to check the color_fn output for internal color distances. This step improves color output, however is currently time-consuming. For best results, color_fn should already provide colors are as distinct from one another as possible, generally true for example rainbowJam(). However when using a function that provides relatively uniform colors, such as colorspace::rainbow_hcl(), the colors which are most distinct from given_colors are often also very similar to each other. The check_internal=TRUE also requires colors from color_fn to meet the min_distance threshold, which requires a recursive, nested algorithm in find_color_spread().
max_iterations	integer default 50, maximum iterations to attempt. The algorithm begins at n and increases the attempted colors by 1 each iteration until it defines at least n new colors. When step_distance is non-zero, the min_distance is reduced by abs(step_distance) then the iterations are repeated. When step_distance is zero, if no solution is found it returns 'NULL'.
min_distance	numeric default 30, minimum distance to require for new colors compared to given_colors. When at least n colors are defined with at least min_distance distance from given_colors, the n colors with the greatest distance are returned. When n colors do not meet these critera, and step_distance is non-zero, the min_distance is reduced by abs(step_distance) and the process is repeated. Finally, if n colors cannot be defined, it returns 'NULL'.
step_distance	numeric default 1, the default step size when iterating progressively smaller min_distance values. When 'NULL' or '0', the min_distance is not decreased after max_iterations iterations.
use_white	character default "F5" representing the white reference, any value recognized by farver::as_white_ref(). The default 'F5' represents 'daylight fluorescent' and in qualitative testing was most effective when defining color distances. The typical default 'D65' is 'daylight 6500K' and is typically used for neutral daylight without blue (cool) or yellow (warm) shifted background lighting.
method	character, default 'cie2000', passed to slot_colors(), then color_distance() to define the color distance method.
do_plot	logical default FALSE, whether to plot the given_colors and new colors.
verbose	logical indicating whether to print verbose output.
...	additional arguments are passed to internal functions color_fn, slot_colors(), and optionally jamba::color2gradient().

Value

character vector of colors with length n.

Examples

n1 <- 6;
n <- 2;
given <- jamba::nameVector(rainbowJam(n1));
new_colors <- add_colors(given, n=n, do_plot=TRUE, method="cmc")
names(new_colors) <- seq_along(new_colors);
show_color_distance(c(given, new_colors))
show_color_distance(c(given, new_colors), cluster_data=TRUE)
show_color_distance(sort_colors(c(given, new_colors)))

given2 <- c(given, new_colors);
color_pie(given2)
new_colors2 <- add_colors(unname(given2), n=n, do_plot=TRUE)
new_colors2 <- add_colors(unname(given2), n=n, do_plot=TRUE, dist_threshold=15)
new_colors2 <- add_colors(unname(given2), n=n, do_plot=TRUE, dist_threshold=20)
names(new_colors2) <- seq_along(new_colors2) + 2;
show_color_distance(sort_colors(c(given2, new_colors2)), cluster_data=TRUE)

jamba::showColors(list(
   given=sort_colors(given),
   `add 2`=sort_colors(c(given, new_colors)),
   `add 2 more`=sort_colors(c(given2, new_colors2))))

new_colors4 <- add_colors(given, n=4, do_plot=TRUE, dist_threshold=20)
names(new_colors4) <- seq_along(new_colors4);
show_color_distance(sort_colors(c(given, new_colors4)))

jamba::showColors(list(given=given,
   `add 2`=sort_colors(c(given, new_colors)),
   `add 2 more`=sort_colors(c(given2, new_colors2)),
   `add 4 upfront`=sort_colors(c(given, new_colors4))))

# Todo: consider ensuring desaturated colors are somewhat different also
show_color_distance(color_distance(given, new_colors), pc=c(given, new_colors))
hm1 <- show_color_distance(sort_colors(c(given, new_colors)), pc=unname(c(given, new_colors)))
hm1
hm2 <- show_color_distance(colorspace::desaturate(amount=0.7, sort_colors(c(given, new_colors))))
hm3 <- show_color_distance(colorspace::desaturate(amount=1, sort_colors(c(given, new_colors))))
hm1 + hm2 + hm3

# test commoon themes
given <- c(DM="dodgerblue3", CTL="gold")
add_colors(unname(given), n=3, do_plot=TRUE)

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