ursa (version 3.11.1)

legend_colorbar: 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)

Value

NULL

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.

Author

Nikita Platonov

Details

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

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

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()