| color.scale.cont {ivue} | R Documentation |
Reusable Color Scales
Description
Construct a scale once to keep colors comparable across scenes. Scale construction and mapping do not load rgl or create a graphics device.
Usage
color.scale.cont(
values,
mode = c("continuous", "binned"),
palette = NULL,
color.map = NULL,
limits = NULL,
center = NULL,
breaks = NULL,
n.bins = 10L,
method = c("uniform", "quantile"),
winsor.p = 0,
oob = c("squish", "censor", "error"),
na.color = "gray80",
digits = NULL
)
color.scale.groups(
groups,
colors = NULL,
na.color = "gray80",
unknown = c("error", "missing")
)
map.colors(x, scale)
Arguments
values |
Numeric reference values. Missing values are allowed; infinity is rejected. Automatic limits are fitted to these reference values only. |
mode |
Continuous interpolation (default) or explicit bins. |
palette |
R colors or a function of the requested number of colors. NULL uses the Viridis HCL palette. Numeric palette indices are resolved when fitting the scale, so later session palette changes have no effect. |
color.map |
Optional function of numeric values returning R colors. Mutually exclusive with palette. Must be deterministic and pointwise: a value's color cannot depend on other values, their order, or call count. Receives data-unit values after out-of-bounds handling, not normalized palette positions. Observations, legend ticks, and the ramp are mapped in separate calls. The caller is responsible for this contract. |
limits |
Two finite, nondecreasing numeric limits. Equal limits are permitted for constant data. |
center |
Optional reference value for a continuous diverging scale. Supply an appropriate diverging palette explicitly. Automatic limits are symmetric about center; explicit limits must contain it strictly. With palette, center maps to the palette midpoint. With color.map, center can affect automatic limits but does not transform the values passed to the callback. |
breaks |
Strictly increasing numerical bin boundaries, or NULL. |
n.bins |
Positive number of requested bins. |
method |
Uniform or quantile bin boundaries. |
winsor.p |
Explicit tail probability used when fitting uniform bins. Zero (default) disables winsorization; must be less than 0.5. |
oob |
Out-of-bounds handling: squish to limits, use missing color, or error. |
na.color |
Color for missing values and censored out-of-bounds values. |
digits |
NULL (default) increases significant digits from 3 up to 17 until distinct legend boundaries/ticks have distinct labels. An explicit integer fixes precision and warns if labels become ambiguous. Does not change bin calculations. |
groups |
Reference group labels or a factor. Factors retain level order; other inputs use first-occurrence order. Missing factor levels and values use na.color, distinct from the literal group "NA". Empty strings are valid groups. Legend labels are quoted when empty strings or a group named "Missing" occur, keeping them distinct from the missing-value legend entry. |
colors |
Optional named group colors, covering all nonmissing reference levels. Names must be unique and nonmissing; an empty name identifies the empty-string group. Numeric colors are fixed when the scale is fitted. |
unknown |
Whether unseen groups raise an error or use the missing color. |
x |
Values or groups to map, according to the scale type. |
scale |
A scale constructed by |
Details
Prefer a palette and fixed limits for comparable views. A custom
color.map must apply the same rule to each value regardless of the batch.
For example, function(x) ifelse(x < 0, "blue", "red") is pointwise.
A mapper that computes range(x), ranks, or quantiles from the current
batch to choose its colors is not supported: it can disagree with its own
legend and assign different colors to the same value in different views,
even without mutable external state. Fit such reference quantities once
and capture them in a fixed mapping function instead.
Value
A scale of class ivue_color_scale. map.colors() returns a list
containing row-aligned colors, a legend data frame (label, color,
count), and the scale. Continuous legend ticks have NA counts; binned and
group counts describe the mapped input. A Missing entry is added as needed.
See Also
plot3D.cont(), plot3D.groups(), ivue-package,
Finding your way around ivue,
Shared-scale recipe.
Examples
sc <- color.scale.cont(c(-1, 0, 1))
map.colors(c(-1, 0.5, NA), sc)
groups <- factor(c("low", "high", "low"), levels = c("low", "high"))
group.scale <- color.scale.groups(groups, c(low = "blue", high = "red"))
map.colors(groups, group.scale)
fixed.map <- function(x) ifelse(x < 0, "blue", "red")
custom <- color.scale.cont(c(-2, 4), color.map = fixed.map, limits = c(-2, 4))
map.colors(c(-1, 0, 2), custom)$colors