persp.ppp: Perspective Plot of Marked Point Pattern

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

Perspective Plot of Marked Point Pattern

Description

For a spatial point pattern with numeric marks, generate a perspective plot in which each data point is shown as a vertical spike, with height proportional to the mark value.

Usage

  ## S3 method for class 'ppp'
persp(x, ..., main, type=c("l", "b"),
            grid = TRUE, ngrid = 10,
            col.grid = "grey", col.base = "white",
            win.args=list(),
            spike.args = list(), neg.args = list(),
            point.args=list(), 
            which.marks = 1,
            zlab = NULL, zlim = NULL, zadjust = 1,
            show.window=TRUE,
            legend=TRUE, legendpos="bottomleft",
            leg.args=list(lwd=4), leg.col=c("black", "orange"))

Arguments

x	A spatial point pattern (object of class "ppp") with numeric marks, or a data frame of marks.
...	Additional graphical arguments passed to persp.default to determine the perspective view (for example the rotation angle theta and the elevation angle phi) or passed to segments to control the drawing of lines (for example lwd for line width) or passed to points.default to control the drawing of points (for example pch for symbol type).
main	Optional main title for the plot.
type	Single character specifying how each observation will be plotted: type="l" for lines, type="b" for both lines and points.
grid	Logical value specifying whether to draw a grid of reference lines on the horizontal plane.
ngrid	Number of grid lines to draw in each direction, if grid=TRUE. An integer, or a pair of integers specifying the number of grid lines along the horizontal and vertical axes respectively.
col.grid	Colour of grid lines, if grid=TRUE.
col.base	Colour with which to fill the horizontal plane. A single colour value, or a pixel image.
win.args	List of arguments passed to plot.owin to control the drawing of the window of x. Applicable only when the window is not a rectangle.
spike.args	List of arguments passed to segments to control the drawing of the spikes.
neg.args	List of arguments passed to segments applicable only to those spikes which have negative height (corresponding to a mark value which is negative).
point.args	List of arguments passed to points.default to control the drawing of the points, when type="b".
which.marks	Integer, or character name, identifying the column of marks which should be used, when marks(x) is a data frame.
zlab	Optional. Label for the vertical axis. Character string or expression.
zlim	Optional. Range of values on the vertical axis. A numeric vector of length 2.
zadjust	Scale adjustment factor controlling the height of spikes.
show.window	Logical value specifying whether to draw the window of x on the horizontal plane.
legend	Logical value specifying whether to draw a reference scale bar for the vertical axis.
legendpos	Position of the reference scale bar. Either a character string matching one of the options "bottomleft", "bottomright", "topleft", "topright", "bottom", "left", "top" or "right", or a numeric vector of length 2 specifing the coordinate position of the base of the reference scale bar.
leg.args	Additional arguments passed to segments to control the drawing of the reference scale bar.
leg.col	A vector (usually of length 2) of colour values for successive intervals in the reference scale. The default is a reference scale consisting of black and orange stripes.

Details

The function persp is generic. This is the method for spatial point patterns (objects of class "ppp"). The argument x must be a point pattern with numeric marks, or with a data frame of marks.

A perspective view will be plotted. The eye position is determined by the arguments theta and phi passed to persp.default.

First the horizontal plane is drawn in perspective view, using a faint grid of lines to help suggest the perspective. Next the observation window of x is placed on the horizontal plane and its edges are drawn in perspective view. Finally for each data point in x, a vertical spike is erected at the spatial location of the data point, with height equal to the mark value of the point.

The horizontal plane is effectively transparent, by default. If the argument col.base is a single colour value, the horizontal plane will be painted in this colour. If col.base is a pixel image, it will be rendered as a colour image shown in perspective view on the horizontal plane:

• If valuesAreColours=TRUE is specified, the pixel values of col.base will be interpreted directly as colour values.

• Otherwise, the argument colmap controls the mapping from pixel values of col.base to physical colours.

After the horizontal plane has been coloured, the observation window Window(x) will be drawn on the horizontal plane (unless show.window=FALSE). By default, only the edges of the window will be drawn, as black line segments. The style of plotting the window can be modified using win.args. The colour of the line segments is controlled by win.args$border. If win.args$col is given, the window will be filled in the specified colour, overwriting any previous colours. See the Examples.

If any mark values are negative, the corresponding spikes will penetrate below the horizontal plane. They can be drawn in a different colour by specifying neg.args as shown in the examples. These would be obscured if col.base is an opaque colour other than white, or if col.base is a pixel image. A transparent colour for col.base can be used if it is supported by the graphics device.

Like all spatial plots in the spatstat family, persp.ppp does not independently rescale the x and y coordinates. A long narrow window will be represented as a long narrow window in the perspective view. To override this and allow the coordinates to be independently rescaled, use the argument scale=TRUE which will be passed to persp.default.

Value

(Invisibly) the perspective transformation matrix.

Author(s)

\adrian

.

Examples

   persp(longleaf, theta=-30, phi=35, spike.args=list(lwd=3), zadjust=1.5,
         zlab="diameter")

   # negative mark values
   X <- longleaf
   marks(X) <- marks(X) - 20
   persp(X, theta=80, phi=35, neg.args=list(col="red"),
         spike.args=list(lwd=3), zadjust=1.2)

   # irregular window
   Australia <- Window(austates)
   Y <- runifrect(70, Frame(Australia))[Australia]
   marks(Y) <- runif(npoints(Y))
   persp(Y, theta=30, phi=20, col.base="lightblue",
         win.args=list(col="pink", border=NA),
         spike.args=list(lwd=2), zadjust=1.5, zlab="")

   persp(Y, type="b",
         theta=30, phi=20, col.base="lightblue",
         win.args=list(col="pink", border=NA),
         spike.args=list(lty=3), point.args=list(col="blue"), zadjust=1.5)

spatstat.geom documentation built on Jan. 20, 2026, 5:08 p.m.