R: plot a Spatial Point Pattern

plot.ppp {spatstat} | R Documentation

## plot a Spatial Point Pattern

### Description

Plot a two-dimensional spatial point pattern

### Usage

     ## S3 method for class 'ppp'
    plot(x, main, ..., clipwin=NULL,
                        chars=NULL, cols=NULL,
                        use.marks=TRUE, which.marks=NULL,
                        add=FALSE, type=c("p","n"),
                        legend=TRUE,
                        leg.side=c("left", "bottom", "top", "right"),
                        leg.args=list(),
                        symap=NULL, maxsize=NULL, meansize=NULL, markscale=NULL,
                        zap=0.01,
                        show.window=show.all, show.all=!add, do.plot=TRUE,
                        multiplot=TRUE)

### Arguments

`x` | The spatial point pattern to be plotted. An object of class `"ppp"`, or data which can be converted into this format by `as.ppp()`.
`main` | text to be displayed as a title above the plot.
`...` | extra arguments that will be passed to the plotting functions `plot.default`, `points` and/or `symbols`. Not all arguments will be recognised.
`clipwin` | Optional. A window (object of class `"owin"`). Only this subset of the image will be displayed.
`chars` | plotting character(s) used to plot points.
`cols` | the colour(s) used to plot points.
`use.marks` | logical flag; if `TRUE`, plot points using a different plotting symbol for each mark; if `FALSE`, only the locations of the points will be plotted, using `points()`.
`which.marks` | Index determining which column of marks to use, if the marks of `x` are a data frame. A character or integer vector identifying one or more columns of marks. If `add=FALSE` then the default is to plot all columns of marks, in a series of separate plots. If `add=TRUE` then only one column of marks can be plotted, and the default is `which.marks=1` indicating the first column of marks.
`add` | logical flag; if `TRUE`, just the points are plotted, over the existing plot. A new plot is not created, and the window is not plotted.
`type` | Type of plot: either `"p"` or `"n"`. If `type="p"` (the default), both the points and the observation window are plotted. If `type="n"`, only the window is plotted.
`legend` | Logical value indicating whether to add a legend showing the mapping between mark values and graphical symbols (for a marked point pattern).
`leg.side` | Position of legend relative to main plot.
`leg.args` | List of additional arguments passed to `plot.symbolmap` or `symbolmap` to control the legend. In addition to arguments documented under `plot.symbolmap`, and graphical arguments recognised by `symbolmap`, the list may also include the argument `sep` giving the separation between the main plot and the legend, or `sep.frac` giving the separation as a fraction of the relevant dimension (width or height) of the main plot.
`symap` | Optional. The graphical symbol map to be applied to the marks. An object of class `"symbolmap"`; see `symbolmap`.
`maxsize` | Maximum physical size of the circles/squares plotted when `x` is a marked point pattern with numerical marks. Incompatible with `meansize` and `markscale`. Ignored if `symap` is given.
`meansize` | Average physical size of the circles/squares plotted when `x` is a marked point pattern with numerical marks. Incompatible with `maxsize` and `markscale`. Ignored if `symap` is given.
`markscale` | physical scale factor determining the sizes of the circles/squares plotted when `x` is a marked point pattern with numerical marks. Mark value will be multiplied by `markscale` to determine physical size. Incompatible with `maxsize` and `meansize`. Ignored if `symap` is given.
`zap` | Fraction between 0 and 1. When `x` is a marked point pattern with numerical marks, `zap` is the smallest mark value (expressed as a fraction of the maximum possible mark) that will be plotted. Any points which have marks smaller in absolute value than `zap * max(abs(marks(x)))` will not be plotted.
`show.window` | Logical value indicating whether to plot the observation window of `x`.
`show.all` | Logical value indicating whether to plot everything including the main title and the observation window of `x`.
`do.plot` | Logical value determining whether to actually perform the plotting.
`multiplot` | Logical value giving permission to display multiple plots.

### Details

This is the `plot` method for point pattern datasets (of class `"ppp"`, see `ppp.object`).

First the observation window `Window(x)` is plotted (if `show.window=TRUE`). Then the points themselves are plotted, in a fashion that depends on their marks, as follows.

unmarked point pattern:

  If the point pattern does not have marks, or if `use.marks = FALSE`, then the locations of all points will be plotted using a single plot character

multitype point pattern:

  If `x$marks` is a factor, then each level of the factor is represented by a different plot character.

continuous marks:

  If `x$marks` is a numeric vector, the marks are rescaled to the unit interval and each point is represented by a circle with diameter proportional to the rescaled mark (if the value is positive) or a square with side length proportional to the absolute value of the rescaled mark (if the value is negative).

other kinds of marks:

  If `x$marks` is neither numeric nor a factor, then each possible mark will be represented by a different plotting character. The default is to represent the ith smallest mark value by `points(..., pch=i)`.

If there are several columns of marks, and if `which.marks` is missing or `NULL`, then

- if `add=FALSE` and `multiplot=TRUE` the default is to plot all columns of marks, in a series of separate plots, placed side-by-side. The plotting is coordinated by `plot.listof`, which calls `plot.ppp` to make each of the individual plots.

- Otherwise, only one column of marks can be plotted, and the default is `which.marks=1` indicating the first column of marks.

Plotting of the window `Window(x)` is performed by `plot.owin`. This plot may be modified through the `...` arguments. In particular the extra argument `border` determines the colour of the window, if the window is not a binary mask.

Plotting of the points themselves is performed by the function `points`, except for the case of continuous marks, where it is performed by `symbols`. Their plotting behaviour may be modified through the `...` arguments.

The argument `chars` determines the plotting character or characters used to display the points (in all cases except for the case of continuous marks). For an unmarked point pattern, this should be a single integer or character determining a plotting character (see `par("pch")`). For a multitype point pattern, `chars` should be a vector of integers or characters, of the same length as `levels(x$marks)`, and then the ith level or type will be plotted using character `chars[i]`.

If `chars` is absent, but there is an extra argument `pch`, then this will determine the plotting character for all points.

The argument `cols` determines the colour or colours used to display the points. For an unmarked point pattern, `cols` should be a character string determining a colour. For a multitype point pattern, `cols` should be a character vector, of the same length as `levels(marks(x))`: that is, there is one colour for each possible mark value. The ith level or type will be plotted using colour `cols[i]`. For a point pattern with continuous marks, `cols` can be either a character string or a character vector specifying colour values: the range of mark values will be mapped to the specified colours.

If `cols` is absent, the colours used to plot the points may be determined by the extra argument `fg` (for multitype point patterns) or the extra argument `col` (for all other cases). Note that specifying `col` will also apply this colour to the window itself.

The default colour for the points is a semi-transparent grey, if this is supported by the plot device. This behaviour can be suppressed (so that the default colour is non-transparent) by setting `spatstat.options(transparent=FALSE)`.

The arguments `maxsize`, `meansize` and `markscale` incompatible. They control the physical size of the circles and squares which represent the marks in a point pattern with continuous marks. The size of a circle is defined as its diameter; the size of a square is its side length. If `markscale` is given, then a mark value of `m` is plotted as a circle of diameter `m * markscale` (if `m` is positive) or a square of side `abs(m) * markscale` (if `m` is negative). If `maxsize` is given, then the largest mark in absolute value, `mmax=max(abs(marks(x)))`, will be scaled to have physical size `maxsize`. If `meansize` is given, then the average absolute mark value, `mmean=mean(abs(marks(x)))`, will be scaled to have physical size `meansize`.

The user can set the default values of these plotting parameters using `spatstat.options("par.points")`.

To zoom in (to view only a subset of the point pattern at higher magnification), use the graphical arguments `xlim` and `ylim` to specify the rectangular field of view.

The value returned by this plot function is an object of class `"symbolmap"` representing the mapping from mark values to graphical symbols. See `symbolmap`. It can be used to make a suitable legend, or to ensure that two plots use the same graphics map.

### Value

(Invisible) object of class `"symbolmap"` giving the correspondence between mark values and plotting characters.

### Removing White Space Around The Plot

A frequently-asked question is: How do I remove the white space around the plot? Currently `plot.ppp` uses the base graphics system of R, so the space around the plot is controlled by parameters to `par`. To reduce the white space, change the parameter `mar`. Typically, `par(mar=rep(0.5, 4))` is adequate, if there are no annotations or titles outside the window.

### Drawing coordinate axes and axis labels

Coordinate axes and axis labels are not drawn, by default. To draw coordinate axes, set `axes=TRUE`. To draw axis labels, set `ann=TRUE` and give values to the arguments `xlab` and `ylab`. See the Examples. Only the default style of axis is supported; for more control over the placement and style of axes, use the graphics commands `axis` and `mtext`.

### Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner r.turner@auckland.ac.nz and Ege Rubak rubak@math.aau.dk.

### See Also

`iplot`, `ppp.object`, `plot`, `par`, `points`, `text.ppp`, `plot.owin`, `symbols`

### Examples

       plot(cells)

       plot(cells, pch=16)

       # make the plotting symbols larger (for publication at reduced scale)
       plot(cells, cex=2)

       # set it in spatstat.options
       oldopt <- spatstat.options(par.points=list(cex=2))
       plot(cells)
       spatstat.options(oldopt)

       # multitype
       plot(lansing)

       # marked by a real number
       plot(longleaf)

       # just plot the points
       plot(longleaf, use.marks=FALSE)
       plot(unmark(longleaf)) # equivalent

       # point pattern with multiple marks
       plot(finpines)
       plot(finpines, which.marks="height")

       # controlling COLOURS of points
       plot(cells, cols="blue")
       plot(lansing, cols=c("black", "yellow", "green",
                            "blue","red","pink"))
       plot(longleaf, fg="blue")

       # make window purple
       plot(lansing, border="purple")
       # make everything purple
       plot(lansing, border="purple", cols="purple", col.main="purple",
                     leg.args=list(col.axis="purple"))

       # controlling PLOT CHARACTERS for multitype pattern
       plot(lansing, chars = 11:16)
       plot(lansing, chars = c("o","h","m",".","o","o"))

       ## multitype pattern mapped to symbols
       plot(amacrine, shape=c("circles", "squares"), size=0.04)
       plot(amacrine, shape="arrows", direction=c(0,90), size=0.07)

       ## plot trees as trees!
       plot(lansing, shape="arrows", direction=90, cols=1:6)

       # controlling MARK SCALE for pattern with numeric marks
       plot(longleaf, markscale=0.1)
       plot(longleaf, maxsize=5)
       plot(longleaf, meansize=2)

       # draw circles of diameter equal to nearest neighbour distance
       plot(cells %mark% nndist(cells), markscale=1, legend=FALSE)

       # inspecting the symbol map
       v <- plot(amacrine)
       v

       ## variable colours ('cols' not 'col')
       plot(longleaf, cols=function(x) ifelse(x < 30, "red", "black"))

       ## re-using the same mark scale
       a <- plot(longleaf)
       juveniles <- longleaf[marks(longleaf) < 30]
       plot(juveniles, symap=a)

       ## numerical marks mapped to symbols of fixed size with variable colour
       ra <- range(marks(longleaf))
       colmap <- colourmap(terrain.colors(20), range=ra)
       ## filled plot characters are the codes 21-25
       ## fill colour is indicated by 'bg'
       sy <- symbolmap(pch=21, bg=colmap, range=ra)
       plot(longleaf, symap=sy)

       ## or more compactly..
       plot(longleaf, bg=terrain.colors(20), pch=21, cex=1)

       ## clipping
       plot(humberside)
       B <- owin(c(4810, 5190), c(4180, 4430))
       plot(B, add=TRUE, border="red")
       plot(humberside, clipwin=B, main="Humberside (clipped)")

       ## coordinate axes and labels
       plot(humberside, axes=TRUE)
       plot(humberside,            ann=TRUE, xlab="Easting", ylab="Northing")
       plot(humberside, axes=TRUE, ann=TRUE, xlab="Easting", ylab="Northing")

[Package spatstat version 1.63-3 Index]