spatstat {spatstat} | R Documentation |
This is a summary of the features of
spatstat, a package in R
for the statistical analysis of spatial point patterns.
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.
For a quick introduction to spatstat, see
the paper by Baddeley and Turner (2005a).
For a complete 2-day course on using spatstat
, see the workshop notes
by Baddeley (2008).
Both of these documents are available on the internet.
Type demo(spatstat)
for a demonstration
of the package's capabilities.
Type demo(data)
to see all the datasets
available in the package.
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 |
II. | Exploratory Data Analysis |
III. | Model fitting (cluster models) |
IV. | Model fitting (Gibbs models) |
V. | Tests and diagnostics |
VI. | Documentation |
Types of spatial data:
The main types of spatial data supported by spatstat are:
ppp | point pattern |
owin | window (spatial region) |
im | pixel image |
psp | line segment pattern |
tess | tessellation |
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 |
rjitter | apply random displacements to points in a pattern |
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 |
rGaussPoisson | simulate the Gauss-Poisson cluster process |
rthin | random thinning |
rcell | simulate the Baddeley-Silverman cell process |
rmh | simulate Gibbs point process using Metropolis-Hastings |
runifpointOnLines | generate n random points along specified line segments |
rpoisppOnLines | generate Poisson random points along specified line segments |
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.
Type demo(data)
to see all the datasets
installed with the package.
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 |
murchison | Murchison gold deposits |
nbfires | New Brunswick fires data |
nztrees | Mark-Esler-Ripley trees data |
ponderosa | Getis-Franklin ponderosa pine trees 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 |
urkiola | Urkiola Woods 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] or pp[subwindow] |
|
superimpose | combine several point patterns |
by.ppp | apply a function to sub-patterns of a point pattern |
cut.ppp | classify the points 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 |
dirichlet | compute Dirichlet-Voronoi tessellation |
delaunay | compute Delaunay triangulation |
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 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 |
closing.owin | close window by a distance r |
opening.owin | open 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 a subset of a pixel image |
[<-.im | replace a subset of a 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 |
interp.im | interpolate a pixel image |
blur | apply Gaussian blur to 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 straight line
segments.
psp | create a line segment pattern |
as.psp | convert other data into a line segment pattern |
is.psp | determine whether a dataset has class "psp" |
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 |
as.data.frame.psp | convert line segment pattern to data frame |
marks.psp | extract marks of line segments |
marks<-.psp | assign new marks to line segments |
unmark.psp | delete marks from line segments |
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 |
nearestsegment | find line segment closest to a given point |
project2segment | find location along a line segment closest to a given point |
pointsOnLines | generate points evenly spaced along line segment |
Tessellations
An object of class "tess"
represents a tessellation.
tess | create a tessellation |
as.tess | convert other data to a tessellation |
plot.tess | plot a tessellation |
tiles | extract all the tiles of a tessellation |
[.tess | extract a subset of (tiles of) a tessellation |
[<-.tess | change a subset of (tiles of) a tessellation |
quadrats | create a tessellation of rectangles |
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 |
Classical exploratory tools:
clarkevans | Clark and Evans aggregation index |
fryplot | Fry plot |
miplot | Morishita Index plot |
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 |
Lest | Ripley's L-function |
Jest | J-function J = (1-G)/(1-F) |
localL | Getis-Franklin neighbourhood density function |
localK | neighbourhood K-function |
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 |
eval.fasp | evaluate any expression involving an array of functions |
with.fv | evaluate an expression for a summary function |
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 |
smooth.ppp | spatial interpolation of marks |
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 G[i,j], G[i.] |
Kcross,Kdot, Kmulti | multitype K-functions K[i,j], K[i.] |
Jcross,Jdot,Jmulti | multitype J-functions J[i,j],J[i.] |
pcfcross | multitype pair correlation function g[i,j] |
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 |
markstat | apply function to the marks of neighbours in a point pattern |
marktable | tabulate the marks of neighbours in a point pattern |
pppdist | find the optimal match between two point patterns |
Cluster process models (with homogeneous or inhomogeneous intensity)
can be fitted by the function kppm
.
Its result is an object of class "kppm"
.
The fitted model can be printed, plotted, predicted, simulated
and updated.
plot.kppm | Plot the fitted model |
predict.kppm | Compute fitted intensity |
update.kppm | Update the model |
simulate.kppm | Generate simulated realisations |
Lower-level fitting functions include:
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 | low-level algorithm for fitting models |
by the method of minimum contrast |
The Thomas and Matern models can also be simulated,
using rThomas
and rMatClust
respectively.
For a detailed explanation of how to fit Gibbs models to point pattern data using spatstat, see Baddeley and Turner (2005b) or Baddeley (2008).
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 |
formula.ppm | Extract the trend formula |
fitted.ppm | Compute fitted conditional intensity at quadrature points |
residuals.ppm | Compute point process residuals 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 |
effectfun | Compute the fitted effect of one covariate |
logLik.ppm | log-likelihood or log-pseudolikelihood |
anova.ppm | Analysis of deviance |
For model selection, you can also use
the generic functions step
, drop1
and AIC
on fitted point process models.
See spatstat.options
to control plotting of fitted model.
To specify a point process model:
The first order ``trend'' of the model is determined by an R
language formula. The formula specifies the form of the
logarithm of the trend.
~1 | No trend (stationary) |
~x | Loglinear trend lambda(x,y) = exp(alpha + beta * 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 |
AreaInter() | Area-interaction process |
Geyer() | Geyer's saturation process |
BadGey() | multiscale Geyer process |
SatPiece() | Saturated pair model, piecewise constant potential |
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"
. To create a quadrature scheme, typically
use quadscheme
.
quadscheme | default quadrature scheme |
using rectangular cells or Dirichlet cells | |
pixelquad | quadrature scheme based on image pixels |
quad | create an object of class "quad" |
To inspect a quadrature scheme:
plot(Q) | plot quadrature scheme Q |
print(Q) | print basic information about quadrature scheme Q |
summary(Q) | summary of quadrature scheme Q |
A quadrature scheme consists of data points, dummy points, and weights. To generate dummy points:
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 |
To compute weights:
gridweights | quadrature weights by the grid-counting rule |
dirichlet.weights | quadrature weights are Dirichlet tile areas |
Simulation and goodness-of-fit for fitted models:
rmh.ppm | simulate realisations of a fitted model |
envelope | compute simulation envelopes for a fitted model |
Classical hypothesis tests:
quadrat.test | chi^2 goodness-of-fit test on quadrat counts |
kstest | Kolmogorov-Smirnov goodness-of-fit test |
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) |
Resampling and randomisation procedures
You can build your own tests based on randomisation and resampling using the following capabilities:
quadratresample | Spatial block resampling |
rshift | Random shifting of (subsets of) points |
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) is a brief overview of
the package.
Baddeley and Turner (2005b) is a more detailed explanation of
how to fit point process models to data.
Baddeley (2008) is a complete set of notes from a 2-day workshop
on the use of spatstat
.
Type citation("spatstat")
to get these references.
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.
Marie-Colette van Lieshout, Rasmus Waagepetersen, Dominic Schuhmacher and Kasper Klitgaard Berthelsen made substantial contributions of code. Additional contributions by Ang Qi Wei, Colin Beale, Brad Biggerstaff, Roger Bivand, Florent Bonneu, Jianbao Chen, Y.C. Chin, Marcelino de la Cruz, Peter Diggle, Stephen Eglen, Agnes Gault, Marc Genton, Pavel Grabarnik, C. Graf, Janet Franklin, Ute Hahn, Mandy Hering, Martin Bogsted Hansen, Martin Hazelton, Juha Heikkinen, Kurt Hornik, Ross Ihaka, Robert John-Chandran, Devin Johnson, Jeff Laake, Jorge Mateu, Peter McCullagh, Mi Xiangcheng, Jesper Moller, Linda Stougaard Nielsen, Evgeni Parilov, Jeff Picka, Matt Reiter, Brian Ripley, Barry Rowlingson, John Rudge, Aila Sarkka, Katja Schladitz, Bryan Scott, Ida-Maria Sintorn, Malte Spiess, Mark Stevenson, P. Surovy, Berwin Turlach, Andrew van Burgel, Hao Wang and Selene Wong.
Adrian Baddeley adrian@maths.uwa.edu.au http://www.maths.uwa.edu.au/~adrian/ and Rolf Turner r.turner@auckland.ac.nz
Baddeley, A. (2008) Analysing spatial point patterns in R.
Workshop notes. CSIRO online technical publication.
URL: www.csiro.au/resources/pf16h.html
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.