Learn R Programming

spatstat.geom (version 3.3-2)

spatstat.geom-package: The spatstat.geom Package

Description

The spatstat.geom package belongs to the spatstat family of packages. It defines classes of geometrical objects such as windows and point patterns, and provides functionality for geometrical operations on them.

Arguments

Structure of the spatstat family

The original spatstat package grew to be very large, and CRAN requested that the package be divided into several sub-packages. Currently the sub-packages are:

  • spatstat.utils containing basic utilities

  • spatstat.data containing datasets

  • spatstat.sparse containing linear algebra utilities

  • spatstat.geom containing geometrical objects and geometrical operations

  • spatstat.random containing code for generating random spatial patterns

  • spatstat.explore containing the main functionality for exploratory and non-parametric analysis of spatial data

  • spatstat.model containing the main functionality for statistical modelling and inference for spatial data

  • spatstat.linnet containing functions for spatial data on a linear network

  • spatstat, which simply loads the other sub-packages listed above, and provides documentation.

When you install spatstat, these sub-packages are also installed. Then if you load the spatstat package by typing library(spatstat), the other sub-packages listed above will automatically be loaded or imported. For an overview of all the functions available in these sub-packages, see the help file for spatstat in the spatstat package,

Additionally there are several extension packages:

  • spatstat.gui for interactive graphics

  • spatstat.local for local likelihood (including geographically weighted regression)

  • spatstat.Knet for additional, computationally efficient code for linear networks

  • spatstat.sphere (under development) for spatial data on a sphere, including spatial data on the earth's surface

The extension packages must be installed separately and loaded explicitly if needed. They also have separate documentation.

OVERVIEW OF CAPABILITIES

Following is an overview of the capabilities of the spatstat.geom sub-package.

Types of spatial data:

The main types of spatial data supported by spatstat.geom are:

ppppoint pattern
owinwindow (spatial region)
impixel image
pspline segment pattern
tesstessellation
pp3three-dimensional point pattern
ppxpoint pattern in any number of dimensions

Additional data types are supported in spatstat.linnet.

To create a point pattern:

pppcreate 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.pppconvert other types of data to a ppp object
clickpppinteractively add points to a plot
marks<-, %mark%attach/reassign marks to a point pattern

To simulate a random point pattern:

Most of the methods for generating random data are provided in spatstat.random. The following basic methods are supplied in spatstat.geom:

runifrectgenerate \(n\) independent uniform random points in a rectangle
rsystsystematic random sample of points
rjitterapply random displacements to points in a pattern

Standard point pattern datasets:

Datasets installed in the spatstat family are provided in the sub-package spatstat.data.

To manipulate a point pattern:

plot.pppplot a point pattern (e.g. plot(X))
spatstat.gui::iplotplot a point pattern interactively
edit.pppinteractive text editor
[.pppextract or replace a subset of a point pattern
pp[subset] or pp[subwindow]
subset.pppextract subset of point pattern satisfying a condition
superimposecombine several point patterns
by.pppapply a function to sub-patterns of a point pattern
cut.pppclassify the points in a point pattern
split.pppdivide pattern into sub-patterns
unmarkremove marks
npointscount the number of points
coordsextract coordinates, change coordinates
marksextract marks, change marks or attach marks
rotaterotate pattern
shift translate pattern
flipxy swap \(x\) and \(y\) coordinates
reflect reflect in the origin
periodify make several translated copies
affineapply affine transformation
scalardilateapply scalar dilation
nnmarkmark value of nearest data point
identify.pppinteractively identify points
unique.pppremove duplicate points
duplicated.pppdetermine which points are duplicates
uniquemap.pppmap duplicated points to unique points
connected.pppfind clumps of points
dirichletcompute Dirichlet-Voronoi tessellation
delaunaycompute Delaunay triangulation
delaunayDistancegraph distance in Delaunay triangulation
convexhullcompute convex hull
discretisediscretise coordinates
pixellate.pppapproximate point pattern by pixel image
as.im.pppapproximate 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).

owinCreate a window object
owin(xlim, ylim) for rectangular window
owin(poly) for polygonal window
owin(mask) for binary image window
WindowExtract window of another object
FrameExtract the containing rectangle ('frame') of another object
as.owinConvert other data to a window object
squaremake a square window
discmake a circular window
ellipsemake an elliptical window
riprasRipley-Rasson estimator of window, given only the points
convexhullcompute convex hull of something
letterRpolygonal window in the shape of the R logo
clickpolyinteractively draw a polygonal window
clickboxinteractively draw a rectangle

To manipulate a window:

plot.owinplot a window.
plot(W)
boundingboxFind a tight bounding box for the window
erosionerode window by a distance r
dilationdilate window by a distance r
closingclose window by a distance r
openingopen window by a distance r
borderdifference between window and its erosion/dilation
complement.owininvert (swap inside and outside)
simplify.owinapproximate a window by a simple polygon
rotaterotate window
flipxyswap \(x\) and \(y\) coordinates
shift translate window
periodify make several translated copies
affineapply affine transformation
as.data.frame.owinconvert window to data frame

Digital approximations:

as.maskMake a discrete pixel approximation of a given window
as.im.owinconvert window to pixel image
pixellate.owinconvert window to pixel image
commonGridfind common pixel grid for windows
nearest.raster.pointmap continuous coordinates to raster locations
raster.xraster x coordinates
raster.yraster y coordinates
raster.xyraster x and y coordinates
as.polygonalconvert pixel mask to polygonal window

See spatstat.options to control the approximation

Geometrical computations with windows:

edgesextract boundary edges
intersect.owinintersection of two windows
union.owinunion of two windows
setminus.owinset subtraction of two windows
inside.owindetermine whether a point is inside a window
area.owincompute area
perimetercompute perimeter length
diameter.owincompute diameter
incirclefind largest circle inside a window
inradiusradius of incircle
connected.owinfind connected components of window
eroded.areascompute areas of eroded windows
dilated.areascompute areas of dilated windows
bdist.pointscompute distances from data points to window boundary
bdist.pixelscompute distances from all pixels to window boundary
bdist.tilesboundary distance for each tile in tessellation
distmap.owindistance transform image
distfun.owindistance transform
centroid.owincompute centroid (centre of mass) of window
is.subset.owindetermine whether one window contains another
is.convexdetermine whether a window is convex
convexhullcompute convex hull
triangulate.owindecompose into triangles
as.maskpixel approximation of window
as.polygonalpolygonal approximation of window
is.rectangletest whether window is a rectangle
is.polygonaltest whether window is polygonal
is.masktest whether window is a mask
setcovspatial covariance function of window
pixelcentresextract centres of pixels in mask
clickdistmeasure distance between two points clicked by user

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.

imcreate a pixel image
as.imconvert other data to a pixel image
pixellateconvert other data to a pixel image
as.matrix.imconvert pixel image to matrix
as.data.frame.imconvert pixel image to data frame
as.function.imconvert pixel image to function
plot.implot a pixel image on screen as a digital image
contour.imdraw contours of a pixel image
persp.imdraw perspective plot of a pixel image
rgbimcreate colour-valued pixel image
hsvimcreate colour-valued pixel image
[.imextract a subset of a pixel image
[<-.imreplace a subset of a pixel image
rotate.imrotate pixel image
shift.imapply vector shift to pixel image
affine.imapply affine transformation to image
Xprint very basic information about image X
summary(X)summary of image X
hist.imhistogram of image
mean.immean pixel value of image
integral.imintegral of pixel values
quantile.imquantiles of image
cut.imconvert numeric image to factor image
is.imtest whether an object is a pixel image
interp.iminterpolate a pixel image
connected.imfind connected components
compatible.imtest whether two images have compatible dimensions
harmonise.immake images compatible
commonGridfind a common pixel grid for images
eval.imevaluate any expression involving images
im.applyevaluate a function of several images
scaletointervalrescale pixel values
zapsmall.imset very small pixel values to zero
levelsetlevel set of an image
solutionsetregion where an expression is true
imcovspatial covariance function of image
convolve.imspatial convolution of images
pixelcentresextract centres of pixels
transmatconvert matrix of pixel values
to a different indexing convention

Line segment patterns

An object of class "psp" represents a pattern of straight line segments.

pspcreate a line segment pattern
as.pspconvert other data into a line segment pattern
edgesextract edges of a window
is.pspdetermine whether a dataset has class "psp"
plot.pspplot a line segment pattern
print.pspprint basic information
summary.pspprint summary information
[.pspextract a subset of a line segment pattern
subset.pspextract subset of line segment pattern
as.data.frame.pspconvert line segment pattern to data frame
marks.pspextract marks of line segments
marks<-.pspassign new marks to line segments
unmark.pspdelete marks from line segments
midpoints.pspcompute the midpoints of line segments
endpoints.pspextract the endpoints of line segments
lengths_pspcompute the lengths of line segments
angles.pspcompute the orientation angles of line segments
superimposecombine several line segment patterns
flipxyswap \(x\) and \(y\) coordinates
rotate.psprotate a line segment pattern
shift.pspshift a line segment pattern
periodifymake several shifted copies
affine.pspapply an affine transformation
pixellate.pspapproximate line segment pattern by pixel image
as.mask.pspapproximate line segment pattern by binary mask
distmap.pspcompute the distance map of a line segment pattern
distfun.pspcompute the distance map of a line segment pattern
selfcrossing.pspfind crossing points between line segments
selfcut.pspcut segments where they cross
crossing.pspfind crossing points between two line segment patterns
extrapolate.pspextrapolate line segments to infinite lines
nncrossfind distance to nearest line segment from a given point
nearestsegmentfind line segment closest to a given point
project2segmentfind location along a line segment closest to a given point
pointsOnLinesgenerate points evenly spaced along line segment
rlinegridgenerate a random array of parallel lines through a window

Tessellations

An object of class "tess" represents a tessellation.

tesscreate a tessellation
quadratscreate a tessellation of rectangles
hextesscreate a tessellation of hexagons
polartesstessellation using polar coordinates
quantessquantile tessellation
venn.tessVenn diagram tessellation
dirichletcompute Dirichlet-Voronoi tessellation of points
delaunaycompute Delaunay triangulation of points
as.tessconvert other data to a tessellation
plot.tessplot a tessellation
tilesextract all the tiles of a tessellation
[.tessextract some tiles of a tessellation
[<-.tesschange some tiles of a tessellation
intersect.tessintersect two tessellations
or restrict a tessellation to a window
chop.tesssubdivide a tessellation by a line
tile.areasarea of each tile in tessellation
bdist.tilesboundary distance for each tile in tessellation
connected.tessfind connected components of tiles
shift.tessshift a tessellation
rotate.tessrotate a tessellation
reflect.tessreflect about the origin
flipxy.tessreflect about the diagonal
affine.tessapply affine transformation

Three-dimensional point patterns

An object of class "pp3" represents a three-dimensional point pattern in a rectangular box. The box is represented by an object of class "box3".

pp3create a 3-D point pattern
plot.pp3plot a 3-D point pattern
coordsextract coordinates
as.hyperframeextract coordinates
subset.pp3extract subset of 3-D point pattern
unitname.pp3name of unit of length
npointscount the number of points
box3create a 3-D rectangular box
as.box3convert data to 3-D rectangular box
unitname.box3name of unit of length
diameter.box3diameter of box
volume.box3volume of box
shortside.box3shortest side of box
eroded.volumesvolumes of erosions of box

Multi-dimensional space-time point patterns

An object of class "ppx" represents a point pattern in multi-dimensional space and/or time.

ppxcreate a multidimensional space-time point pattern
coordsextract coordinates
as.hyperframeextract coordinates
subset.ppxextract subset
unitname.ppxname of unit of length
npointscount the number of points
boxxdefine multidimensional box
diameter.boxxdiameter of box
volume.boxxvolume of box
shortside.boxxshortest side of box
eroded.volumes.boxxvolumes of erosions of box

Linear networks

An object of class "linnet" represents a linear network (for example, a road network). This is supported in the sub-package spatstat.linnet.

An object of class "lpp" represents a point pattern on a linear network (for example, road accidents on a road network).

Hyperframes

A hyperframe is like a data frame, except that the entries may be objects of any kind.

hyperframecreate a hyperframe
as.hyperframeconvert data to hyperframe
plot.hyperframeplot hyperframe
with.hyperframeevaluate expression using each row of hyperframe
cbind.hyperframecombine hyperframes by columns
rbind.hyperframecombine hyperframes by rows
as.data.frame.hyperframeconvert hyperframe to data frame
subset.hyperframemethod for subset
head.hyperframefirst few rows of hyperframe
tail.hyperframelast few rows of hyperframe

Layered objects

A layered object represents data that should be plotted in successive layers, for example, a background and a foreground.

layeredcreate layered object
plot.layeredplot layered object
[.layeredextract subset of layered object

Colour maps

A colour map is a mechanism for associating colours with data. It can be regarded as a function, mapping data to colours. Using a colourmap object in a plot command ensures that the mapping from numbers to colours is the same in different plots.

colourmapcreate a colour map
plot.colourmapplot the colour map only
tweak.colourmapalter individual colour values
interp.colourmapmake a smooth transition between colours
beachcolourmapone special colour map

Inspection of data:

summary(X)print useful summary of point pattern X
Xprint basic description of point pattern X
any(duplicated(X))check for duplicated points in pattern X
intensityMean intensity
quadratcountQuadrat counts

Distances in a point pattern:

nndistnearest neighbour distances
nnwhichfind nearest neighbours
pairdistdistances between all pairs of points
crossdistdistances between points in two patterns
nncrossnearest neighbours between two point patterns
exactdtdistance from any location to nearest data point
distmapdistance map image
distfundistance map function
nnmapnearest point image
nnfunnearest point function

Programming tools:

applynbdapply function to every neighbourhood in a point pattern
markstatapply function to the marks of neighbours in a point pattern
pppdistfind the optimal match between two point patterns

Distances in a three-dimensional point pattern:

pairdist.pp3distances between all pairs of points
crossdist.pp3distances between points in two patterns
nndist.pp3nearest neighbour distances
nnwhich.pp3find nearest neighbours
nncross.pp3find nearest neighbours in another pattern

Distances in multi-dimensional point pattern:

These are for multi-dimensional space-time point pattern objects (class ppx).

pairdist.ppxdistances between all pairs of points
crossdist.ppxdistances between points in two patterns
nndist.ppxnearest neighbour distances
nnwhich.ppxfind nearest neighbours

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.

Author

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

Acknowledgements

Kasper Klitgaard Berthelsen, Ottmar Cronie, Tilman Davies, Yongtao Guan, Ute Hahn, Abdollah Jalilian, Marie-Colette van Lieshout, Greg McSwiggan, Tuomas Rajala, Suman Rakshit, Dominic Schuhmacher, Rasmus Waagepetersen and Hangsheng Wang made substantial contributions of code.

Additional contributions and suggestions from Monsuru Adepeju, Corey Anderson, Ang Qi Wei, Ryan Arellano, Jens Astrom, Robert Aue, Marcel Austenfeld, Sandro Azaele, Malissa Baddeley, Guy Bayegnak, Colin Beale, Melanie Bell, Thomas Bendtsen, Ricardo Bernhardt, Andrew Bevan, Brad Biggerstaff, Anders Bilgrau, Leanne Bischof, Christophe Biscio, Roger Bivand, Jose M. Blanco Moreno, Florent Bonneu, Jordan Brown, Ian Buller, Julian Burgos, Simon Byers, Ya-Mei Chang, Jianbao Chen, Igor Chernayavsky, Y.C. Chin, Bjarke Christensen, Lucia Cobo Sanchez, Jean-Francois Coeurjolly, Kim Colyvas, Hadrien Commenges, Rochelle Constantine, Robin Corria Ainslie, Richard Cotton, Marcelino de la Cruz, Peter Dalgaard, Mario D'Antuono, Sourav Das, Peter Diggle, Patrick Donnelly, Ian Dryden, Stephen Eglen, Ahmed El-Gabbas, Belarmain Fandohan, Olivier Flores, David Ford, Peter Forbes, Shane Frank, Janet Franklin, Funwi-Gabga Neba, Oscar Garcia, Agnes Gault, Jonas Geldmann, Marc Genton, Shaaban Ghalandarayeshi, Julian Gilbey, Jason Goldstick, Pavel Grabarnik, C. Graf, Ute Hahn, Andrew Hardegen, Martin Bogsted Hansen, Martin Hazelton, Juha Heikkinen, Mandy Hering, Markus Herrmann, Maximilian Hesselbarth, Paul Hewson, Hamidreza Heydarian, Kassel Hingee, Kurt Hornik, Philipp Hunziker, Jack Hywood, Ross Ihaka, Cenk Icos, Aruna Jammalamadaka, Robert John-Chandran, Devin Johnson, Mahdieh Khanmohammadi, Bob Klaver, Lily Kozmian-Ledward, Peter Kovesi, Mike Kuhn, Jeff Laake, Robert Lamb, Frederic Lavancier, Tom Lawrence, Tomas Lazauskas, Jonathan Lee, George Leser, Angela Li, Li Haitao, George Limitsios, Andrew Lister, Nestor Luambua, Ben Madin, Martin Maechler, Kiran Marchikanti, Jeff Marcus, Robert Mark, Peter McCullagh, Monia Mahling, Jorge Mateu Mahiques, Ulf Mehlig, Frederico Mestre, Sebastian Wastl Meyer, Mi Xiangcheng, Lore De Middeleer, Robin Milne, Enrique Miranda, Jesper Moller, Annie Mollie, Ines Moncada, Mehdi Moradi, Virginia Morera Pujol, Erika Mudrak, Gopalan Nair, Nader Najari, Nicoletta Nava, Linda Stougaard Nielsen, Felipe Nunes, Jens Randel Nyengaard, Jens Oehlschlaegel, Thierry Onkelinx, Sean O'Riordan, Evgeni Parilov, Jeff Picka, Nicolas Picard, Tim Pollington, Mike Porter, Sergiy Protsiv, Adrian Raftery, Suman Rakshit, Ben Ramage, Pablo Ramon, Xavier Raynaud, Nicholas Read, Matt Reiter, Ian Renner, Tom Richardson, Brian Ripley, Ted Rosenbaum, Barry Rowlingson, Jason Rudokas, Tyler Rudolph, John Rudge, Christopher Ryan, Farzaneh Safavimanesh, Aila Sarkka, Cody Schank, Katja Schladitz, Sebastian Schutte, Bryan Scott, Olivia Semboli, Francois Semecurbe, Vadim Shcherbakov, Shen Guochun, Shi Peijian, Harold-Jeffrey Ship, Tammy L Silva, Ida-Maria Sintorn, Yong Song, Malte Spiess, Mark Stevenson, Kaspar Stucki, Jan Sulavik, Michael Sumner, P. Surovy, Ben Taylor, Thordis Linda Thorarinsdottir, Leigh Torres, Berwin Turlach, Torben Tvedebrink, Kevin Ummer, Medha Uppala, Andrew van Burgel, Tobias Verbeke, Mikko Vihtakari, Alexendre Villers, Fabrice Vinatier, Maximilian Vogtland, Sasha Voss, Sven Wagner, Hao Wang, H. Wendrock, Jan Wild, Carl G. Witthoft, Selene Wong, Maxime Woringer, Luke Yates, Mike Zamboni and Achim Zeileis.

Details

spatstat is a family of R packages for the statistical analysis of spatial data. Its main focus is the analysis of spatial patterns of points in two-dimensional space.

The original spatstat package has now been split into several sub-packages.

This sub-package spatstat.geom defines the main classes of geometrical objects (such as windows, point patterns, line segment patterns, pixel images) and supports geometrical operations (such as shifting and rotating, measuring areas and distances, finding nearest neighbours in a point pattern).

Functions for performing statistical analysis and modelling are in the separate sub-packages spatstat.explore and spatstat.model.

Functions for linear networks are in the separate sub-package spatstat.linnet.

For an overview of all the functions available in the spatstat family, see the help file for spatstat in the spatstat package.