Skip to contents

Add categorical colors to an existing color set

Source: R/colorjam-add-colors.R
add_colors.Rd

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 = TRUE,
  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.

Details

This function is actively evolving. The core goal is to take a set of categorical colors, and to add 'n' more colors using a color function such as rainbowJam(). It will add colors with maximum color distance, to provide as distinct a set of colors as possible, based upon the existing colors in use.

The existing colors can be provided from any source, it does not need to be generated by rainbowJam().

See also

Other colorjam assignment: col_div_xf(), col_linear_xf(), color_complement(), group2colors(), matrix2heatColors(), rainbowJamMulti(), vals2colorLevels(), vibrant_color_by_hue()

Examples

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

show_color_distance(c(given, new_colors), cluster_data=TRUE)


given2 <- c(given, new_colors);
color_pie(given2)


new_colors2 <- add_colors(unname(given2), n=n, dist_threshold=15)
color_pie(sort_colors(c(given2, new_colors2)))


new_colors2 <- add_colors(unname(given2), n=n, dist_threshold=20)
color_pie(sort_colors(c(given2, new_colors2)))


names(new_colors2) <- seq_along(new_colors2) + 2;
show_color_distance(sort_colors(c(given2, new_colors2)))


new_colors4 <- add_colors(given, n=4, dist_threshold=20)
names(new_colors4) <- seq_along(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))))


# test common themes
given <- c(DM="dodgerblue3", CTL="gold")
new6 <- add_colors(unname(given), n=6)
color_pie(sort_colors(c(given, new6)))