colormap {oce}R Documentation

Calculate colour map

Description

Map values to colours, for use in palettes and plots. There are many ways to use this function, and some study of the arguments should prove fruitful in cases that extend far beyond the examples.

Usage

colormap(z = NULL, zlim, zclip = FALSE, breaks, col = oce.colorsJet, name,
  x0, x1, col0, col1, blend = 0, missingColor,
  debug = getOption("oceDebug"))

Arguments

z

an optional vector or other set of numerical values to be examined. If z is given, the return value will contain an item named zcol that will be a vector of the same length as z, containing a colour for each point. If z is not given, zcol will contain just one item, the colour "black".

zlim

optional vector containing two numbers that specify the z limits for the colour scale. If provided, it overrides defaults as describe in the following. If name is given, then the range of numerical values contained therein will be used for zlim. Otherwise, if z is given, then its rangeExtended sets zlim. Otherwise, if x0 and x1 are given, then their range sets zlim. Otherwise, there is no way to infer zlim and indeed there is no way to construct a colormap, so an error is reported. It is an error to specify both zlim and breaks, if the length of the latter does not equal 1.

zclip

logical, with TRUE indicating that z values outside the range of zlim or breaks should be painted with missingColor and FALSE indicating that these values should be painted with the nearest in-range colour.

breaks

an optional indication of break points between colour levels (see image). If this is provided, the arguments name through blend are all ignored (see “Details”). If it is provided, then it may either be a vector of break points, or a single number indicating the desired number of break points to be computed with pretty(z, breaks). In either case of non-missing breaks, the resultant break points must number 1 plus the number of colours (see col).

col

either a vector of colours or a function taking a numerical value as its single argument and returning a vector of colours. The value of col is ignored if name is provided, or if x0 through col1 are provided.

name

an optional string naming a built-in colormap (one of "gmt_relief", "gmt_ocean", "gmt_globe" or "gmt_gebco") or the name of a file or URL that contains a colour map specification in GMT format, e.g. one of the .cpt files from http://www.beamreach.org/maps/gmt/share/cpt). If name is provided, then x0, x1, col0 and col1 are all ignored.

x0, x1, col0, col1

Vectors that specify a colour map. They must all be the same length, with x0 and x1 being numerical values, and col0 and col1 being colours. The colours may be strings (e.g. "red") or colours as defined by rgb or hsv.

blend

a number indicating how to blend colours within each band. This is ignored except when x0 through col1 are supplied. A value of 0 means to use col0[i] through the interval x0[i] to x1[i]. A value of 1 means to use col1[i] in that interval. A value between 0 and 1 means to blend between the two colours according to the stated fraction. Values exceeding 1 are an error at present, but there is a plan to use this to indicate subintervals, so a smooth palette can be created from a few colours.

missingColor

colour to use for missing values. If not provided, this will be "gray", unless name is given, in which case it comes from that colour table.

debug

a flag that turns on debugging. Set to 1 to get a moderate amount of debugging information, or to 2 to get more.

Details

This is a multi-purpose function that generally links (“maps”) numerical values to colours. The return value can specify colours for points on a graph, or breaks and col vectors that are suitable for use by drawPalette, imagep or image.

There are three ways of specifying colour schemes, and colormap works by checking for each condition in turn.

Value

A list containing the following (not necessarily in this order)

Author(s)

Dan Kelley

References

Information on GMT software is given at http://gmt.soest.hawaii.edu (link worked for years but failed 2015-12-12). Diagrams showing the GMT colour schemes are at http://www.geos.ed.ac.uk/it/howto/GMT/CPT/palettes.html (link worked for years but failed 2015-12-08), and numerical specifications for some colour maps are at http://www.beamreach.org/maps/gmt/share/cpt, http://soliton.vm.bytemark.co.uk/pub/cpt-city, and other sources.

See Also

Other things related to colors: colors, oce.colorsGebco, oce.colorsTwo

Examples

library(oce)
## Example 1. colour scheme for points on xy plot
x <- seq(0, 1, length.out=40)
y <- sin(2 * pi * x)
par(mar=c(3, 3, 1, 1))
mar <- par('mar') # prevent margin creep by drawPalette()
## First, default breaks
c <- colormap(y)
drawPalette(c$zlim, col=c$col, breaks=c$breaks)
plot(x, y, bg=c$zcol, pch=21, cex=1)
grid()
par(mar=mar)
## Second, 100 breaks, yielding a smoother palette
c <- colormap(y, breaks=100)
drawPalette(c$zlim, col=c$col, breaks=c$breaks)
plot(x, y, bg=c$zcol, pch=21, cex=1)
grid()
par(mar=mar)

## Not run: 
## Example 2. topographic image with a standard colour scheme
par(mfrow=c(1,1))
data(topoWorld)
cm <- colormap(name="gmt_globe")
imagep(topoWorld, breaks=cm$breaks, col=cm$col)

## Example 3. topographic image with modified colours,
## black for depths below 4km.
cm <- colormap(name="gmt_globe")
deep <- cm$x0 < -4000
cm$col0[deep] <- 'black'
cm$col1[deep] <- 'black'
cm <- colormap(x0=cm$x0, x1=cm$x1, col0=cm$col0, col1=cm$col1)
imagep(topoWorld, breaks=cm$breaks, col=cm$col)

## Example 4. image of world topography with water colorized
## smoothly from violet at 8km depth to blue
## at 4km depth, then blending in 0.5km increments
## to white at the coast, with tan for land.
cm <- colormap(x0=c(-8000, -4000,   0,  100),
               x1=c(-4000,     0, 100, 5000),
               col0=c("violet","blue","white","tan"),
               col1=c("blue","white","tan","yelloe"),
               blend=c(100, 8, 0))
lon <- topoWorld[['longitude']]
lat <- topoWorld[['latitude']]
z <- topoWorld[['z']]
imagep(lon, lat, z, breaks=cm$breaks, col=cm$col)
contour(lon, lat, z, levels=0, add=TRUE)
message("colormap() example 4 is broken")

## Example 5. visualize GMT style colour map
cm <- colormap(name="gmt_globe", debug=4)
plot(seq_along(cm$x0), cm$x0, pch=21, bg=cm$col0)
grid()
points(seq_along(cm$x1), cm$x1, pch=21, bg=cm$col1)

## End(Not run)

[Package oce version 0.9-22 Index]