spatstat.model-package: The spatstat.model Package
In spatstat.model: Parametric Statistical Modelling and Inference for the 'spatstat' Family

spatstat.model-package

R Documentation

The spatstat.model Package

Description

The spatstat.model package belongs to the spatstat family of packages. It contains the core functionality for parametric statistical modelling of spatial data.

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.model contains all the main user-level functions that perform parametric statistical modelling of spatial data.

(The main exception is that functions for linear networks are in the separate sub-package spatstat.linnet.)

Structure of the spatstat family

The orginal spatstat package grew to be very large. It has now been divided into several sub-packages:

spatstat.utils containing basic utilities
spatstat.sparse containing linear algebra utilities
spatstat.data containing datasets
spatstat.univar containing functions for estimating probability distributions of random variables
spatstat.geom containing geometrical objects and geometrical operations
spatstat.explore containing the functionality for exploratory analysis and nonparametric modelling of spatial data
spatstat.model containing the main functionality for parametric modelling, analysis 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 the sub-packages of spatstat, see the help file for "spatstat-package" 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 Functionality in spatstat.model

The spatstat family of packages is designed to support a complete statistical analysis of spatial data. It supports

creation, manipulation and plotting of point patterns;
exploratory data analysis;
spatial random sampling;
simulation of point process models;
parametric model-fitting;
non-parametric smoothing and regression;
formal inference (hypothesis tests, confidence intervals);
model diagnostics.

For an overview, see the help file for "spatstat-package" in the spatstat package.

Following is a list of the functionality provided in the spatstat.model package only.

To simulate a random point pattern:

Functions for generating random point patterns are now contained in the spatstat.random package.

Exploratory analysis

Exploratory graphics, smoothing, and exploratory analysis of spatial data are now provided in the spatstat.explore package.

Model fitting (Cox and cluster models)

Cluster process models (with homogeneous or inhomogeneous intensity) and Cox processes 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.

`kppm`	Fit model
`plot.kppm`	Plot the fitted model
`summary.kppm`	Summarise the fitted model
`fitted.kppm`	Compute fitted intensity
`predict.kppm`	Compute fitted intensity
`update.kppm`	Update the model
`improve.kppm`	Refine the estimate of trend
`simulate.kppm`	Generate simulated realisations
`vcov.kppm`	Variance-covariance matrix of coefficients
`coef.kppm`	Extract trend coefficients
`formula.kppm`	Extract trend formula
`parameters`	Extract all model parameters
`clusterfield.kppm`	Compute offspring density
`clusterradius.kppm`	Radius of support of offspring density
`Kmodel.kppm`	`K` function of fitted model
`pcfmodel.kppm`	Pair correlation of fitted model

For model selection, you can also use the generic functions step, drop1 and AIC on fitted point process models. For variable selection, see sdr.

The theoretical models can also be simulated, for any choice of parameter values, using rThomas, rMatClust, rCauchy, rVarGamma, and rLGCP.

Lower-level fitting functions include:

`lgcp.estK`	fit a log-Gaussian Cox process model
`lgcp.estpcf`	fit a log-Gaussian Cox process model
`thomas.estK`	fit the Thomas process model
`thomas.estpcf`	fit the Thomas process model
`matclust.estK`	fit the \Matern Cluster process model
`matclust.estpcf`	fit the \Matern Cluster process model
`cauchy.estK`	fit a Neyman-Scott Cauchy cluster process
`cauchy.estpcf`	fit a Neyman-Scott Cauchy cluster process
`vargamma.estK`	fit a Neyman-Scott Variance Gamma process
`vargamma.estpcf`	fit a Neyman-Scott Variance Gamma process
`mincontrast`	low-level algorithm for fitting models
	by the method of minimum contrast

Model fitting (Poisson and Gibbs models)

Poisson point processes are the simplest models for point patterns. A Poisson model assumes that the points are stochastically independent. It may allow the points to have a non-uniform spatial density. The special case of a Poisson process with a uniform spatial density is often called Complete Spatial Randomness.

Poisson point processes are included in the more general class of Gibbs point process models. In a Gibbs model, there is interaction or dependence between points. Many different types of interaction can be specified.

For a detailed explanation of how to fit Poisson or Gibbs point process models to point pattern data using spatstat, see Baddeley and Turner (2005b) or Baddeley (2008).

To fit a Poisson or Gibbs point process model:

Model fitting in spatstat is performed mainly by the function ppm. Its result is an object of class "ppm".

Here are some examples, where X is a point pattern (class "ppp"):

command	model
`ppm(X)`	Complete Spatial Randomness
`ppm(X ~ 1)`	Complete Spatial Randomness
`ppm(X ~ x)`	Poisson process with
	intensity loglinear in `x` coordinate
`ppm(X ~ 1, Strauss(0.1))`	Stationary Strauss process
`ppm(X ~ x, Strauss(0.1))`	Strauss process with
	conditional intensity loglinear in `x`

It is also possible to fit models that depend on other covariates.

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
`parameters`	Extract all model parameters
`formula.ppm`	Extract the trend formula
`intensity.ppm`	Compute fitted intensity
`Kmodel.ppm`	`K` function of fitted model
`pcfmodel.ppm`	pair correlation of fitted model
`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
`model.frame.ppm`	Extract data frame used to fit model
`model.images`	Extract spatial data used to fit model
`model.depends`	Identify variables in the model
`as.interact`	Interpoint interaction component of model
`fitin`	Extract fitted interpoint interaction
`is.hybrid`	Determine whether the model is a hybrid
`valid.ppm`	Check the model is a valid point process
`project.ppm`	Ensure the model is a valid point process

For model selection, you can also use the generic functions step, drop1 and AIC on fitted point process models. For variable selection, see sdr.

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.

`X ~ 1`	No trend (stationary)
`X ~ x`	Loglinear trend `\lambda(x,y) = \exp(\alpha + \beta x)`
	where `x,y` are Cartesian coordinates
`X ~ polynom(x,y,3)`	Log-cubic polynomial trend
`X ~ harmonic(x,y,2)`	Log-harmonic polynomial trend
`X ~ Z`	Loglinear function of covariate `Z`
	`\lambda(x,y) = \exp(\alpha + \beta Z(x,y))`

The higher order (“interaction”) components are described by an object of class "interact". Such objects are created by:

`Poisson()`	the Poisson point process
`AreaInter()`	Area-interaction process
`BadGey()`	multiscale Geyer process
`Concom()`	connected component interaction
`DiggleGratton()`	Diggle-Gratton potential
`DiggleGatesStibbard()`	Diggle-Gates-Stibbard potential
`Fiksel()`	Fiksel pairwise interaction process
`Geyer()`	Geyer's saturation process
`Hardcore()`	Hard core process
`HierHard()`	Hierarchical multiype hard core process
`HierStrauss()`	Hierarchical multiype Strauss process
`HierStraussHard()`	Hierarchical multiype Strauss-hard core process
`Hybrid()`	Hybrid of several interactions
`LennardJones()`	Lennard-Jones potential
`MultiHard()`	multitype hard core process
`MultiStrauss()`	multitype Strauss process
`MultiStraussHard()`	multitype Strauss/hard core process
`OrdThresh()`	Ord process, threshold potential
`Ord()`	Ord model, user-supplied potential
`PairPiece()`	pairwise interaction, piecewise constant
`Pairwise()`	pairwise interaction, user-supplied potential
`Penttinen()`	Penttinen pairwise interaction
`SatPiece()`	Saturated pair model, piecewise constant potential
`Saturated()`	Saturated pair model, user-supplied potential
`Softcore()`	pairwise interaction, soft core potential
`Strauss()`	Strauss process
`StraussHard()`	Strauss/hard core point process
`Triplets()`	Geyer triplets process

Note that it is also possible to combine several such interactions using Hybrid.

Simulation and goodness-of-fit for fitted models:

`rmh.ppm`	simulate realisations of a fitted model
`simulate.ppm`	simulate realisations of a fitted model
`envelope`	compute simulation envelopes for a fitted model

Model fitting (determinantal point process models)

Code for fitting determinantal point process models has recently been added to spatstat.

For information, see the help file for dppm.

Model fitting (spatial logistic regression)

Pixel-based spatial logistic regression is an alternative technique for analysing spatial point patterns that is widely used in Geographical Information Systems. It is approximately equivalent to fitting a Poisson point process model.

In pixel-based logistic regression, the spatial domain is divided into small pixels, the presence or absence of a data point in each pixel is recorded, and logistic regression is used to model the presence/absence indicators as a function of any covariates.

Facilities for performing spatial logistic regression are provided in spatstat for comparison purposes.

Fitting a spatial logistic regression

Spatial logistic regression is performed by the function slrm. Its result is an object of class "slrm". There are many methods for this class, including methods for print, fitted, predict, simulate, anova, coef, logLik, terms, update, formula and vcov.

For example, if X is a point pattern (class "ppp"):

command	model
`slrm(X ~ 1)`	Complete Spatial Randomness
`slrm(X ~ x)`	Poisson process with
	intensity loglinear in `x` coordinate
`slrm(X ~ Z)`	Poisson process with
	intensity loglinear in covariate `Z`

Manipulating a fitted spatial logistic regression

`anova.slrm`	Analysis of deviance
`coef.slrm`	Extract fitted coefficients
`vcov.slrm`	Variance-covariance matrix of fitted coefficients
`fitted.slrm`	Compute fitted probabilities or intensity
`logLik.slrm`	Evaluate loglikelihood of fitted model
`plot.slrm`	Plot fitted probabilities or intensity
`predict.slrm`	Compute predicted probabilities or intensity with new data
`simulate.slrm`	Simulate model

There are many other undocumented methods for this class, including methods for print, update, formula and terms. Stepwise model selection is possible using step or stepAIC. For variable selection, see sdr.

Simulation

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

Random point patterns: Functions for random generation are now contained in the spatstat.random package.

See also varblock for estimating the variance of a summary statistic by block resampling, and lohboot for another bootstrap technique.

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.ppm. To generate one or more simulated realisations of the fitted model, use simulate.ppm.

Other random patterns: Functions for random generation are now contained in the spatstat.random package.

Simulation-based inference

Simulation-based inference including simulation envelopes and hypothesis tests is now supported by the package spatstat.explore.

Sensitivity diagnostics:

Classical measures of model sensitivity such as leverage and influence have been adapted to point process models.

`leverage.ppm`	Leverage for point process model
`influence.ppm`	Influence for point process model
`dfbetas.ppm`	Parameter influence
`dffit.ppm`	Effect change diagnostic

Diagnostics for covariate effect:

Classical diagnostics for covariate effects have been adapted to point process models.

`parres`	Partial residual plot
`addvar`	Added variable plot
`rhohat.ppm`	Kernel estimate of covariate effect
`rho2hat`	Kernel estimate of covariate effect (bivariate)

Residual diagnostics:

Residuals for a fitted point process model, and diagnostic plots based on the residuals, were introduced in Baddeley et al (2005) and Baddeley, Rubak and \Moller (2011).

Type demo(diagnose) for a demonstration of the diagnostics features.

`diagnose.ppm`	diagnostic plots for spatial trend
`qqplot.ppm`	diagnostic Q-Q plot for interpoint interaction
`residualspaper`	examples from Baddeley et al (2005)
`Kcom`	model compensator of `K` function
`Gcom`	model compensator of `G` function
`Kres`	score residual of `K` function
`Gres`	score residual of `G` function
`psst`	pseudoscore residual of summary function
`psstA`	pseudoscore residual of empty space function
`psstG`	pseudoscore residual of `G` function
`compareFit`	compare compensators of several fitted models

Resampling and randomisation procedures

You can build your own tests based on randomisation and resampling using the following capabilities:

`quadratresample`	block resampling
`rshift`	random shifting of (subsets of) points
`rthin`	random thinning

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, Julian Gilbey, Yongtao Guan, Ute Hahn, Kassel Hingee, Abdollah Jalilian, Marie-Colette van Lieshout, Greg McSwiggan, Tuomas Rajala, Suman Rakshit, Dominic Schuhmacher, Rasmus Waagepetersen and Hangsheng Wang made substantial contributions of code.

For comments, corrections, bug alerts and suggestions, we thank 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, 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, 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, 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.