spatstat {spatstat}R Documentation

The Spatstat Package

Description

This is a summary of the features of spatstat, a package in R for the statistical analysis of spatial point patterns.

Details

spatstat is a package for the statistical analysis of spatial data. Currently, it deals mainly with the analysis of patterns of points in the plane. The points may carry `marks', and the spatial region in which the points were recorded may have arbitrary shape.

The package supports

The point process models to be fitted may be quite general Gibbs/Markov models; they may include spatial trend, dependence on covariates, and interpoint interactions of any order (i.e. not restricted to pairwise interactions). Models are specified by a formula in the R language, and are fitted using a single function ppm analogous to lm and glm. It is also possible to fit cluster process models by the method of minimum contrast.

Getting Started

Type demo(spatstat) for an overall demonstration of the package.

For a readable introduction to spatstat, see the paper by Baddeley and Turner (2005a), available online.

Type demo(data) to see all the datasets available in the package.

FUNCTIONS AND DATASETS

Following is a summary of the main functions and datasets in the spatstat package. Alternatively an alphabetical list of all functions and datasets is available by typing library(help=spatstat).

For further information on any of these, type help(name) where name is the name of the function or dataset.

Type demo(data) to see all the datasets installed with the package.

CONTENTS:

I. Creating and manipulating data
II. Exploratory Data Analysis
III. Model fitting (cluster models)
IV. Model fitting (Gibbs models)
V. Tests and diagnostics
VI. Documentation

I. CREATING AND MANIPULATING DATA

To create a point pattern:

ppp create a point pattern from (x,y) and window information
ppp(x, y, xlim, ylim) for rectangular window
ppp(x, y, poly) for polygonal window
ppp(x, y, mask) for binary image window
as.ppp convert other types of data to a ppp object
clickppp interactively add points to a plot
setmarks, %mark% attach/reassign marks to a point pattern

To simulate a random point pattern:

runifpoint generate n independent uniform random points
rpoint generate n independent random points
rmpoint generate n independent multitype random points
rpoispp simulate the (in)homogeneous Poisson point process
rmpoispp simulate the (in)homogeneous multitype Poisson point process
runifdisc generate n independent uniform random points in disc
rstrat stratified random sample of points
rsyst systematic random sample of points
rMaternI simulate the Mat'ern Model I inhibition process
rMaternII simulate the Mat'ern Model II inhibition process
rSSI simulate Simple Sequential Inhibition process
rStrauss simulate Strauss process (perfect simulation)
rNeymanScott simulate a general Neyman-Scott process
rMatClust simulate the Mat'ern Cluster process
rThomas simulate the Thomas process
rthin random thinning
rcell simulate the Baddeley-Silverman cell process
rmh simulate Gibbs point process using Metropolis-Hastings

To randomly change an existing point pattern:

rlabel random (re)labelling of a multitype point pattern
rshift random shift (including toroidal shifts)

Standard point pattern datasets:

Remember to say data(bramblecanes) etc.

amacrine Austin Hughes' rabbit amacrine cells
anemones Upton-Fingleton sea anemones data
ants Harkness-Isham ant nests data
bei Tropical rainforest trees
betacells Waessle et al. cat retinal ganglia data
bramblecanes Bramble Canes data
cells Crick-Ripley biological cells data
chorley Chorley-Ribble cancer data
copper Berman-Huntington copper deposits data
demopat Synthetic point pattern
finpines Finnish Pines data
hamster Aherne's hamster tumour data
humberside North Humberside childhood leukaemia data
japanesepines Japanese Pines data
lansing Lansing Woods data
longleaf Longleaf Pines data
nztrees Mark-Esler-Ripley trees data
nbfires New Brunswick fires data
redwood Strauss-Ripley redwood saplings data
redwoodfull Strauss redwood saplings data (full set)
residualspaper Data from Baddeley et al (2005)
simdat Simulated point pattern (inhomogeneous, with interaction)
spruces Spruce trees in Saxonia
swedishpines Strand-Ripley swedish pines data

To manipulate a point pattern:

plot.ppp plot a point pattern (e.g. plot(X))
subset.ppp, "[.ppp" extract or replace a subset of a point pattern
pp[subset]
pp[, subwindow]
superimpose superimpose any number of point patterns
cut.ppp discretise the marks in a point pattern
unmark remove marks
setmarks attach marks or reset marks
split.ppp divide pattern into sub-patterns
rotate rotate pattern
shift translate pattern
affine apply affine transformation
density.ppp kernel smoothing
identify.ppp interactively identify points
unique.ppp remove duplicate points
duplicated.ppp determine which points are duplicates

See spatstat.options to control plotting behaviour.

To create a window:

An object of class "owin" describes a spatial region (a window of observation).

owin Create a window object
owin(xlim, ylim) for rectangular window
owin(poly) for polygonal window
owin(mask) for binary image window
as.owin Convert other data to a window object
square make a square window
disc make a circular window
ripras Ripley-Rasson estimator of window, given only the points
letterR polygonal window in the shape of the {sf R} logo

To manipulate a window:

plot.owin plot a window.
plot(W)
bounding.box Find a tight bounding box for the window
erode.owin erode window by a distance r
dilate.owin dilate window by a distance r
complement.owin invert (swap inside and outside)
rotate rotate window
shift translate window
affine apply affine transformation

Digital approximations:

as.mask Make a discrete pixel approximation of a given window
nearest.raster.point map continuous coordinates to raster locations
raster.x raster x coordinates
raster.y raster y coordinates

See spatstat.options to control the approximation

Geometrical computations with windows:

intersect.owin intersection of two windows
union.owin union of two windows
inside.owin determine whether a point is inside a window
area.owin compute window's area
diameter compute window frame's diameter
eroded.areas compute areas of eroded windows
bdist.points compute distances from data points to window boundary
bdist.pixels compute distances from all pixels to window boundary
distmap.owin distance transform image
centroid.owin compute centroid (centre of mass) of window
is.subset.owin determine whether one window contains another

Pixel images: An object of class "im" represents a pixel image. Such objects are returned by some of the functions in spatstat including Kmeasure, setcov and density.ppp.
im create a pixel image
as.im convert other data to a pixel image
as.matrix.im convert pixel image to matrix
plot.im plot a pixel image on screen as a digital image
contour.im draw contours of a pixel image
persp.im draw perspective plot of a pixel image
[.im extract subset of pixel image
shift.im apply vector shift to pixel image
X print very basic information about image X
summary(X) summary of image X
hist.im histogram of image
mean.im mean pixel value of image
quantile.im quantiles of image
cut.im convert numeric image to factor image
is.im test whether an object is a pixel image
compatible.im test whether two images have compatible dimensions
eval.im evaluate any expression involving images
levelset level set of an image
solutionset region where an expression is true

Line segment patterns

An object of class "psp" represents a pattern of line segments.
psp create a line segment pattern
as.psp convert other data into a line segment pattern
plot.psp plot a line segment pattern
print.psp print basic information
summary.psp print summary information
subset.psp
[.psp extract a subset of a line segment pattern
midpoints.psp compute the midpoints of line segments
endpoints.psp extract the endpoints of line segments
lengths.psp compute the lengths of line segments
angles.psp compute the orientation angles of line segments
rotate.psp rotate a line segment pattern
shift.psp shift a line segment pattern
affine.psp apply an affine transformation
distmap.psp compute the distance map of a line segment pattern
density.psp kernel smoothing of line segments
selfcrossing.psp find crossing points between line segments
crossing.psp find crossing points between two line segment patterns

II. EXPLORATORY DATA ANALYSIS

Inspection of data:
summary(X) print useful summary of point pattern X
X print basic description of point pattern X
any(duplicated(X)) check for duplicated points in pattern X

Summary statistics for a point pattern:
quadratcount Quadrat counts
Fest empty space function F
Gest nearest neighbour distribution function G
Kest Ripley's K-function
Jest J-function J = (1-G)/(1-F)
pcf pair correlation function
Kinhom K for inhomogeneous point patterns
Kest.fft fast K-function using FFT for large datasets
Kmeasure reduced second moment measure
allstats all four functions F, G, J, K
envelope simulation envelopes for a summary function

Related facilities:
plot.fv plot a summary function
eval.fv evaluate any expression involving summary functions
nndist nearest neighbour distances
nnwhich find nearest neighbours
pairdist distances between all pairs of points
crossdist distances between points in two patterns
nncross nearest neighbours between two point patterns
exactdt distance from any location to nearest data point
distmap distance map image
density.ppp kernel smoothed density

Summary statistics for a multitype point pattern: A multitype point pattern is represented by an object X of class "ppp" with a component X$marks which is a factor.
Gcross,Gdot,Gmulti multitype nearest neighbour distributions Gij, Gi.
Kcross,Kdot, Kmulti multitype K-functions Kij, Ki.
Jcross,Jdot,Jmulti multitype J-functions Jij,Ji.
alltypes estimates of the above for all i,j pairs
Iest multitype I-function
Kcross.inhom,Kdot.inhom inhomogeneous counterparts of Kcross, Kdot

Summary statistics for a marked point pattern: A marked point pattern is represented by an object X of class "ppp" with a component X$marks. The entries in the vector X$marks may be numeric, complex, string or any other atomic type.
markcorr mark correlation function
Gmulti multitype nearest neighbour distribution
Kmulti multitype K-function
Jmulti multitype J-function

Alternatively use cut.ppp to convert a marked point pattern to a multitype point pattern.

Programming tools:
applynbd apply function to every neighbourhood
in a point pattern
pppdist find the optimal match between two point patterns

III. MODEL FITTING (CLUSTER MODELS)

Several kinds of clustered point process models can be fitted using the Method of Minimum Contrast.

thomas.estK fit the Thomas process model
matclust.estK fit the Matern Cluster process model
lgcp.estK fit a log-Gaussian Cox process model
mincontrast general algorithm for fitting models
by the method of minimum contrast

The Thomas and Matern models can also be simulated, using rThomas and rMatClust respectively.

IV. MODEL FITTING (GIBBS MODELS)

For a detailed explanation of how to fit models to point pattern data using spatstat, see Baddeley and Turner (2005b).

To fit a Gibbs point process model:

Model fitting in spatstat is performed mainly by the function ppm. Its result is an object of class "ppm".

Manipulating the fitted model:

plot.ppm Plot the fitted model
predict.ppm Compute the spatial trend
and conditional intensity
of the fitted point process model
coef.ppm Extract the fitted model coefficients
fitted.ppm Compute fitted conditional intensity at quadrature points
update.ppm Update the fit
vcov.ppm Variance-covariance matrix of estimates
rmh.ppm Simulate from fitted model
print.ppm Print basic information about a fitted model
summary.ppm Summarise a fitted model
anova.ppm Analysis of deviance

See spatstat.options to control plotting of fitted model.

To specify a point process model:

The first order ``trend'' of the model is written as an R language formula.

~1 No trend (stationary)
~x First order term λ(x,y) = exp(α + β x)
where x,y are Cartesian coordinates
~polynom(x,y,3) Log-cubic polynomial trend
~harmonic(x,y,2) Log-harmonic polynomial trend

The higher order (``interaction'') components are described by an object of class "interact". Such objects are created by:
Poisson() the Poisson point process
Strauss() the Strauss process
StraussHard() the Strauss/hard core point process
Softcore() pairwise interaction, soft core potential
PairPiece() pairwise interaction, piecewise constant
DiggleGratton() Diggle-Gratton potential
LennardJones() Lennard-Jones potential
Pairwise() pairwise interaction, user-supplied potential
Geyer() Geyer's saturation process
Saturated() Saturated pair model, user-supplied potential
OrdThresh() Ord process, threshold potential
Ord() Ord model, user-supplied potential
MultiStrauss() multitype Strauss process
MultiStraussHard() multitype Strauss/hard core process

Finer control over model fitting:

A quadrature scheme is represented by an object of class "quad".

quadscheme generate a Berman-Turner quadrature scheme
for use by ppm
default.dummy default pattern of dummy points
gridcentres dummy points in a rectangular grid
rstrat stratified random dummy pattern
spokes radial pattern of dummy points
corners dummy points at corners of the window
gridweights quadrature weights by the grid-counting rule
dirichlet.weights quadrature weights are Dirichlet tile areas
plot(Q) plot quadrature scheme Q
print(Q) print basic information about quadrature scheme Q
summary(Q) summary of quadrature scheme Q

Simulation and goodness-of-fit for fitted models:

rmh.ppm simulate realisations of a fitted model
envelope compute simulation envelopes for a fitted model

V. TESTS AND DIAGNOSTICS

Classical hypothesis tests:

quadrat.test chi^2 goodness-of-fit test on quadrat counts
envelope critical envelope for Monte Carlo test of goodness-of-fit
anova.ppm Analysis of Deviance for point process models

Diagnostic plots:

Residuals for a fitted point process model, and diagnostic plots based on the residuals, were introduced in Baddeley et al (2005).

Type demo(diagnose) for a demonstration of the diagnostics features.

diagnose.ppm diagnostic plots for spatial trend
qqplot.ppm diagnostic plot for interpoint interaction
residualspaper examples from Baddeley et al (2005)

VI. DOCUMENTATION

The online manual entries are quite detailed and should be consulted first for information about a particular function.

The paper by Baddeley and Turner (2005a) describes the package. Baddeley and Turner (2005b) is a more detailed explanation of how to fit point process models to data.

Type citation("spatstat") to get these references.

Licence

This library and its documentation are usable under the terms of the "GNU General Public License", a copy of which is distributed with the package.

Acknowledgements

Marie-Colette van Lieshout, Kasper Klitgaard Berthelsen and Dominic Schuhmacher made substantial contributions of code. Additional contributions by Colin Beale, Brad Biggerstaff, Florent Bonneu, Jianbao Chen, Y.C. Chin, Peter Diggle, Stephen Eglen, Agnes Gault, Marc Genton, Pavel Grabarnik, C. Graf, Ute Hahn, Mandy Hering, Martin Bogsted Hansen, Martin Hazelton, Kurt Hornik, Robert John-Chandran, Jorge Mateu, Jesper Moller, Linda Stougaard Nielsen, Evgeni Parilov, Matt Reiter, Brian Ripley, Barry Rowlingson, Aila Sarkka, Katja Schladitz, Bryan Scott, Malte Spiess, Mark Stevenson, P. Surovy, Berwin Turlach, Andrew van Burgel and Selene Wong.

Author(s)

Adrian Baddeley adrian@maths.uwa.edu.au http://www.maths.uwa.edu.au/~adrian/ and Rolf Turner rolf@math.unb.ca http://www.math.unb.ca/~rolf

References

Baddeley, A. and Turner, R. (2005a) Spatstat: an R package for analyzing spatial point patterns. Journal of Statistical Software 12:6, 1–42. URL: www.jstatsoft.org, ISSN: 1548-7660.

Baddeley, A. and Turner, R. (2005b) Modelling spatial point patterns in R. In: A. Baddeley, P. Gregori, J. Mateu, R. Stoica, and D. Stoyan, editors, Case Studies in Spatial Point Pattern Modelling, Lecture Notes in Statistics number 185. Pages 23–74. Springer-Verlag, New York, 2006. ISBN: 0-387-28311-0.

Baddeley, A., Turner, R., Moller, J. and Hazelton, M. (2005) Residual analysis for spatial point processes. Journal of the Royal Statistical Society, Series B 67, 617–666.

[Package spatstat version 1.11-3 Index]