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 breaks or inputs.

inputs

Values to which the colours are associated. A factor or vector of the same length as col. Incompatible with breaks or range.

breaks

Breakpoints for the colour map. A numeric vector of length equal to length(col)+1. Incompatible with range or inputs.

gamma

Exponent for the gamma correction, when range is given. A single positive number. See Details.

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 compress, if compress is specified.

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.

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:

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)

[Package spatstat.geom version 3.5-0 Index]