legend_colorbar: Plot colorbar

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

Plot colorbar

Description

Functions draw single color bar outside of maps panels. legend_colorbar (without prefix dot) is a wrapper for non-public .legend_colorbar (with prefix dot)

Usage

legend_colorbar(...)

## non-public
.legend_colorbar(ct, units = "", labels = NA, align = NULL, shift = 1, cex = 1,
                 adj = NA, las = 1, forceLabel = FALSE, lomar = 0, himar = 0,
                 turn = FALSE, useRaster = NA, trim = 0L, abbrev = 24L,
                 opacity = NA, verbose = FALSE)

Arguments

...	Set of arguments, which are recognized via their names (using regular expressions) and classes. Passed to non-public .legend_colorbar, excepting argument colorbar: Matched pattern (legend_colorbar) Argument (.legend_colorbar) Description colorbar Prefix for indirect use (e.g., in display). Separated by a dot ".", e.g., colorbar.units="mbar". (ct)* ct See below. unit(s)* units See below. labels labels See below. align align See below. shift shift See below. cex cex See below. adj adj See below. las las See below. forceLabel forceLabel See below. lomar lomar See below. himar himar See below. turn turn See below. useRaster useRaster See below. trim trim See below. abbrev abbrev See below. opacity opacity See below. verb(ose)* verbose See below.
ct	ursaRaster object with color table or object of class ursaColorTable. First argument in legend_colorbar; name can be omitted.
units	Argument of class character or expression with matching name "unit(s)*" in legend_colorbar. Text, which is used as a caption for color bars. If character then caption is displayed in bold. Default is "": no caption.
labels	Argument of class integer or character with matching name "labels" in legend_colorbar. If labels is vector of length 1, then it is number of labels at the color bar, else vector of specified values. Default is NA: it means 11 labels for numerical values and 31 labels for categorical values, but this number can be reduced for perpendicular orientation to the axes to prevent label overlapping.
align	Argument of class numeric with matching name "align" in legend_colorbar. The indent for right alignment of labels. May be useful, if two or more color bars are located on the same side, but with different units and order of values. Can be specified by the string of maximal length or via legend_align. Default is NULL: right alignment of each color bar is independent.
shift	Argument of class numeric with matching name "shift" in legend_colorbar. Multiplier for manual correction of labels alignment in the case when automatical alignment is poor. Default is 1: no changes. If shift<1 then labels are shifted to the left. If shift>1 then labels are shifted to the right.
cex	Argument of class numeric with matching name "cex" in legend_colorbar. A numerical value giving the amount by which labels should be magnified relative to the default. Default is 1.
adj	Argument of class numeric with matching name "adj" in legend_colorbar. Adjustment for labels. For labels parallel to the axes, adj=0 means left or bottom alignment, and adj=1 means right or top alignment. Default is NA: for labels parallel to the axes adj=0.5, for labels perpendicular to the axis adj=1 for numeric and adj=0 for character.
las	Argument of values 0, 1, 2, 3 with matching name "adj" in legend_colorbar. The correspondence between directions of axis and labels. The same definition as for par(las=). Default is 1L.
forceLabel	Argument of class logical with matching name "forceLabel" in legend_colorbar. If TRUE then all labels are plotted regardless their possible overlapping.
lomar	Argument of class numeric, non-negative, with matching name "lomar" in legend_colorbar.Relative shifting of the lower (left or bottom) position of colorbar. Default is 0: the lower position is corresponded to the limit of panel(s). Positive value decreases length of colorbar.
himar	Argument of class numeric, non-negative, with matching name "himar" in legend_colorbar. Relative shifting of the higher (right or bottom) position of colorbar. Default is 0: the higher position is corresponded to the limit of panel(s). Positive value decreases length of colorbar.
turn	Argument of class logical with matching name "turn" in legend_colorbar. Default is FALSE: lower value is on left or bottom, higher value is on right or top. If turn=TRUE, then opposite order.
useRaster	Argument of class logical with matching name "useRaster" in legend_colorbar. Passed as argument useRaster to function image. Default is NA, which is interpreted as TRUE for "cairo" graphical device and as FALSE for "windows" graphical device (see description of argument type in png).
trim	Argument of values 0L, 1L, 2L with matching name "trim" in legend_colorbar. Determines behaviour for plotting marginal labels. If 0L, then marginal labels are displayed as is. If 1L, then marginal labels are shifted inside of color bar to prevent their outcrop to the panel(s) limits. If 2L then outctopped labels are not displayed.
abbrev	Argument of class integer or logical with matching name "abbrev" in legend_colorbar. TRUE is interpreted as default value. FALSE is interpreted as 0L. If positive, then labels are abbreviated, and this argument is passed as argument minlength to function abbreviate: abbreviate(label, minlength=abbrev, strict=TRUE). If abbreviation is failed (e.g., non-ASCII symbols), the subset is applied.
opacity	Argument of class integer or logical with matching name "abbrev" in legend_colorbar. Responses for shading of color bar. If FALSE or 0, then no shading. If TRUE or 1, then shading is forced. Default is NA; if semi-transparence is detected, then shading is applied.
verbose	Argument of class logical with matching name "verb(ose)*" in legend_colorbar. Value TRUE may provide some additional information on console. Default is FALSE.

Details

If units are expression, then possible way for formatting is:

units=as.expression(substitute(bold(degree*C)))

Value

NULL

Author(s)

Nikita Platonov [e-mail]

Examples

session_grid(NULL)
display(ursa_dummy(1),units="Required 99 labels; displayed less"
        ,colorbar.labels=99,las=3,gridline.trim=FALSE,colorbar.trim=1L)
cname <- c("Apple","Orange","Cherry","Blueberry","Strawberry","Currant")
a <- ursa_dummy(4)
b <- list(colorize(a[1],value=seq(50,200,length=length(cname))
                  ,name=cname)#,stretch="category")
         ,colorize(a[2]*10,ramp=FALSE),colorize(a[3]*100),colorize(a[4]/10))
la <- legend_align(b[3:4])
leg <- vector("list",10)
leg[[1]] <- list(1,"left")
leg[[2]] <- list(1,"right")
for (i in seq(4)) {
   leg[[i+2]] <- list("top",i)
   leg[[i+6]] <- list("bottom",i)
}
compose_open(layout=c(1,4),legend=leg,scale=NA,dev=FALSE) # use 'dev=TRUE' to check layout
compose_panel(b)
legend_colorbar(b[[1]],lomar=20,himar=0) ## "left"
legend_colorbar(b[[4]],labels=c(6,7.5,12,15,20)
               ,units="Manual set of labels") ## "right"
legend_colorbar(b[[1]],las=2,adj=0.5,turn=TRUE,lomar=6,himar=6
               ,units="Central adjustment; inverse order") ## ("top",1)
legend_colorbar(b[[2]],cex=0.9
               ,units="Horizontal labels can be overlapped") ## ("top",2)
legend_colorbar(b[[3]],las=3,align=la
               ,units="Increased width, but aligned -->") ## ("top",3)
legend_colorbar(b[[4]],las=3,align=la,labels=3
               ,units="<-- Reduced width, but aligned") ## ("top",4)
legend_colorbar(b[[1]],las=2,adj=0,shift=0.9,turn=FALSE,lomar=2,himar=10
               ,units="Left adjustement. Non-optimal; shifted") ## ("bottom",1)
legend_colorbar(b[[2]],las=3,adj=0
               ,units="But right adj. is default for numeric") ## ("bottom",2)
legend_colorbar(b[[3]],labels=99,las=3,trim=2L
               ,units="Required 99 labels, but displayed less") ## ("bottom",3)
legend_colorbar('Caption from named item'=b[[4]],labels=99) ## ("bottom",4)
compose_close()

ursa documentation built on April 3, 2025, 6 p.m.