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.

Getting Started

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

An introduction to the package is available in the file Intro.pdf in the doc directory supplied in the installation of the package.

The package is described more fully in the paper by Baddeley and Turner (2005a), available online.

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.

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
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
rMaternI simulate the Mat'ern Model I inhibition process
rMaternII simulate the Mat'ern Model II inhibition process
rSSI simulate Simple Sequential Inhibition process
rNeymanScott simulate a general Neyman-Scott process
rMatClust simulate the Mat'ern Cluster process
rThomas simulate the Thomas 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
rtoro random toroidal shift

Standard point pattern datasets:

Remember to say data(bramblecanes) etc.

amacrine Austin Hughes' rabbit amacrine cells
ants Harkness-Isham ant nests data
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
redwood Strauss-Ripley redwood saplings data
redwoodfull Strauss redwood saplings data (full set)
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
ksmooth.ppp kernel smoothing
identify.ppp interactively identify points

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
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
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 ksmooth.ppp.
im create a pixel image
as.im convert other data to a pixel image
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
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

II. EXPLORATORY DATA ANALYSIS

Inspection of data:
summary(X) print useful summary of point pattern X
X print basic description of point pattern X
quadratcount Quadrat counts

Summary statistics for a point pattern:
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
pairdist distances between all pairs of points
crossdist distances between points in two patterns
exactdt distance from any location to nearest data point
distmap distance map image

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

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

III. MODEL FITTING

To fit a point process model:

Model fitting in spatstat is performed 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
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
stratrand 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:

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

Diagnostic plots:

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

diagnose.ppm diagnostic plots for spatial trend
qqplot.ppm diagnostic plot for interpoint interaction

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.

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 made substantial contributions of code. Contributions were also made by J.B. Chen, Y.C. Chin, S. Eglen, P. Grabarnik, U. Hahn, M.B. Hansen, K. Hornik, J. Mateu, L.S. Nielsen, B.D. Ripley, B. Rowlingson, A. Sarkka, K. Schladitz, B.T. Scott, M. Stevenson, B. Turlach, and A. van Burgel.

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, J. Mateu and D. Stoyan (eds.) Case Studies in Spatial Point Pattern Modelling. Springer-Verlag, 2005, to appear.


[Package spatstat version 1.6-12 Index]