colourmap {spatstat.geom} | R Documentation |
Colour Lookup Tables
Description
Create a colour map (colour lookup table).
Usage
colourmap(col, ..., range=NULL, breaks=NULL, inputs=NULL, gamma=1,
compress=NULL, decompress=NULL)
Arguments
col |
Vector of values specifying colours |
... |
Ignored. |
range |
Interval to be mapped.
A numeric vector of length 2, specifying the endpoints of the
range of values to be mapped.
Incompatible with |
inputs |
Values to which the colours are associated.
A factor or vector of the same length as |
breaks |
Breakpoints for the colour map.
A numeric vector of length equal to |
gamma |
Exponent for the gamma correction, when |
compress |
Optional. Experimental. An R function determining a nonlinear transformation of the domain of the colour map. See section on Nonlinear colour maps. |
decompress |
Experimental.
An R function giving the inverse function of |
Details
A colour map is a mechanism for associating colours with data. It can be regarded as a function, mapping data to colours.
The command colourmap
creates an object representing
a colour map, which can then be used to control the plot commands
in the spatstat package. It can also be used to compute the
colour assigned to any data value.
The argument col
specifies the colours to which
data values will be mapped. It should be a vector
whose entries can be interpreted as colours by the standard
R graphics system. The entries can be string names of colours
like "red"
, or integers that refer to
colours in the standard palette, or strings containing
six-letter hexadecimal codes like "#F0A0FF"
.
Exactly one of the arguments range
, inputs
or breaks
must be specified by name.
-
If
inputs
is given, then it should be a vector or factor, of the same length ascol
. The entries ofinputs
can be any atomic type (e.g. numeric, logical, character, complex) or factor values. The resulting colour map associates the valueinputs[i]
with the colourcol[i]
. The argumentcol
should have the same length asinputs
. -
If
range
is given, then it determines the interval of the real number line that will be mapped. It should be a numeric vector of length 2. The interval will be divided evenly into bands, each of which is assigned one of the colours incol
. (Ifgamma
is given, then the bands are equally spaced on a scale where the original values are raised to the powergamma
.) (See the section on Nonlinear colour maps for the case wherecompress
anddecompress
are given.) -
If
breaks
is given, then it determines the precise intervals of the real number line which are mapped to each colour. It should be a numeric vector, of length at least 2, with entries that are in increasing order. Infinite values are allowed. Any number in the range betweenbreaks[i]
andbreaks[i+1]
will be mapped to the colourcol[i]
. The argumentcol
should have length equal tolength(breaks) - 1
.
It is also permissible for col
to be a single colour value,
representing a trivial colour map in which all data values are mapped to
the same colour.
The result is an object of class "colourmap"
.
There are print
and plot
methods for this class.
Some plot commands in the spatstat package accept an object
of this class as a specification of the colour map.
The result is also a function f
which can be used to compute
the colour assigned to any data value.
That is, f(x)
returns the character value of the colour assigned
to x
. This also works for vectors of data values.
Value
A function, which is also an object of class "colourmap"
and "lut"
.
Nonlinear colour maps
If the arguments compress
and decompress
are given,
they define a transformation of the range of numbers.
A typical example would be a logarithmic colour map defined
by compress = log10
and
decompress = function(x) { 10^x }
.
These functions have no effect on the interpretation of the
arguments range
, breaks
and inputs
. However,
if range
is given, then the range of values will be divided
into intervals which have equal length on the scale defined by
compress
. That is, the range of numbers determined by
compress(range)
will be evenly divided into intervals,
and these intervals will be mapped back to the original scale by
decompress
to determine the breaks
.
For a logarithmic colour map with compress=log10
,
the specified range will be divided into intervals which are equal
on a logarithmic scale.
The arguments compress
and decompress
affect the way
in which the colour map is plotted by plot.colourmap
.
For a continuous colour map, the range of input values is plotted on
the compressed scale, but annotated on the original scale.
See the Examples.
The arguments compress
and decompress
should be functions which are vectorised (i.e. if x
is a
vector then compress(x)
and
decompress(x)
are also vectors of the same length as x
)
and increasing (if x < y
then compress(x) < compress(y)
and decompress(x) < decompress(y)
.
The argument decompress
is not needed in the following cases:
If
compress
is the functionlog10
, thendecompress
is taken to be its inversefunction(x) { 10^x }
.If
compress
is a cumulative distribution function (of class"ecdf"
,"ewcdf"
or"interpolatedCDF"
) thendecompress
is taken to be its inverse functiondecompress = quantilefun(compress)
.
Author(s)
Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.
See Also
The plot method plot.colourmap
.
See the R help file on
colours
for information about the colours
that R recognises, and how to manipulate them.
To make a smooth transition between colours, see
interp.colourmap
.
To alter individual colour values, see
tweak.colourmap
.
To extract or replace all colour values, see
colouroutputs
.
See also restrict.colourmap
and rev.colourmap
.
See colourtools
for more tools to manipulate colour values.
See lut
for lookup tables.
Examples
## colour map for real numbers, using breakpoints
cr <- colourmap(c("red", "blue", "green"), breaks=c(0,5,10,15))
cr
cr(3.2)
cr(c(3,5,7))
## a large colour map
co <- colourmap(rainbow(100), range=c(-1,1))
co(0.2)
## colour map for discrete set of values
ct <- colourmap(c("red", "green"), inputs=c(FALSE, TRUE))
ct(TRUE)
## logarithmic colour map
cl <- colourmap(rainbow(25), range=c(0.1, 1000), compress=log10)
plot(cl)