lut: Lookup Tables

In spatstat/spatstat.geom: Geometrical Functionality of the 'spatstat' Family

Lookup Tables

Description

Create a lookup table.

Usage

lut(outputs, ..., range=NULL, breaks=NULL, inputs=NULL,
    gamma=1, compress=NULL, decompress=NULL)

Arguments

outputs	Vector of output values.
...	Ignored.
range	Interval of numbers to be mapped. A numeric vector of length 2, specifying the ends of the range of values to be mapped. Incompatible with breaks or inputs.
inputs	Input values to which the output values are associated. A factor or vector of the same length as outputs. Incompatible with breaks or range.
breaks	Breakpoints for the lookup table. A numeric vector of length equal to length(outputs)+1. Incompatible with range or inputs.
gamma	Exponent for 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 lookup table. See section on Nonlinear lookup tables.
decompress	Experimental. An R function giving the inverse function of compress, if compress is specified.

Details

A lookup table is a function, mapping input values to output values.

The command lut creates an object representing a lookup table, which can then be used to control various behaviour in the spatstat package. It can also be used to compute the output value assigned to any input value.

The argument outputs specifies the output values to which input data values will be mapped. It should be a vector of any atomic type (e.g. numeric, logical, character, complex) or factor values.

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 outputs. The entries of inputs can be any atomic type (e.g. numeric, logical, character, complex) or factor values. The resulting lookup table associates the value inputs[i] with the value outputs[i]. The argument outputs 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 mapped to an entry of outputs. (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 lookup tables for the case where compress and decompress are given.)

• If breaks is given, then it determines intervals of the real number line which are mapped to each output value. 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 value outputs[i]. The argument outputs should have length equal to length(breaks) - 1.

It is also permissible for outputs to be a single value, representing a trivial lookup table in which all data values are mapped to the same output value.

The result is an object of class "lut". There is a print method for this class. Some plot commands in the spatstat package accept an object of this class as a specification of a lookup table.

The result is also a function f which can be used to compute the output value assigned to any input data value. That is, f(x) returns the output value assigned to x. This also works for vectors of input data values.

Value

A function, which is also an object of class "lut".

Nonlinear lookup tables

If the arguments compress and decompress are given, they define a transformation of the range of numbers. A typical example would be a logarithmic lookup table defined by compress = log10 and decompress = function(x) { 10^xg }.

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 lookup table with compress=log10, the specified range will be divided into intervals which are equal on a logarithmic scale.

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

.

See Also

colourmap.

Examples

  ## lookup table for real numbers, using breakpoints
  cr <- lut(factor(c("low", "medium", "high")), breaks=c(0,5,10,15))
  cr
  cr(3.2)
  cr(c(3,5,7))
  ## lookup table for discrete set of values
  ct <- lut(c(0,1), inputs=c(FALSE, TRUE))
  ct(TRUE)
  ## logarithmic lookup table
  cl <- lut(letters[1:3], range=c(0.1, 100), compress=log10)

spatstat/spatstat.geom documentation built on June 14, 2025, 5:50 a.m.