colormap {oce} | R Documentation |
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.
colormap(z, zlim, zclip=FALSE, breaks, col=oce.colorsJet, name, x0, x1, col0, col1, blend=0, missingColor, debug=getOption("oceDebug"))
z |
an optional vector or other set of numerical values to be examined.
If |
zlim |
optional vector containing two numbers that specify the |
zclip |
logical, with |
breaks |
an optional indication of break points between colour levels
(see |
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
|
name |
an optional string naming a built-in colormap (one of
|
x0, x1, col0, col1 |
Vectors that specify a colour map. They must all be
the same length, with |
blend |
a number indicating how to blend colours within each band. This
is ignored except when |
missingColor |
colour to use for missing values. If not provided, this
will be |
debug |
a flag that turns on debugging. Set to 1 to get a moderate amount of debugging information, or to 2 to get more. |
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.
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.
Dan Kelley
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.
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)