plot.ppp: plot a Spatial Point Pattern
In spatstat.geom: Geometrical Functionality of the 'spatstat' Family

plot.ppp

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,
                    minsize=NULL, zerosize=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`	the plotting character(s) used to plot points. Either a single character, an integer, or a vector of single characters or integers. Ignored if `symap` is given.
`cols`	the colour(s) used to plot points. Either an integer index from 1 to 8 (indexing the standard colour palette), a character string giving the name of a colour, or a string giving the hexadecimal representation of a colour, or a vector of such integers or strings. See the section on Colour Specification in the help for `par`. Ignored if `symap` is given.
`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 largest dimension (maximum of width and height) of the main plot.
`symap`	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.
`minsize`	Minimum physical size of the circles/squares plotted when `x` is a marked point pattern with numerical marks. Incompatible with `zerosize`. Ignored if `symap` is given.
`zerosize`	Physical size of the circle/square representing a mark value of zero, when `x` is a marked point pattern with numerical marks. Incompatible with `minsize`. Defaults to zero. 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 marks(x) is a factor, then each level of the factor is represented by a different plot character.
continuous marks:: If marks(x) 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 marks(x) 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.

If the argument symap is given, then it determines the graphical display of the points. It should be a symbol map (object of class "symbolmap") created by the function symbolmap.

If symap is not given, then the following arguments can be used to specify how the points are plotted:

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(marks(x)), 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 are incompatible with each other (and incompatible with symap). The arguments minsize and zerosize are incompatible with each other (and incompatible with symap). Together, these arguments 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 + zerosize (if m is positive) or a square of side abs(m) * markscale + zerosize (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. If minsize is given, then the minimum mark value, mmean=mean(abs(marks(x))), will be scaled to have physical size minsize.
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.

The Symbol Map

The behaviour of plot.ppp is different from the behaviour of the base R graphics functions points and symbols.

In the base graphics functions points and symbols, arguments such as col, pch and cex can be vectors which specify the representation of each successive point. For example col[3] would specify the colour of the third point in the sequence of points. If there are 100 points then col should be a vector of length 100.

In the spatstat function plot.ppp, arguments such as col, pch and cex specify the mapping from point characteristics to graphical parameters (called the symbol map). For example col[3] specifies the colour of the third type of point in a pattern of points of different types. If there are 4 types of points then col should be a vector of length 4.

To modify a symbol map, for example to change the colours used without changing anything else, use update.symbolmap.

Author(s)

\spatstatAuthors

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)
   plot(longleaf, minsize=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'
   ## outline colour is 'fg'
   sy <- symbolmap(pch=21, bg=colmap, fg=colmap, range=ra)
   plot(longleaf, symap=sy)

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

   ## plot only the colour map (since the symbols have fixed size and shape)
   plot(longleaf, symap=sy, leg.args=list(colour.only=TRUE))

   ## 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")

spatstat.geom documentation built on Sept. 18, 2024, 9:08 a.m.