spatstat-package

0th

Percentile

The Spatstat Package

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

Keywords
package, spatial
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

  • creation, manipulation and plotting of point patterns
  • exploratory data analysis
  • simulation of point process models
  • parametric model-fitting
  • hypothesis tests and diagnostics
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

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.

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.

CONTENTS:

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

I. CREATING AND MANIPULATING DATA

Types of spatial data:

The main types of spatial data supported by spatstat are:

ll{ ppp point pattern owin window (spatial region) im pixel image psp line segment pattern tess tessellation }

To create a point pattern: ll{ 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: ll{ 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 simulate.ppm 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: ll{ rlabel random (re)labelling of a multitype point pattern rshift random shift (including toroidal shifts) }

Standard point pattern datasets: Remember to say data(amacrine) etc. Type demo(data) to see all the datasets installed with the package. ll{ 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 bronzefilter Bronze Filter Section 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) shapley Galaxies in an astronomical survey 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:

ll{ plot.ppp plot a point pattern (e.g. plot(X)) iplot plot a point pattern interactively [.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 convexhull compute convex hull pixellate.ppp approximate point pattern by pixel image as.im.ppp approximate point pattern by pixel image } See spatstat.options to control plotting behaviour. To create a window:

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

ll{ 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 convexhull compute convex hull of something letterR polygonal window in the shape of the Rlogo }

To manipulate a window:

ll{ plot.owin plot a window. plot(W) bounding.box Find a tight bounding box for the window erosion erode window by a distance r dilation dilate window by a distance r closing close window by a distance r opening open window by a distance r complement.owin invert (swap inside and outside) simplify.owin approximate a window by a simple polygon rotate rotate window shift translate window affine apply affine transformation }

Digital approximations:

ll{ as.mask Make a discrete pixel approximation of a given window as.im.owin convert window to pixel image pixellate.owin convert window to pixel image nearest.raster.point map continuous coordinates to raster locations raster.x raster x coordinates raster.y raster y coordinates as.polygonal convert pixel mask to polygonal window } See spatstat.options to control the approximation

Geometrical computations with windows:

ll{ 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 area perimeter compute perimeter length diameter compute diameter incircle find largest circle inside a window connected find connected components of window eroded.areas compute areas of eroded windows dilated.areas compute areas of dilated 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 is.convex determine whether a window is convex convexhull compute convex hull as.mask pixel approximation of window as.polygonal polygonal approximation of window }

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. ll{ im create a pixel image as.im convert other data to a pixel image pixellate 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 connected find connected components 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. ll{ 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 [.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 nncross find distance to nearest line segment from a given point 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 rpoisline generate a realisation of the Poisson line process inside a window rlinegrid generate a random array of parallel lines through a window }

Tessellations

An object of class "tess" represents a tessellation.

ll{ tess create a tessellation quadrats create a tessellation of rectangles as.tess convert other data to a tessellation plot.tess plot a tessellation tiles extract all the tiles of a tessellation [.tess extract some tiles of a tessellation [<-.tess change some tiles of a tessellation intersect.tess intersect two tessellations or restrict a tessellation to a window chop.tess subdivide a tessellation by a line dirichlet compute Dirichlet-Voronoi tessellation of points delaunay compute Delaunay triangulation of points rpoislinetess generate tessellation using Poisson line process }

II. EXPLORATORY DATA ANALYSIS

Inspection of data: ll{ 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 istat(X) Interactive exploratory analysis }

Classical exploratory tools: ll{ clarkevans Clark and Evans aggregation index fryplot Fry plot miplot Morishita Index plot }

Summary statistics for a point pattern: ll{ 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 Linhom $L$ 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: ll{ 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. ll{ Gcross,Gdot,Gmulti multitype nearest neighbour distributions $G_{ij}, G_{i\bullet}$ Kcross,Kdot, Kmulti multitype $K$-functions $K_{ij}, K_{i\bullet}$ Lcross,Ldot multitype $L$-functions $L_{ij}, L_{i\bullet}$ Jcross,Jdot,Jmulti multitype $J$-functions $J_{ij}, J_{i\bullet}$ pcfcross multitype pair correlation function $g_{ij}$ markconnect marked connection function $p_{ij}$ alltypes estimates of the above for all $i,j$ pairs Iest multitype $I$-function Kcross.inhom,Kdot.inhom inhomogeneous counterparts of Kcross, Kdot Lcross.inhom,Ldot.inhom inhomogeneous counterparts of Lcross, Ldot }

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. For numeric marks, there are the following functions: ll{ markmean smoothed local average of marks markvar smoothed local variance of marks markcorr mark correlation function markvario mark variogram markcorrint mark correlation integral Emark mark independence diagnostic $E(r)$ Vmark mark independence diagnostic $V(r)$ nnmean nearest neighbour mean index nnvario nearest neighbour mark variance index } For marks of any type, there are the following: ll{ 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: ll{ 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 }

III. MODEL FITTING (CLUSTER MODELS)

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.

ll{ 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:

ll{ 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.

IV. MODEL FITTING (GIBBS MODELS)

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:

ll{ 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 simulate.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. ll{ ~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: ll{ 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. ll{ 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: ll{ 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: ll{ 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: ll{ gridweights quadrature weights by the grid-counting rule dirichlet.weights quadrature weights are Dirichlet tile areas }

Simulation and goodness-of-fit for fitted models: ll{ rmh.ppm simulate realisations of a fitted model simulate.ppm simulate realisations of a fitted model envelope compute simulation envelopes for a fitted model }

V. SIMULATION

There are many ways to generate a random point pattern, line segment pattern, pixel image or tessellation in spatstat.

Random point patterns:

ll{ 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 (grid) 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 rGaussPoisson simulate the Gauss-Poisson cluster process rcell simulate the Baddeley-Silverman cell process runifpointOnLines generate $n$ random points along specified line segments rpoisppOnLines generate Poisson random points along specified line segments }

Resampling a point pattern:

ll{ quadratresample block resampling rjitter apply random displacements to points in a pattern rshift random shifting of (subsets of) points rthin random thinning } Fitted point process models:

If you have fitted a point process model to a point pattern dataset, the fitted model can be simulated.

Cluster process models are fitted by the function kppm yielding an object of class "kppm". To generate one or more simulated realisations of this fitted model, use simulate.kppm.

Gibbs point process models are fitted by the function ppm yielding an object of class "ppm". To generate a simulated realisation of this fitted model, use rmh. To generate one or more simulated realisations of the fitted model, use simulate.ppm.

Other random patterns:

ll{ rlinegrid generate a random array of parallel lines through a window rpoisline simulate the Poisson line process within a window rpoislinetess generate random tessellation using Poisson line process rMosaicSet generate random set by selecting some tiles of a tessellation rMosaicField generate random pixel image by assigning random values in each tile of a tessellation }

Simulation-based inference

ll{ envelope critical envelope for Monte Carlo test of goodness-of-fit qqplot.ppm diagnostic plot for interpoint interaction }

VI. TESTS AND DIAGNOSTICS

Classical hypothesis tests: ll{ quadrat.test $\chi^2$ goodness-of-fit test on quadrat counts kstest Kolmogorov-Smirnov goodness-of-fit test bermantest Berman's goodness-of-fit tests 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.

ll{ 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: ll{ quadratresample block resampling rjitter apply random displacements to points in a pattern rshift random shifting of (subsets of) points rthin random thinning }

VII. 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) 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.

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, Rasmus Waagepetersen, Dominic Schuhmacher and Kasper Klitgaard Berthelsen made substantial contributions of code. Additional contributions by Ang Qi Wei, Colin Beale, Ricardo Bernhardt, Brad Biggerstaff, Roger Bivand, Florent Bonneu, Julian Burgos, Jianbao Chen, Y.C. Chin, Bjarke Christensen, 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, Robert Mark, Jorge Mateu, Peter McCullagh, Sebastian Wastl Meyer, Mi Xiangcheng, Jesper Moller, Linda Stougaard Nielsen, Felipe Nunes, Evgeni Parilov, Jeff Picka, Matt Reiter, Brian Ripley, Barry Rowlingson, Ege Rubak, John Rudge, Aila Sarkka, Katja Schladitz, Bryan Scott, Ida-Maria Sintorn, Malte Spiess, Mark Stevenson, P. Surovy, Berwin Turlach, Andrew van Burgel, Alexendre Villers, Hao Wang, H. Wendrock and Selene Wong.

References

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.

Aliases
  • spatstat-package
  • spatstat
Documentation reproduced from package spatstat, version 1.17-0, License: GPL (>= 2)

Community examples

Looks like there are no examples yet.