# symbolmap

##### Graphics Symbol Map

Create a graphics symbol map that associates data values with graphical symbols.

##### Usage

`symbolmap(…, range = NULL, inputs = 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`

.- inputs
Optional. A vector containing all the data values that will be mapped to symbols. Incompatible with

`range`

.

##### 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`

nor`inputs`

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"`

or`NA`

. This parameter takes precedence over`pch`

.- 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 is`FALSE`

.- direction,headlength,headangle,arrowtype
Numeric parameters of arrow symbols, applicable when

`shape="arrows"`

. Here`direction`

is the direction of the arrow in degrees anticlockwise from the \(x\) 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; and`arrowtype`

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"`

.

##### 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.

##### Examples

```
# NOT RUN {
g <- symbolmap(inputs=letters[1:10], pch=11:20)
g1 <- symbolmap(range=c(0,100), size=function(x) x/50)
g2 <- symbolmap(shape=function(x) ifelse(x > 0, "circles", "squares"),
size=function(x) sqrt(ifelse(x > 0, x/pi, -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)
# }
```

*Documentation reproduced from package spatstat, version 1.56-1, License: GPL (>= 2)*