getColorRamp: get color ramp by name, color, or function
In jmw86069/jamba: Jam Base Methods

getColorRamp

R Documentation

get color ramp by name, color, or function

Description

get color ramp by name, color, or function

Usage

getColorRamp(
  col,
  n = 15,
  trimRamp = c(0, 0),
  gradientN = 15,
  defaultBaseColor = "grey99",
  reverseRamp = FALSE,
  alpha = TRUE,
  gradientWtFactor = NULL,
  dex = 1,
  lens = 0,
  divergent = NULL,
  verbose = FALSE,
  ...
)

Arguments

`col`	one of the following: `character` vector of two or more R colors. A color gradient will be defined using these colors in order with `colorRampPalette()`. `character` vector length=1 with one R color. A color gradient is defined from `defaultBaseColor` to `col` using `color2gradient()`. To adjust the range of light to dark luminance, use the `dex` argument, where higher values increase the range, and lower values decrease the range. `character` vector length=1, with one recognized color ramp name: any color palette from `rownames(RColorBrewer::brewer.pal.info())`; any color palette function name from `viridis`; any color palette from `colorjam::jam_linear()` or `colorjam::jam_divergent()`. `character` vector length=1, with one color function name, for example `col="rainbow_hcl"`. Input is equivalent to supplying one color `function`, see below. `function` whose first argument expects `integer` number of colors to return, for example `col=viridis::viridis` defines the function itself as input. `function` derived from `circlize::colorRamp2()`, recognized by having attribute names `"breaks"` and `"colors"`. Note that only the colors are used for the individual color values, not the break points.
`n`	`integer` number of output colors to return, or NULL if the output should be a color function in the form `⁠function(n)⁠` which returns `n` colors.
`trimRamp`	`integer` vector, expanded to length=2 as needed, which defines the number of colors to trim from the beginning and end of the color vector, respectively. When `reverseRamp=TRUE`, the colors are reversed before the trimming is applied. If the two `trimRamp` values are not identical, symmetric divergent color scales will no longer be symmetric.
`gradientN`	`integer` number of colors to expand gradient colors prior to trimming colors.
`defaultBaseColor`	`character` vector indicating a color from which to begin a color gradient, only used when col is a single color.
`reverseRamp`	`logical` indicating whether to reverse the resulting color ramp. This value is ignored when a single value is supplied for col, and where "_r" or "_rev" is detected as a substring at the end of the character value.
`alpha`	`logical` indicating whether to honor alpha transparency whenever `colorRampPalette` is called. If colors contain no alpha transparency, this setting has no effect, otherwise the alpha value is applied by `grDevices::colorRampPalette()` using a linear gradient between each color.
`gradientWtFactor`	`numeric` value used to expand single color input to a gradient, using `color2gradient()`, prior to making a full gradient to the `defaultBaseColor`. Note that `dex` is the preferred method for adjusting the range of light to dark for the given color `col`.
`dex`	`numeric` darkness expansion factor, used only with input `col` is a single color, which is then split into a color gradient using `defaultBaseColor` by calling `color2gradient()`. The `dex` factor adjusts the range of dark to light colors, where higher values for `dex` increase the range, making the changes more dramatic.
`lens`, `divergent`	arguments sent to `warpRamp()` to apply a warp effect to the color ramp, to compress or expand the color gradient: `lens` scales the warp effect, with positive values compressing colors toward baseline and negative values expanding colors near baseline; `divergent` is a logical indicating whether the middle color is considered the baseline.
`verbose`	`logical` whether to print verbose output
`...`	additional arguments are ignored.

Details

This function accepts a color ramp name, a single color, a vector of colors, or a function names, and returns a simple vector of colors of the appropriate length, suitable as input to a number of plotting functions.

When n is NULL, this function returns a color function, wrapped by grDevices::colorRampPalette(). The colors used are defined by gradientN, so the grDevices::colorRampPalette() function actually uses a starting palette of gradientN number of colors.

When n is an integer greater than 0, this function returns a vector of colors with length n.

When col is a single color value, a color gradient is created by appending defaultColorBase to the output of color2gradient(..., n=3, gradientWtFactor=gradientWtFactor). These 4 colors are used as the internal palette before applying grDevices::colorRampPalette() as appropriate. In this case, gradientWtFactor is used to adjust the strength of the color gradient. The intended use is: getColorRamp("red", n=5). To remove the leading white color, use getColorRamp("red", n=5, trimRamp=c(1,0)).

When col contains multiple color values, they are used to define a color ramp directly.

When col is not a color value, it is compared to known color palettes from RColorBrewer::RColorBrewer and viridisLite, and will use the corresponding color function or color palette.

When col refers to a color palette, the suffix "_r" may be used to reverse the colors. For example, getColorRamp(col="RdBu_r", n=9) will recognize the RColorBrewer color palette "RdBu", and will reverse the colors to return blue to red, more suitable for heatmaps where high values associated with heat are colored red, and low values associated with cold are colored blue.

The argument reverseRamp=TRUE may be used to reverse the returned colors.

Color functions from viridisLite are recognized: "viridis", "cividis", "inferno", "magma", "plasma".

The argument trimRamp is used to trim colors from the beginning and end of a color ramp, respectively. This mechanism is useful to remove the first or last color when those colors may be too extreme. Note that internally, colors are expanded to length gradientN, then trimmed, then the corresponding n colors are returned.

The trimRamp argument is also useful when returning a color function, which occurs when n=NULL. In this case, colors are expanded to length gradientN, then are trimmed using the values from trimRamp, then the returned function can be used to create a color ramp of arbitrary length.

Note that when reverseRamp=TRUE, colors are reversed before trimRamp is applied.

By default, alpha transparency will be maintained if supplied in the input color vector. Most color ramps have no transparency, in which case transparency can be added after the fact using alpha2col().

Examples

# get a gradient using red4
red4 <- getColorRamp("red4");
showColors(getColorRamp(red4));

# make a custom gradient
BuOr <- getColorRamp(c("dodgerblue","grey10","orange"));
showColors(BuOr);
colorList <- list(red4=red4, BuOr=BuOr);

# If RColorBrewer is available, use a brewer name
if (suppressPackageStartupMessages(require(RColorBrewer))) {
   RdBu <- getColorRamp("RdBu");
   RdBu_r <- getColorRamp("RdBu_r");
   colorList <- c(colorList, list(RdBu=RdBu, RdBu_r=RdBu_r));
   showColors(RdBu);
}

if (suppressPackageStartupMessages(require(viridis))) {
   viridisV <- getColorRamp("viridis");
   colorList <- c(colorList, list(viridis=viridisV));
}

# for fun, put a few color ramps onto one plot
showColors(colorList, cexCellnote=0.7);

showColors(list(`white background\ncolor='red'`=getColorRamp("red"),
   `black background\ncolor='red'`=getColorRamp("red", defaultBaseColor="black"),
   `white background\ncolor='gold'`=getColorRamp("gold"),
   `black background\ncolor='gold'`=getColorRamp("gold", defaultBaseColor="black")))

jmw86069/jamba documentation built on Oct. 9, 2024, 10:52 a.m.