colourmap: Colour Lookup Tables
In spatstat.geom: Geometrical Functionality of the 'spatstat' Family

colourmap

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.

If inputs is given, then it should be a vector or factor, of the same length as col. The entries of inputs can be any atomic type (e.g. numeric, logical, character, complex) or factor values. The resulting colour map associates the value inputs[i] with the colour col[i]. The argument col should have the same length as inputs.
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 in col. (If gamma is given, then the bands are equally spaced on a scale where the original values are raised to the power gamma.) (See the section on Nonlinear colour maps for the case where compress and decompress 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 between breaks[i] and breaks[i+1] will be mapped to the colour col[i]. The argument col should have length equal to length(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 function log10, then decompress is taken to be its inverse function(x) { 10^x }.
If compress is a cumulative distribution function (of class "ecdf", "ewcdf" or "interpolatedCDF") then decompress is taken to be its inverse function decompress = quantilefun(compress).

Author(s)

\spatstatAuthors

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)

spatstat.geom documentation built on June 8, 2025, 1:27 p.m.