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,
             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.

- Case A. Supply `z` but nothing else. In this case, `breaks` will be set to `pretty(z, 10)` and things are otherwise as in case 2.

- Case B. Supply `breaks`. In this case, `breaks` and `col` are used together to specify a colour scheme. If `col` is a function, then it is expected to take a single numerical argument that specifies the number of colours, and this number will be set to `length(breaks)-1`. Otherwise, `col` may be a vector of colours, and its length must be one less than the number of breaks. (NB. if `breaks` is given, then all other arguments except `col` and `missingColor` are ignored.) The figure below explains the (`breaks`, `col`) method of specifying a colour mapping. Note that there must be one more break than colour. This is the method used by e.g. `image`.

- Case C. Do not supply `breaks`, but supply `name` instead. This `name` may be the name of a pre-defined colour palette (`"gmt_relief"`, `"gmt_ocean"`, `"gmt_globe"` or `"gmt_gebco"`), or it may be the name of a file (including a URL) containing a colour map in the GMT format (see “References”). (NB. if `name` is given, then all other arguments except `z` and `missingColor` are ignored.)

- Case D. Do not supply either `breaks` or `name`, but instead supply each of `x0`, `x1`, `col0`, and `col1`. These values are specify a value-colour mapping that is similar to that used for GMT colour maps. The method works by using `seq` to interpolate between the elements of the `x0` vector. The same is done for `x1`. Similarly, `colorRampPalette` is used to interpolate between the colours in the `col0` vector, and the same is done for `col1`. The figure below explains the (`x0`, `x1`, `col0`, `col1`) method of specifying a colour mapping. Note that the each of the items has the same length. The case of `blend=0`, which has colour `col0[i]` between `x0[i]` and `x1[i]`, is illustrated below.

### Value

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

- `zcol`, a vector of colours for `z`, if `z` was provided, otherwise `"black"`

- `zlim`, a two-element vector suitable as the argument of the same name supplied to `image` or `imagep`

- `breaks` and `col`, vectors of breakpoints and colours, suitable as the same-named arguments to `image` or `imagep`

- `zclip` the provided value of `zclip`.

- `x0` and `x1`, numerical vectors of the sides of colour intervals, and `col0` and `col1`, vectors of corresponding colours. The meaning is the same as on input. The purpose of returning these four vectors is to permit users to alter colour mapping, as in example 3 in “Examples”.

- `missingColor`, a colour that could be used to specify missing values, e.g. as the same-named argument to `imagep`. If this is supplied as an argument, its value is repeated in the return value. Otherwise, its value is either `"gray"` or, in the case of `name` being given, the value in the GMT colour map specification.

### 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.

### 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-18 Index]