assign_numeric_colors: Assign color function to a numeric vector

In jmw86069/platjam: Platform Jam, biological platform importers.

Assign color function to a numeric vector

Description

Assign color function to a numeric vector

Usage

assign_numeric_colors(
  x,
  color,
  color_max = NULL,
  ratio_for_zero_baseline = 3,
  lower_range_expansion = 0.2,
  base_color = "#fff6f4",
  restrict_pretty_range = TRUE,
  lens = 1,
  verbose = FALSE,
  ...
)

Arguments

x	numeric or integer vector
color	character color
color_max	numeric optional fixed value to define the numeric value associated with the maximum color gradient color.
ratio_for_zero_baseline	numeric indicating the ratio of max to min numeric range, above which the baseline value should include zero. This argument is intended when values include c(3, 100) and the numeric range is more reasonable to include zero; compared to values between c(185, 192) where it makes more sense to apply the color gradient only near those values, and not to use c(0, 192).
lower_range_expansion	numeric used when the baseline is not zero, see ratio_for_zero_baseline, to adjust the baseline below the lowest value by this fraction of the span of values (max - min) below the lowest value. The intention is to prevent assigning white base_color to this lowest value, instead it should use a very pale variant of color.
base_color	character string used as the baseline color when defining a color gradient to color. This value is passed to jamba::getColorRamp(..., defaultBaseColor).
restrict_pretty_range	logical indicating whether the values returned by pretty() should be filtered by range(x), excluding any numeric breaks outside that range. The practical effect is that it reduces labels displayed by jamba::showColors() or by color legends drawn by ComplexHeatmap::Heatmap().
lens	numeric value that defines the intensity of color gradient, with higher values increasing the rate of increase in color intensity, and negative values decreasing this rate. This argument is passed to jamba::getColorRamp().
...	additional arguments are ignored.

Details

This function is called internally by design2colors(). It takes a numeric vector as input, and applies a color gradient defined by color across the range of numeric values.

When there are negative values, a divergent color scale is generated:

• When color is a single R color, it is used as the positive color gradient. A complementary color is chosen as the negative color using quick_complement_color(). The middle color is base_color.

• When color is a named color gradient, it is assumed to be a divergent gradient. The middle color of the gradient is assigned to zero, and the color gradient is symmetric above and below zero.

The numeric range is either defined by the data x, or when color_max is supplied, it is used to define the numeric value at which (or higher) the maximum color is assigned.

• When color_max is not assigned, it is defined as max(abs(x)).

• If there are negative values, the color gradient will be defined from -color_max to color_max, with the middle color assigned to zero, as described above.

• If there are only positive values, the baseline will be defined using ratio_for_zero_baseline, and the maximum color will be defined at color_max (and higher).

The ratio_for_zero_baseline is used only when there are no negative values, since it determines whether the color gradient should be applied starting at zero, or based upon min(x). When the lowest value is less than ratio_for_zero_baseline * color_max the color gradient is applied starting from zero; otherwise the baseline uses min(x). In the latter case, non-zero baseline, the lowest value is extended by multiplying lower_range_expansion by the span of the numeric range, in order to prevent the lowest non-zero value from being a blank color defined by base_color.

Value

function as defined by circlize::colorRamp2() which takes a numeric vector as input, and returns character vector of colors as output. The attributes described below are used to show a suitable summary of colors in jamba::showColors(); and are used by jamses::heatmap_se() to define a usable color legend with reasonable number of labels. The function also contains two important attributes:

• "breaks": numeric values at break positions used when the color function was defined. Note the values are taken from the color function environment, so modifying breaks directly will not affect the color function output.

• "colors": a matrix of colors in rgb format, with columns red, blue, green, and numeric values ranging from 0 to 1. The number of rows equals the length of color breaks.

See Also

Other jam color functions: design2colors(), df_to_numcolors(), mean_hue(), print_color_list(), quick_complement_color()

jmw86069/platjam documentation built on Sept. 26, 2024, 3:31 p.m.