spatstat.geom-package: The spatstat.geom Package
In spatstat.geom: Geometrical Functionality of the 'spatstat' Family

spatstat.geom-package

R Documentation

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.univar containing functions for estimating probability distributions of random variables
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
`persp.ppp`	perspective plot of marked point pattern
`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.