sl.plot.colbar: Plot Colourbar

In helgegoessling/spheRlab: Spherical Geometry, Analysis, and Plotting of Geoscientific Data on Arbitrary Grids

Plot Colourbar

Description

Plot a spheRlab colourbar, vertically or horizontally, with a number of options.

Usage

sl.plot.colbar(colbar, categorical = FALSE, breaks = NULL, vertical = TRUE, labels.at = NULL, labels.num = min(length(breaks),5), labels = NULL, labels.side = "bottom", labels.cex = 1, labels.signif = 3, ticks.length = 1, ticks.mirrored = FALSE, ratio = 0.1, triag.ends = FALSE, device = "pdf", do.init = TRUE, do.init.device = TRUE, do.close.device = do.init.device, file.name = paste0("~/sl.plot.colbar.",device), width = 6, xshift = 0, yshift = 0, len = 0.6, units = NULL, units.xy = NULL, labels.col = "black")

Arguments

colbar	a spheRlab colourbar of length N (as returned by sl.colbar), or a list including such a colourbar as an element named 'colbar'. In the latter case, the arguments categorical, breaks, and labels are ignored and taken from colbar if colbar also includes accordingly named elements.
categorical	a logical value specifying whether the colourbar is categorical. If TRUE, labels are placed at colour centres. Default is FALSE. Ignored if colbar is a list with elements 'colbar' as well as 'categorical'.
breaks	a vector of length N-1 specifying the breaks corresponding to colbar. Ignored if categorical=TRUE. Ignored if colbar is a list with elements 'colbar' as well as 'breaks'.
vertical	a logical value specifying whether the colourbar is to be plotted vertically (default). If vertical=FALSE, a horizontal colourbar is plotted.
labels.at	NULL or a vector of length N-1 (or N if categorical=TRUE) with logical values specifying which breaks (or colours) are to be labelled. If NULL (default) and categorical=FALSE, the argument labels.num is used to place labels automatically in a quasi equidistant manner. If NULL (default) and categorical=TRUE, each colour is labelled.
labels.num	a scalar specifiying how many labels are to be drawn in a quasi equidistant manner. Used only if labels.at=NULL and categorical=FALSE. Default is labels.num=min(length(breaks),9). To plot labels at all breaks, set labels.num=NULL (as well as labels.at=NULL).
labels	NULL or a vector specifying the labels. If categorical=FALSE, the length must be N-1 and the labels correspond to the colour breaks; if NULL (default), labels are derived from breaks. If categorical=TRUE, the length must be N and the labels correspond to colour centres; if NULL (default), labels are 1:N. Note that this vector has the same length as breaks (or colbar), meaning that it must include pseudo entries even for breaks (or colours) that are not labelled. Ignored if colbar is a list with elements 'colbar' as well as 'labels'.
labels.side	NOT YET USED! - a character specifying the side of the colourbar at which the labels are to be placed.
labels.cex	a scalar specifying the relative size of the labels.
labels.signif	an integer specifying the number of significant digits to be printed for the labels. Used only if categorical=FALSE. Default is labels.signif=3.
ticks.length	NOT YET USED!
ticks.mirrored	NOT YET USED!
ratio	a scalar specifying the ratio of width and length of the colourbar. By default ratio=0.1.
triag.ends	a logical value indicating whether the ends of the colourbar (that is, the last colour polygons) shall be triangular. By default triag.ends=FALSE.
device	a character specifying which graphics device to use. Default is device='pdf'. Ignored if do.init.device=FALSE.
do.init	a logical value indicating whether or not an initial call of plot shall be executed. Default is do.init=TRUE.
do.init.device	a logical value indicating whether or not to initialise a device as specified by device. Default is do.init.device=do.init. If do.init.device=FALSE but do.init=TRUE, the plot will be initialised in the standard graphical device.
do.close.device	a logical value specifying whether to call dev.off() to close the corresponding device in the end. Default is do.close.device=do.init.device.
file.name	a character specifying the output file name of the figure. By default file.name=paste0("~/sl.plot.colbar.",device).
width	a scalar specifying the width of the figure.
xshift	a scalar specifying how far the colourbar shall be shifted from the plot coordinate origin in x-direction. Default is xshift=0.
yshift	a scalar specifying how far the colourbar shall be shifted from the plot coordinate origin in y-direction. Default is yshift=0.
len	a scalar specifying the (absolute) length of the colourbar. Default is 0.6. If do.init=TRUE, in which case the plot domain ranges from -0.5 to 0.5 in both x and y direction, len also corresponds to the colourbar length relative to the plot size.
units	a character specifying a units string to be added to the plot. Default is "", in which case no units are added.
units.xy	a two-element numeric vector specifying the relative (scaled by len) x and y coordinates of the units relative to the colourbar. If not specified, units.xy=c(0,1.2) for vertical colourbars (units are added above the upper end) and units.xy=c(1.2,0) for vertical colourbars (units are added next to the right end).
labels.col	the colour of the labels (and units).

Details

By default, colourbars in spheRlab follow the philosophy that they are plotted separately of the fields they annotate. In this case, combining a plotted field and its colourbar subsequently is left to the user and his or her choice of external software (e.g., OpenOffice or the like). This increases the simplicity and flexibility of plot handling within spheRlab.

It is also possible to add a colourbar to an existing plot by setting do.init=FALSE and adjusting xshift, yshift, and len. If adding to a spheRlab plot initialised with sl.plot.init or variants thereof, note that the plot x-y-ranges are stored in the list returned by the initialising function call in the elements xlim and ylim.

Value

An integer giving the device into which the figure was plotted.

Note

This function still has some unused arguments that should be implemented at some point.

Author(s)

Helge Goessling

See Also

sl.colbar, sl.num2colbar, sl.view.colbar

Examples

cb = sl.colbar(cols=rgb(c(1,0,0),c(.5,.5,.5),c(0,0,1)),N=10)
breaks = seq(.1,.9,.1)
sl.plot.colbar(colbar=cb,breaks=breaks,do.init.device=F,units="(K)")

helgegoessling/spheRlab documentation built on April 8, 2024, 8:34 a.m.