colorize: Create color table

In ursa: Non-Interactive Spatial Tools for Raster Processing and Visualization

Create color table

Description

colorize assigns color table to raster image.

Usage

colorize(obj, value = NULL, breakvalue = NULL, name = NULL, pal = NULL, inv = NA,
         stretch = c("default", "linear", "equal", "mean", "positive",
                     "negative", "diff", "category", "julian", "date", "time",
                     "slope", "conc", "sd", "significance", "bathy",
                     "grayscale", "greyscale", ".onetoone"),
         minvalue = NA, maxvalue = NA, byvalue = NA, ltail = NA, rtail = NA, tail = NA,
         ncolor = NA, nbreak = NA, interval = NA_integer_, ramp = TRUE, byte = FALSE,
         lazyload = TRUE, reset = FALSE, origin = "1970-01-01" ,format = "",
         alpha = "", colortable = NULL, verbose = FALSE, ...)
                          
palettize(...) ## wrapper for non-spatial vectors

Arguments

obj	ursaRaster object or one-dimension numeric or character vector.
value	Numeric. Values to be assigned to categories.
breakvalue	Numeric. Values to be assigned to intervals.
name	Character. Names of categories.
pal	Function or character. If function then value should corresponded to function, which creates a vector of colors. If character then values should correponded to R color names or hexadecimal string of the form "#RRGGBB" or "#RRGGBBAA".
inv	Logical. Invert sequence of colors.
stretch	Character. Either kind of value transformation ("linear", "equal") or pre-defined options with palette specification ("positive", "data", "significance", etc)
minvalue	Numeric. Lower range limit.
maxvalue	Numeric. Upper range limit.
byvalue	Numeric. Increment of the sequence from minvalue to maxvalue.
ltail	Numeric. Partition of omitted values at left tail.
rtail	Numeric. Partition of omitted values at right tail.
tail	Numeric. Partition of omitted values at both tail. If length of tail is 2 then left and right tails may differ.
ncolor	Numeric or interer. Number of desired colors (or categories).
nbreak	Numeric or interer. Number of desired separators between colors.
interval	Integer or logical. Logical is coerced to integer. How to underwrite categories? Value 0L means that for numeric data each color gradation corresponds to intervals but named as a single value (e.g., middle between low and high values). Value 1L means that values correspond to separators of color gradation. Value 2L is experimental for scales with zero. Default is NA: interval=0L for ramp=TRUE and interval=1L for ramp=FALSE.
ramp	Logical. Is color ramp required?
byte	Logical. Forcing to produce color table for storage in byte format (not more than 255 colors). Default is FALSE.
lazyload	Logical. If FALSE then raster is reclassified to categories. If TRUE then color table is created without any change to source raster and raster value just postponed for change. Default is TRUE.
reset	Logical. If TRUE and source raster has color table, then this color table is destroyed, and new one is created. Default is FALSE.
origin	Character. Origin for stretch="date" (passed to function as.Date) and stretch="time" (passed to function as.POSIXct). See desription of orogin in respective functions. Default is "1970-01-01".
format	Character. Format date/time objects for arguments stretch with values "date", "time", or "julian". Default is "" (character of length 0).
alpha	Character or numeric. The characteristics of transparency. If character, then hexadecimal values between "00" and "FF" are allowed, and then coerced to numeric value between 0 and 255. If numeric, and ⁠0 <= alpha <= 1⁠, then alpha is multiplied to 255. alpha=0 means full transparency, alpha=255 means full opacity. Default is ""; if palette has no alpha channel, then alpha is assign to "FF".
colortable	Object of class ursaColorTable or object of class ursaRaster with color table. Reference color table. Is specified, then all other arguments are ignored, expexted lazyload. Default is NULL (unspecified).
verbose	Logical. Some output in console. Primarily for debug purposes.
...	For colorize(): If pal is a function, and argument names are in the format "pal.*" then prefix "pal." is omitted, and the rest part is used for argument names, which are passed to pal function. For palettize(): Arguments, which are passed to colorize().

Details

palettize is a wrapper ursa_colortable(colorize(...)) to return color table for one-dimensional numeric or character vector.

colortable is designed to prepare pretty thematic maps.

Color rampimg (ramp=TRUE) is not quick in computatons and has no effective labelling. It is intoduced to visualize non-thematic maps, and it is assumed that labeling can be omitted for such maps.

The labelling implementation is based on some improvements of pretty function. The notation of intervals is mixed by brackets and comparative symbols, for example: "<=1.5","(1.5,2.5]","(2.5,3.5]",">3.5"

Reserved values for interval:

• 0L or FALSE - no interlavs. Values are interpreted as category, even if they are in non-nominal scale

• 1L or TRUE - each category corresponds to interval. The low limit of lowest category is -Inf. The high limit of highest category is +Inf

• 2L - different implementation of interval=1. In some cases may relult more pretty labeling.

  If breaks is numerical vector and colors has zero length, then it is assumed interal scaling, and interval=1L is assigned to unspecified interval

  Finite values of extreme intervals are neccessary sometimes, however this option is not implemented currently

Keywords for stretch to create pre-defined color tables:

• "positive" - lower limit is 0. Palette is "Oranges"

• "negative" - higher limit is 0. Palette is "Purples"

• "grayscale", "greyscale" - palette is "Greys". Usually used for raw satellite images.

• "mean" - designed for common thematic maps and for averaged map across set of maps. Palette is "Spectral"

• "sd" - designed for spatial mapping of standard deviation across set of maps. Palette is "YlGnBu"

• "diff" - diverge palette "RdBu". Absolute values of lower and upper limits are equal, zero is in the middle of palette. Designed for anomaly maps.

• "slope" - is similar to diff but without extreme colors, which are reserved for contouring of statistically significant areas.

• "significance" - desiged to illustrate statistically significant areas of slope. The realisation is colortable(obj, value=c(-0.999, -0.99, -0.95, -0.9, -0.5, +0.5, +0.9, +0.95, +0.99, +0.999), interval=1L, palname="RdBu")

• "category" - Values are interpreted in nominal scale. Palette is based on random colors from "Pairs" palette.

• "conc" - designed for visualization of sea ice concentration data, which have lower limit 0 and higher limit 100. Palette is "Blues"

• "bathy" - designed for ocean depth (bathymetry) maps. Internally colorize(obj, stretch="equal",interval=1L, palname="Blues", inv=TRUE) is used to detect the crossing from shelf waters to deep water basin. Better practice is to do second step with manual specification of value argument.

• "internal" - continuous colors, designed for conversion to greyscale with keeping of intensities.

• "default" - allowing to detect stretch by intuition, without any strong mathematical criteria

It is allowed manual correction of labels using followed code example: names(ursa_colortable(x)) <- c("a<=0","0<a<=1","a>1")

Value

Object of class ursaRaster with named character vector of item $colortable

Author(s)

Nikita Platonov [e-mail]

See Also

ursa_colortable, ursa_colortable<-

Examples

session_grid(NULL)
a <- pixelsize()-350
print(a)
b1 <- colorize(a,ramp=FALSE)
print(ursa_colortable(b1))
b2 <- colorize(a,interval=1,stretch="positive",ramp=FALSE)
print(ursa_colortable(b2))
b3 <- colorize(a,interval=2,stretch="positive",ramp=FALSE)
print(ursa_colortable(b3))
b4 <- colorize(a,value=c(150,250),interval=1)
print(ursa_colortable(b4))
names(ursa_colortable(b4)) <- c("x<=150","150<x<=250","x>250")
print(ursa_colortable(b4))
display(b4)

ursa documentation built on Sept. 30, 2024, 9:35 a.m.