symbolmap {spatstat.geom} | R Documentation |
Graphics Symbol Map
Description
Create a graphics symbol map that associates data values with graphical symbols.
Usage
symbolmap(..., range = NULL, inputs = NULL,
transform = NULL, compress = transform, decompress = NULL)
Arguments
... |
Named arguments specifying the graphical parameters. See Details. |
range |
Optional. Range of numbers that are mapped.
A numeric vector of length 2 giving the minimum and maximum
values that will be mapped.
Incompatible with |
inputs |
Optional. A vector containing all the data values
that will be mapped to symbols.
Incompatible with |
transform |
Optional. Experimental.
An R function which should applied to input data for the symbol map
before the graphics parameters |
compress |
Optional. Experimental. An R function determining a nonlinear transformation of the domain of the symbol map, to be used when the symbol map is plotted. See section on Nonlinear transformation. |
decompress |
Experimental.
An R function giving the inverse function of |
Details
A graphical symbol map is an association between
data values and graphical symbols.
The command symbolmap
creates an object of class
"symbolmap"
that represents a graphical symbol map.
Once a symbol map has been created, it can be applied to any suitable data to generate a plot of those data. This makes it easy to ensure that the same symbol map is used in two different plots. The symbol map can be plotted as a legend to the plots, and can also be plotted in its own right.
The possible values of data that will be mapped
are specified by range
or inputs
.
if
range
is given, it should be a numeric vector of length 2 giving the minimum and maximum values of the range of numbers that will be mapped. These limits must be finite.if
inputs
is given, it should be a vector of any atomic type (e.g. numeric, character, logical, factor). This vector contains all the possible data values that will be mapped.If neither
range
norinputs
is given, it is assumed that the possible values are real numbers.
The association of data values with graphical symbols
is specified by the other arguments ...
which are given in name=value
form.
These arguments specify the kinds of symbols that will be
used, the sizes of the symbols, and graphics parameters for
drawing the symbols.
Each graphics parameter can be either a single
value, for example shape="circles"
,
or a function(x)
which determines the value
of the graphics parameter as a function of the data x
,
for example shape=function(x) ifelse(x > 0, "circles", "squares")
.
Colourmaps (see colourmap
) are also acceptable
because they are functions.
Currently recognised graphics parameters, and their allowed values, are:
- shape
-
The shape of the symbol: currently either
"circles"
,"squares"
,"arrows"
,"crossticks"
orNA
. This parameter takes precedence overpch
. (Crossticks are used only for point patterns on a linear network). - size
-
The size of the symbol: a positive number or zero.
- pch
-
Graphics character code: a positive integer, or a single character. See
par
. - cex
-
Graphics character expansion factor.
- cols
-
Colour of plotting characters.
- fg,bg
-
Colour of foreground (or symbol border) and background (or symbol interior).
- col,lwd,lty
-
Colour, width and style of lines.
- etch
-
Logical. If
TRUE
, each symbol is surrounded by a border drawn in the opposite colour, which improves its visibility against the background. Default isFALSE
. - direction,headlength,headangle,arrowtype
-
Numeric parameters of arrow symbols, applicable when
shape="arrows"
. Heredirection
is the direction of the arrow in degrees anticlockwise from thex
axis;headlength
is the length of the head of the arrow in coordinate units;headangle
is the angle subtended by the point of the arrow; andarrowtype
is an integer code specifying which ends of the shaft have arrowheads attached (0 means no arrowheads, 1 is an arrowhead at the start of the shaft, 2 is an arrowhead at the end of the shaft, and 3 is arrowheads at both ends).
A vector of colour values is also acceptable for the arguments
col,cols,fg,bg
if
range
is specified.
Value
An object of class "symbolmap"
.
Nonlinear transformation
The argument
transform
defines a transformation that will be applied to the input data for the symbol map.If
transform
is given, it should be an R function. All input data for the symbol map will first be transformed by this function, before the graphical parameters specified by...
are determined.A typical example would be a logarithmic symbol map defined by
transform = log10
together with something likesize = function(x) { 3 * x }
. This would mean that a numerical valuez
will be represented on the plot by a circle of diametersize(transform(z)) = 3 * log10(z)
on the physical scale of the plot.-
The arguments
compress
anddecompress
define a transformation of the range of numbers that is used only when the symbol map is plotted.A typical example would be a logarithmic symbol map defined by
compress = log10
anddecompress = function(x) { 10^x }
.The arguments
compress
anddecompress
have no effect on the interpretation of the other arguments. They only affect the way in which the symbol map is plotted byplot.symbolmap
. For a continuous symbol map, the range of input values is plotted on the compressed scale, but annotated on the original scale. See the Examples.
If transform
is given, then the default value of
compress
is the same function transform
. This reflects
the fact that, when the user has specified that the input data
should be transformed to another scale in order to determine their
graphical representation, it would
usually be appropriate to display the symbol map legend on the same
transformed scale. However this can be overridden by specifying
another value for compress
, including NULL
.
The arguments transform
, 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
plot.symbolmap
to plot the symbol map itself.
invoke.symbolmap
to apply the symbol map to some data
and plot the resulting symbols.
update.symbolmap
to change the symbol map.
There are methods for print
and summary
for symbol maps.
Examples
g <- symbolmap(inputs=letters[1:10], pch=11:20)
g1 <- symbolmap(range=c(0,100), size=function(x) x/50)
## squares and circles with area proportional to |x|
## For 'squares', size is side length; size = sqrt(area)
## For 'circles', size is diameter; size = sqrt(area * 4/pi)
g2 <- symbolmap(shape=function(x) ifelse(x > 0, "circles", "squares"),
size=function(x) sqrt(ifelse(x > 0,
abs(x)*4/pi,
abs(x))),
bg = function(x) ifelse(abs(x) < 1, "red", "black"))
colmap <- colourmap(topo.colors(20), range=c(0,10))
g3 <- symbolmap(pch=21, bg=colmap, range=c(0,10))
plot(g3)
## logarithmic symbol map
gm <- symbolmap(range=c(1,1000), pch=21, transform=log10,
size=function(x) { x + 1 })
## input value x is plotted as a circle of diameter = log10(x) + 1.
gm(100)
plot(gm, nsymbols=4)
## note logarithmic scale of legend, because compress=transform by default.
## logarithmic display scale only
gl <- symbolmap(range=c(1,1000), pch=21, compress=log10)
gl(10)
plot(gl, nsymbols=4)
gu <- symbolmap(range=c(1,1000), pch=21)
gu(10)
plot(gu, nsymbols=4)
## log transformation 'compress' does not affect symbol map itself