spatstat.geom-package {spatstat.geom}

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.

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.

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:

ppp	point pattern
owin	window (spatial region)
im	pixel image
psp	line segment pattern
tess	tessellation
pp3	three-dimensional point pattern
ppx	point pattern in any number of dimensions

Additional data types are supported in spatstat.linnet.

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

runifrect	generate n independent uniform random points in a rectangle
rsyst	systematic random sample of points
rjitter	apply 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.ppp	plot a point pattern (e.g. plot(X))
spatstat.gui::iplot	plot a point pattern interactively
edit.ppp	interactive text editor
[.ppp	extract or replace a subset of a point pattern
	pp[subset] or pp[subwindow]
subset.ppp	extract subset of point pattern satisfying a condition
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
split.ppp	divide pattern into sub-patterns
unmark	remove marks
npoints	count the number of points
coords	extract coordinates, change coordinates
marks	extract marks, change marks or attach marks
rotate	rotate pattern
shift	translate pattern
flipxy	swap x and y coordinates
reflect	reflect in the origin
periodify	make several translated copies
affine	apply affine transformation
scalardilate	apply scalar dilation
nnmark	mark value of nearest data point
identify.ppp	interactively identify points
unique.ppp	remove duplicate points
duplicated.ppp	determine which points are duplicates
uniquemap.ppp	map duplicated points to unique points
connected.ppp	find clumps of points
dirichlet	compute Dirichlet-Voronoi tessellation
delaunay	compute Delaunay triangulation
delaunayDistance	graph distance in Delaunay triangulation
convexhull	compute convex hull
discretise	discretise coordinates
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).

owin	Create a window object
	owin(xlim, ylim) for rectangular window
	owin(poly) for polygonal window
	owin(mask) for binary image window
Window	Extract window of another object
Frame	Extract the containing rectangle ('frame') of another object
as.owin	Convert other data to a window object
square	make a square window
disc	make a circular window
ellipse	make an elliptical 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 R logo
clickpoly	interactively draw a polygonal window
clickbox	interactively draw a rectangle

To manipulate a window:

plot.owin	plot a window.
	plot(W)
boundingbox	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
border	difference between window and its erosion/dilation
complement.owin	invert (swap inside and outside)
simplify.owin	approximate a window by a simple polygon
rotate	rotate window
flipxy	swap x and y coordinates
shift	translate window
periodify	make several translated copies
affine	apply affine transformation
as.data.frame.owin	convert window to data frame

Digital approximations:

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
commonGrid	find common pixel grid for windows
nearest.raster.point	map continuous coordinates to raster locations
raster.x	raster x coordinates
raster.y	raster y coordinates
raster.xy	raster x and y coordinates
as.polygonal	convert pixel mask to polygonal window

See spatstat.options to control the approximation

Geometrical computations with windows:

edges	extract boundary edges
intersect.owin	intersection of two windows
union.owin	union of two windows
setminus.owin	set subtraction of two windows
inside.owin	determine whether a point is inside a window
area.owin	compute area
perimeter	compute perimeter length
diameter.owin	compute diameter
incircle	find largest circle inside a window
inradius	radius of incircle
connected.owin	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
bdist.tiles	boundary distance for each tile in tessellation
distmap.owin	distance transform image
distfun.owin	distance transform
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
triangulate.owin	decompose into triangles
as.mask	pixel approximation of window
as.polygonal	polygonal approximation of window
is.rectangle	test whether window is a rectangle
is.polygonal	test whether window is polygonal
is.mask	test whether window is a mask
setcov	spatial covariance function of window
pixelcentres	extract centres of pixels in mask
clickdist	measure 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.

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
as.data.frame.im	convert pixel image to data frame
as.function.im	convert pixel image to function
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
rgbim	create colour-valued pixel image
hsvim	create colour-valued pixel image
[.im	extract a subset of a pixel image
[<-.im	replace a subset of a pixel image
rotate.im	rotate pixel image
shift.im	apply vector shift to pixel image
affine.im	apply affine transformation to 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
integral.im	integral of pixel values
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
connected.im	find connected components
compatible.im	test whether two images have compatible dimensions
harmonise.im	make images compatible
commonGrid	find a common pixel grid for images
eval.im	evaluate any expression involving images
im.apply	evaluate a function of several images
scaletointerval	rescale pixel values
zapsmall.im	set very small pixel values to zero
levelset	level set of an image
solutionset	region where an expression is true
imcov	spatial covariance function of image
convolve.im	spatial convolution of images
pixelcentres	extract centres of pixels
transmat	convert matrix of pixel values
	to a different indexing convention

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
edges	extract edges of a window
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
subset.psp	extract subset of 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
superimpose	combine several line segment patterns
flipxy	swap x and y coordinates
rotate.psp	rotate a line segment pattern
shift.psp	shift a line segment pattern
periodify	make several shifted copies
affine.psp	apply an affine transformation
pixellate.psp	approximate line segment pattern by pixel image
as.mask.psp	approximate line segment pattern by binary mask
distmap.psp	compute the distance map of a line segment pattern
distfun.psp	compute the distance map of a line segment pattern
selfcrossing.psp	find crossing points between line segments
selfcut.psp	cut segments where they cross
crossing.psp	find crossing points between two line segment patterns
extrapolate.psp	extrapolate line segments to infinite lines
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
rlinegrid	generate a random array of parallel lines through a window

Tessellations

An object of class "tess" represents a tessellation.

tess	create a tessellation
quadrats	create a tessellation of rectangles
hextess	create a tessellation of hexagons
polartess	tessellation using polar coordinates
quantess	quantile tessellation
venn.tess	Venn diagram tessellation
dirichlet	compute Dirichlet-Voronoi tessellation of points
delaunay	compute Delaunay triangulation of points
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
tile.areas	area of each tile in tessellation
bdist.tiles	boundary distance for each tile in tessellation
connected.tess	find connected components of tiles
shift.tess	shift a tessellation
rotate.tess	rotate a tessellation
reflect.tess	reflect about the origin
flipxy.tess	reflect about the diagonal
affine.tess	apply 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".

pp3	create a 3-D point pattern
plot.pp3	plot a 3-D point pattern
coords	extract coordinates
as.hyperframe	extract coordinates
subset.pp3	extract subset of 3-D point pattern
unitname.pp3	name of unit of length
npoints	count the number of points
box3	create a 3-D rectangular box
as.box3	convert data to 3-D rectangular box
unitname.box3	name of unit of length
diameter.box3	diameter of box
volume.box3	volume of box
shortside.box3	shortest side of box
eroded.volumes	volumes 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.

ppx	create a multidimensional space-time point pattern
coords	extract coordinates
as.hyperframe	extract coordinates
subset.ppx	extract subset
unitname.ppx	name of unit of length
npoints	count the number of points
boxx	define multidimensional box
diameter.boxx	diameter of box
volume.boxx	volume of box
shortside.boxx	shortest side of box
eroded.volumes.boxx	volumes 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.

hyperframe	create a hyperframe
as.hyperframe	convert data to hyperframe
plot.hyperframe	plot hyperframe
with.hyperframe	evaluate expression using each row of hyperframe
cbind.hyperframe	combine hyperframes by columns
rbind.hyperframe	combine hyperframes by rows
as.data.frame.hyperframe	convert hyperframe to data frame
subset.hyperframe	method for subset
head.hyperframe	first few rows of hyperframe
tail.hyperframe	last 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.

layered	create layered object
plot.layered	plot layered object
[.layered	extract 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.

colourmap	create a colour map
plot.colourmap	plot the colour map only
tweak.colourmap	alter individual colour values
interp.colourmap	make a smooth transition between colours
beachcolourmap	one special colour map

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
intensity	Mean intensity
quadratcount	Quadrat counts

Distances in a point pattern:

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
distfun	distance map function
nnmap	nearest point image
nnfun	nearest point function

Programming tools:

applynbd	apply function to every neighbourhood in a point pattern
markstat	apply function to the marks of neighbours in a point pattern
pppdist	find the optimal match between two point patterns

Distances in a three-dimensional point pattern:

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

Distances in multi-dimensional point pattern:

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

pairdist.ppx	distances between all pairs of points
crossdist.ppx	distances between points in two patterns
nndist.ppx	nearest neighbour distances
nnwhich.ppx	find 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.

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.

Author(s)

Adrian Baddeley [e-mail], Rolf Turner [e-mail] and Ege Rubak [e-mail].