Version:	3.5-2
Date:	2025-07-22
Title:	Exploratory Data Analysis for the 'spatstat' Family
Maintainer:	Adrian Baddeley <Adrian.Baddeley@curtin.edu.au>
Depends:	R (≥ 3.5.0), spatstat.data (≥ 3.1-2), spatstat.univar (≥ 3.1-4), spatstat.geom (≥ 3.5-0), spatstat.random (≥ 3.4), stats, graphics, grDevices, utils, methods, nlme
Imports:	spatstat.utils (≥ 3.1-5), spatstat.sparse (≥ 3.1-0), goftest (≥ 1.2-2), Matrix, abind
Suggests:	sm, gsl, locfit, spatial, fftwtools (≥ 0.9-8), spatstat.linnet (≥ 3.2-1), spatstat.model (≥ 3.3-1), spatstat (≥ 3.3)
Description:	Functionality for exploratory data analysis and nonparametric analysis of spatial data, mainly spatial point patterns, in the 'spatstat' family of packages. (Excludes analysis of spatial data on a linear network, which is covered by the separate package 'spatstat.linnet'.) Methods include quadrat counts, K-functions and their simulation envelopes, nearest neighbour distance and empty space statistics, Fry plots, pair correlation function, kernel smoothed intensity, relative risk estimation with cross-validated bandwidth selection, mark correlation functions, segregation indices, mark dependence diagnostics, and kernel estimates of covariate effects. Formal hypothesis tests of random pattern (chi-squared, Kolmogorov-Smirnov, Monte Carlo, Diggle-Cressie-Loosmore-Ford, Dao-Genton, two-stage Monte Carlo) and tests for covariate effects (Cox-Berman-Waller-Lawson, Kolmogorov-Smirnov, ANOVA) are also supported.
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
URL:	http://spatstat.org/
NeedsCompilation:	yes
ByteCompile:	true
BugReports:	https://github.com/spatstat/spatstat.explore/issues
Packaged:	2025-07-22 02:39:14 UTC; adrian
Author:	Adrian Baddeley [aut, cre, cph], Rolf Turner [aut, cph], Ege Rubak [aut, cph], Kasper Klitgaard Berthelsen [ctb], Warick Brown [cph], Achmad Choiruddin [ctb], Ya-Mei Chang [ctb], Jean-Francois Coeurjolly [ctb], Ottmar Cronie [ctb], Tilman Davies [ctb, cph], Julian Gilbey [ctb], Jonatan Gonzalez [ctb], Yongtao Guan [ctb], Ute Hahn [ctb], Martin Hazelton [ctb], Kassel Hingee [ctb, cph], Abdollah Jalilian [ctb], Frederic Lavancier [ctb], Marie-Colette van Lieshout [ctb, cph], Greg McSwiggan [ctb], Robin K Milne [cph], Tuomas Rajala [ctb], Suman Rakshit [ctb, cph], Dominic Schuhmacher [ctb], Rasmus Plenge Waagepetersen [ctb], Hangsheng Wang [ctb], Tingting Zhan [ctb]
Repository:	CRAN
Date/Publication:	2025-07-22 04:40:33 UTC

The spatstat.explore Package

Description

The spatstat.explore package belongs to the spatstat family of packages. It contains the core functionality for statistical analysis and 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.explore contains the user-level functions that perform exploratory data analysis and nonparametric data analysis 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 data analysis and nonparametric analysis of spatial data.

• spatstat.model containing the functionality for statistical modelling, model-fitting, formal statistical inference and informal model diagnostics.

• 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.explore

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.explore package only.

To simulate a random point pattern:

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

To interrogate a point pattern:

Manipulation of pixel images:

An object of class "im" represents a pixel image.

Line segment patterns

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

Tessellations

An object of class "tess" represents a tessellation.

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".

Multi-dimensional space-time point patterns

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

Classical exploratory tools:

Smoothing:

Modern exploratory tools:

Summary statistics for a point pattern:

Selecting the bandwidth for kernel estimation of the summary function:

Related facilities:

Summary statistics for a multitype point pattern: A multitype point pattern is represented by an object X of class "ppp" such that marks(X) is a factor.

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:

For marks of any type, there are the following:

Alternatively use cut.ppp to convert a marked point pattern to a multitype point pattern.

Programming tools:

Summary statistics for a three-dimensional point pattern:

These are for 3-dimensional point pattern objects (class pp3).

Related facilities:

Summary statistics for random sets:

These work for point patterns (class ppp), line segment patterns (class psp) or windows (class owin).

Model fitting

Functions for fitting point process models are now contained in the spatstat.model package.

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.

Methods for simulating a fitted model are now contained in the spatstat.model package.

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

Simulation-based inference

Manipulation of envelope objects:

Hypothesis tests:

More recently-developed tests:

Model diagnostics:

Classical measures of model sensitivity such as leverage and influence, and classical model diagnostic tools such as residuals, partial residuals, and effect estimates, have been adapted to point process models. These capabilities are now provided in the spatstat.model package.

Resampling and randomisation procedures

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

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.

Author(s)

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

Diagnostics for random marking

Description

Estimate the summary functions E(r) and V(r) for a marked point pattern, proposed by Schlather et al (2004) as diagnostics for dependence between the points and the marks.

Usage

Emark(X, r=NULL,
         correction=c("isotropic", "Ripley", "translate"),
         method="density", ..., normalise=FALSE)
Vmark(X, r=NULL,
         correction=c("isotropic", "Ripley", "translate"),
         method="density", ..., normalise=FALSE)

Arguments

Details

For a marked point process, Schlather et al (2004) defined the functions E(r) and V(r) to be the conditional mean and conditional variance of the mark attached to a typical random point, given that there exists another random point at a distance r away from it.

More formally,

E(r) = E_{0u}[M(0)]

and

V(r) = E_{0u}[(M(0)-E(u))^2]

where E_{0u} denotes the conditional expectation given that there are points of the process at the locations 0 and u separated by a distance r, and where M(0) denotes the mark attached to the point 0.

These functions may serve as diagnostics for dependence between the points and the marks. If the points and marks are independent, then E(r) and V(r) should be constant (not depending on r). See Schlather et al (2004).

The argument X must be a point pattern (object of class "ppp") or any data that are acceptable to as.ppp. It must be a marked point pattern with numeric marks.

The argument r is the vector of values for the distance r at which k_f(r) is estimated.

This algorithm assumes that X can be treated as a realisation of a stationary (spatially homogeneous) random spatial point process in the plane, observed through a bounded window. The window (which is specified in X as Window(X)) may have arbitrary shape.

Biases due to edge effects are treated in the same manner as in Kest. The edge corrections implemented here are

isotropic/Ripley

Ripley's isotropic correction (see Ripley, 1988; Ohser, 1983). This is implemented only for rectangular and polygonal windows (not for binary masks).

translate

Translation correction (Ohser, 1983). Implemented for all window geometries, but slow for complex windows.

Note that the estimator assumes the process is stationary (spatially homogeneous).

The numerator and denominator of the mark correlation function (in the expression above) are estimated using density estimation techniques. The user can choose between

"density"

which uses the standard kernel density estimation routine density, and works only for evenly-spaced r values;

"loess"

which uses the function loess in the package modreg;

"sm"

which uses the function sm.density in the package sm and is extremely slow;

"smrep"

which uses the function sm.density in the package sm and is relatively fast, but may require manual control of the smoothing parameter hmult.

Value

If marks(X) is a numeric vector, the result is an object of class "fv" (see fv.object). If marks(X) is a data frame, the result is a list of objects of class "fv", one for each column of marks.

An object of class "fv" is essentially a data frame containing numeric columns

together with a column or columns named "iso" and/or "trans", according to the selected edge corrections. These columns contain estimates of the function E(r) or V(r) obtained by the edge corrections named.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

References

Schlather, M. and Ribeiro, P. and Diggle, P. (2004) Detecting dependence between marks and locations of marked point processes. Journal of the Royal Statistical Society, series B 66 (2004) 79-83.

See Also

Mark correlation markcorr, mark variogram markvario for numeric marks.

Mark connection function markconnect and multitype K-functions Kcross, Kdot for factor-valued marks.

Examples

    plot(Emark(spruces))
    E <- Emark(spruces, method="density", kernel="epanechnikov")
    plot(Vmark(spruces))

    plot(Emark(finpines))
    V <- Vmark(finpines)

Extract Subset of Function Array

Description

Extract a subset of a function array (an object of class "fasp").

Usage

  ## S3 method for class 'fasp'
x[I, J, drop=TRUE,...]

Arguments

Details

A function array can be regarded as a matrix whose entries are functions. See fasp.object for an explanation of function arrays.

This routine extracts a sub-array according to the usual conventions for matrix indexing.

Value

A function array (of class "fasp"). Exceptionally, if the array has only one cell, and if drop=TRUE, then the result is a function value table (class "fv").

Author(s)

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

See Also

fasp.object

Examples

 online <- interactive()
 # Lansing woods data - multitype points with 6 types
 X <- lansing

 if(!online) {
   # subsample data (from 2251 to 450 points) to shorten check time
   X <- X[c(FALSE,FALSE,FALSE,FALSE,TRUE)]
 }

 a <- alltypes(X, 'K')

 # extract first three marks only
 b <- a[1:3,1:3]
 if(online) {plot(b)}
 # subset of array pertaining to hickories
 h <- a["hickory", ]
 if(online) {plot(h)}

Extract or Replace Subset of Function Values

Description

Extract or replace a subset of an object of class "fv".

Usage

  ## S3 method for class 'fv'
x[i, j, ..., drop=FALSE]

  ## S3 replacement method for class 'fv'
x[i, j] <- value

  ## S3 replacement method for class 'fv'
x$name <- value

Arguments

Details

These functions extract a designated subset of an object of class "fv", or replace the designated subset with other data, or delete the designated subset.

The subset is specified by the row index i and column index j, or by the column name name. Either i or j may be missing, or both may be missing.

The function [.fv is a method for the generic operator [ for the class "fv". It extracts the designated subset of x, and returns it as another object of class "fv" (if drop=FALSE) or as a data frame or vector (if drop=TRUE).

The function [<-.fv is a method for the generic operator [<- for the class "fv". If value is NULL, the designated subset of x will be deleted from x. Otherwise, the designated subset of x will be replaced by the data contained in value. The return value is the modified object x.

The function $<-.fv is a method for the generic operator $<- for the class "fv". If value is NULL, the designated column of x will be deleted from x. Otherwise, the designated column of x will be replaced by the data contained in value. The return value is the modified object x.

Value

The result of [.fv with drop=TRUE is a data frame or vector.

Otherwise, the result is another object of class "fv".

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

See Also

fv.object

Examples

 K <- Kest(cells)

 # discard the estimates of K(r) for r  > 0.1
 Ksub <- K[K$r <= 0.1, ]

 # extract the border method estimates
 bor <- K[ , "border", drop=TRUE]
 # or equivalently
 bor <- K$border

 # remove the border-method estimates
 K$border <- NULL
 K

Empty Space Function of a Three-Dimensional Point Pattern

Description

Estimates the empty space function F_3(r) from a three-dimensional point pattern.

Usage

F3est(X, ..., rmax = NULL, nrval = 128, vside = NULL,
              correction = c("rs", "km", "cs"),
              sphere = c("fudge", "ideal", "digital"))

Arguments

Details

For a stationary point process \Phi in three-dimensional space, the empty space function is

F_3(r) = P(d(0,\Phi) \le r)

where d(0,\Phi) denotes the distance from a fixed origin 0 to the nearest point of \Phi.

The three-dimensional point pattern X is assumed to be a partial realisation of a stationary point process \Phi. The empty space function of \Phi can then be estimated using techniques described in the References.

The box containing the point pattern is discretised into cubic voxels of side length vside. The distance function d(u,\Phi) is computed for every voxel centre point u using a three-dimensional version of the distance transform algorithm (Borgefors, 1986). The empirical cumulative distribution function of these values, with appropriate edge corrections, is the estimate of F_3(r).

The available edge corrections are:

"rs":

the reduced sample (aka minus sampling, border correction) estimator (Baddeley et al, 1993)

"km":

the three-dimensional version of the Kaplan-Meier estimator (Baddeley and Gill, 1997)

"cs":

the three-dimensional generalisation of the Chiu-Stoyan or Hanisch estimator (Chiu and Stoyan, 1998).

Alternatively correction="all" selects all options.

The result includes a column theo giving the theoretical value of F_3(r) for a uniform Poisson process (Complete Spatial Randomness). This value depends on the volume of the sphere of radius r measured in the discretised distance metric. The argument sphere determines how this will be calculated.

• If sphere="ideal" the calculation will use the volume of an ideal sphere of radius r namely (4/3) \pi r^3. This is not recommended because the theoretical values of F_3(r) are inaccurate.

• If sphere="fudge" then the volume of the ideal sphere will be multiplied by 0.78, which gives the approximate volume of the sphere in the discretised distance metric.

• If sphere="digital" then the volume of the sphere in the discretised distance metric is computed exactly using another distance transform. This takes longer to compute, but is exact.

Value

A function value table (object of class "fv") that can be plotted, printed or coerced to a data frame containing the function values.

Warnings

A small value of vside and a large value of nrval are required for reasonable accuracy.

The default value of vside ensures that the total number of voxels is 2^22 or about 4 million. To change the default number of voxels, see spatstat.options("nvoxel").

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rana Moyeed.

References

Baddeley, A.J, Moyeed, R.A., Howard, C.V. and Boyde, A. Analysis of a three-dimensional point pattern with replication. Applied Statistics 42 (1993) 641–668.

Baddeley, A.J. and Gill, R.D. (1997) Kaplan-Meier estimators of interpoint distance distributions for spatial point processes. Annals of Statistics 25, 263–292.

Borgefors, G. (1986) Distance transformations in digital images. Computer Vision, Graphics and Image Processing 34, 344–371.

Chiu, S.N. and Stoyan, D. (1998) Estimators of distance distributions for spatial patterns. Statistica Neerlandica 52, 239–246.

See Also

pp3 to create a three-dimensional point pattern (object of class "pp3").

G3est, K3est, pcf3est for other summary functions of a three-dimensional point pattern.

Fest to estimate the empty space function of point patterns in two dimensions.

Examples

  
  X <- rpoispp3(42)
  Z <- F3est(X)
  if(interactive()) plot(Z)
  

Estimate the Empty Space Function or its Hazard Rate

Description

Estimates the empty space function F(r) or its hazard rate h(r) from a point pattern in a window of arbitrary shape.

Usage

Fest(X, ..., eps, r=NULL, breaks=NULL,
     correction=c("rs", "km", "cs"),
     domain=NULL)

Fhazard(X, ...) 

Arguments

Details

Fest computes an estimate of the empty space function F(r), and Fhazard computes an estimate of its hazard rate h(r).

The empty space function (also called the “spherical contact distribution” or the “point-to-nearest-event” distribution) of a stationary point process X is the cumulative distribution function F of the distance from a fixed point in space to the nearest point of X.

An estimate of F derived from a spatial point pattern dataset can be used in exploratory data analysis and formal inference about the pattern (Cressie, 1991; Diggle, 1983; Ripley, 1988). In exploratory analyses, the estimate of F is a useful statistic summarising the sizes of gaps in the pattern. For inferential purposes, the estimate of F is usually compared to the true value of F for a completely random (Poisson) point process, which is

F(r) = 1 - e^{ - \lambda \pi r^2}

where \lambda is the intensity (expected number of points per unit area). Deviations between the empirical and theoretical F curves may suggest spatial clustering or spatial regularity.

This algorithm estimates the empty space function F from the point pattern X. It assumes that X can be treated as a realisation of a stationary (spatially homogeneous) random spatial point process in the plane, observed through a bounded window. The window (which is specified in X) may have arbitrary shape.

The argument X is interpreted as a point pattern object (of class "ppp", see ppp.object) and can be supplied in any of the formats recognised by as.ppp.

The algorithm uses two discrete approximations which are controlled by the parameter eps and by the spacing of values of r respectively. (See below for details.) First-time users are strongly advised not to specify these arguments.

The estimation of F is hampered by edge effects arising from the unobservability of points of the random pattern outside the window. An edge correction is needed to reduce bias (Baddeley, 1998; Ripley, 1988). The edge corrections implemented here are the border method or "reduced sample" estimator, the spatial Kaplan-Meier estimator (Baddeley and Gill, 1997) and the Chiu-Stoyan estimator (Chiu and Stoyan, 1998).

Our implementation makes essential use of the distance transform algorithm of image processing (Borgefors, 1986). A fine grid of pixels is created in the observation window. The Euclidean distance between two pixels is approximated by the length of the shortest path joining them in the grid, where a path is a sequence of steps between adjacent pixels, and horizontal, vertical and diagonal steps have length 1, 1 and \sqrt 2 respectively in pixel units. If the pixel grid is sufficiently fine then this is an accurate approximation.

The parameter eps is the pixel width of the rectangular raster used to compute the distance transform (see below). It must not be too large: the absolute error in distance values due to discretisation is bounded by eps.

If eps is not specified, the function checks whether the window Window(X) contains pixel raster information. If so, then eps is set equal to the pixel width of the raster; otherwise, eps defaults to 1/100 of the width of the observation window.

The argument r is the vector of values for the distance r at which F(r) should be evaluated. It is also used to determine the breakpoints (in the sense of hist) for the computation of histograms of distances. The estimators are computed from histogram counts. This introduces a discretisation error which is controlled by the fineness of the breakpoints.

First-time users would be strongly advised not to specify r. However, if it is specified, r must satisfy r[1] = 0, and max(r) must be larger than the radius of the largest disc contained in the window. Furthermore, the spacing of successive r values must be very fine (ideally not greater than eps/4).

The algorithm also returns an estimate of the hazard rate function, h(r) of F(r). The hazard rate is defined by

h(r) = - \frac{d}{dr} \log(1 - F(r))

The hazard rate of F has been proposed as a useful exploratory statistic (Baddeley and Gill, 1994). The estimate of h(r) given here is a discrete approximation to the hazard rate of the Kaplan-Meier estimator of F. Note that F is absolutely continuous (for any stationary point process X), so the hazard function always exists (Baddeley and Gill, 1997).

If the argument domain is given, the estimate of F(r) will be based only on the empty space distances measured from locations inside domain (although their nearest data points may lie outside domain). This is useful in bootstrap techniques. The argument domain should be a window (object of class "owin") or something acceptable to as.owin. It must be a subset of the window of the point pattern X.

The naive empirical distribution of distances from each location in the window to the nearest point of the data pattern, is a biased estimate of F. However this is also returned by the algorithm (if correction="none"), as it is sometimes useful in other contexts. Care should be taken not to use the uncorrected empirical F as if it were an unbiased estimator of F.

Value

An object of class "fv", see fv.object, which can be plotted directly using plot.fv.

The result of Fest is essentially a data frame containing up to seven columns:

The result of Fhazard contains only three columns

Warnings

The reduced sample (border method) estimator of F is pointwise approximately unbiased, but need not be a valid distribution function; it may not be a nondecreasing function of r. Its range is always within [0,1].

The spatial Kaplan-Meier estimator of F is always nondecreasing but its maximum value may be less than 1.

The estimate of hazard rate h(r) returned by the algorithm is an approximately unbiased estimate for the integral of h() over the corresponding histogram cell. It may exhibit oscillations due to discretisation effects. We recommend modest smoothing, such as kernel smoothing with kernel width equal to the width of a histogram cell, using Smooth.fv.

Note

Sizeable amounts of memory may be needed during the calculation.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

References

Baddeley, A.J. Spatial sampling and censoring. In O.E. Barndorff-Nielsen, W.S. Kendall and M.N.M. van Lieshout (eds) Stochastic Geometry: Likelihood and Computation. Chapman and Hall, 1998. Chapter 2, pages 37-78.

Baddeley, A.J. and Gill, R.D. The empty space hazard of a spatial pattern. Research Report 1994/3, Department of Mathematics, University of Western Australia, May 1994.

Baddeley, A.J. and Gill, R.D. Kaplan-Meier estimators of interpoint distance distributions for spatial point processes. Annals of Statistics 25 (1997) 263-292.

Borgefors, G. Distance transformations in digital images. Computer Vision, Graphics and Image Processing 34 (1986) 344-371.

Chiu, S.N. and Stoyan, D. (1998) Estimators of distance distributions for spatial patterns. Statistica Neerlandica 52, 239–246.

Cressie, N.A.C. Statistics for spatial data. John Wiley and Sons, 1991.

Diggle, P.J. Statistical analysis of spatial point patterns. Academic Press, 1983.

Ripley, B.D. Statistical inference for spatial processes. Cambridge University Press, 1988.

Stoyan, D, Kendall, W.S. and Mecke, J. Stochastic geometry and its applications. 2nd edition. Springer Verlag, 1995.

See Also

Gest, Jest, Kest, km.rs, reduced.sample, kaplan.meier

Examples

   Fc <- Fest(cells, 0.01)

   # Tip: don't use F for the left hand side!
   # That's an abbreviation for FALSE

   plot(Fc)

   # P-P style plot
   plot(Fc, cbind(km, theo) ~ theo)

   # The empirical F is above the Poisson F
   # indicating an inhibited pattern

   if(interactive()) {
   plot(Fc, . ~ theo)
   plot(Fc, asin(sqrt(.)) ~ asin(sqrt(theo)))
   }
   

Inhomogeneous Empty Space Function

Description

Estimates the inhomogeneous empty space function of a non-stationary point pattern.

Usage

  Finhom(X, lambda = NULL, lmin = NULL, ...,
        sigma = NULL, varcov = NULL,
        r = NULL, breaks = NULL, ratio = FALSE,
        update = TRUE, warn.bias=TRUE, savelambda=FALSE)

Arguments

Details

This command computes estimates of the inhomogeneous F-function (van Lieshout, 2010) of a point pattern. It is the counterpart, for inhomogeneous spatial point patterns, of the empty space function F for homogeneous point patterns computed by Fest.

The argument X should be a point pattern (object of class "ppp").

The inhomogeneous F function is computed using the border correction, equation (6) in Van Lieshout (2010).

The argument lambda should supply the (estimated) values of the intensity function \lambda of the point process. It may be either

a numeric vector

containing the values of the intensity function at the points of the pattern X.

a pixel image

(object of class "im") assumed to contain the values of the intensity function at all locations in the window.

a fitted point process model

(object of class "ppm" or "kppm") whose fitted trend can be used as the fitted intensity. (If update=TRUE the model will first be refitted to the data X before the trend is computed.)

a function

which can be evaluated to give values of the intensity at any locations.

omitted:

if lambda is omitted, then it will be estimated using a ‘leave-one-out’ kernel smoother.

If lambda is a numeric vector, then its length should be equal to the number of points in the pattern X. The value lambda[i] is assumed to be the the (estimated) value of the intensity \lambda(x_i) for the point x_i of the pattern X. Each value must be a positive number; NA's are not allowed.

If lambda is a pixel image, the domain of the image should cover the entire window of the point pattern. If it does not (which may occur near the boundary because of discretisation error), then the missing pixel values will be obtained by applying a Gaussian blur to lambda using blur, then looking up the values of this blurred image for the missing locations. (A warning will be issued in this case.)

If lambda is a function, then it will be evaluated in the form lambda(x,y) where x and y are vectors of coordinates of the points of X. It should return a numeric vector with length equal to the number of points in X.

If lambda is omitted, then it will be estimated using a ‘leave-one-out’ kernel smoother. The estimate lambda[i] for the point X[i] is computed by removing X[i] from the point pattern, applying kernel smoothing to the remaining points using density.ppp, and evaluating the smoothed intensity at the point X[i]. The smoothing kernel bandwidth is controlled by the arguments sigma and varcov, which are passed to density.ppp along with any extra arguments.

Value

An object of class "fv", see fv.object, which can be plotted directly using plot.fv.

Author(s)

Original code by Marie-Colette van Lieshout. C implementation and R adaptation by Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Ege Rubak rubak@math.aau.dk.

References

Van Lieshout, M.N.M. and Baddeley, A.J. (1996) A nonparametric measure of spatial interaction in point patterns. Statistica Neerlandica 50, 344–361.

Van Lieshout, M.N.M. (2010) A J-function for inhomogeneous point processes. Statistica Neerlandica 65, 183–201.

See Also

Ginhom, Jinhom, Fest

Examples

  online <- interactive()
  if(online) {
    plot(Finhom(swedishpines, sigma=10))
    plot(Finhom(swedishpines, sigma=bw.diggle, adjust=2))
  } else {
    ## use a coarse grid for faster computation and package testing
    plot(Finhom(swedishpines, sigma=10, dimyx=32))
  }

Inhomogeneous Marked F-Function

Description

For a marked point pattern, estimate the inhomogeneous version of the multitype F function, effectively the cumulative distribution function of the distance from a fixed point to the nearest point in subset J, adjusted for spatially varying intensity.

Usage

  Fmulti.inhom(X, J,
              lambda = NULL, lambdaJ = NULL, lambdamin = NULL,
              ...,
              r = NULL)

  FmultiInhom(X, J,
              lambda = NULL, lambdaJ = NULL, lambdamin = NULL,
              ...,
              r = NULL)

Arguments

Details

See Cronie and Van Lieshout (2015).

The functions FmultiInhom and Fmulti.inhom are identical.

Value

Object of class "fv" containing the estimate of the inhomogeneous multitype F function.

Author(s)

Ottmar Cronie and Marie-Colette van Lieshout. Rewritten for spatstat by Adrian Baddeley Adrian.Baddeley@curtin.edu.au.

References

Cronie, O. and Van Lieshout, M.N.M. (2015) Summary statistics for inhomogeneous marked point processes. Annals of the Institute of Statistical Mathematics DOI: 10.1007/s10463-015-0515-z

See Also

Finhom

Examples

  X <- amacrine
  J <- (marks(X) == "off")
  online <- interactive()
  eps <- if(online) NULL else 0.025
  if(online && require(spatstat.model)) {
    mod <- ppm(X ~ marks * x, eps=eps)
    lambdaX <- fitted(mod, dataonly=TRUE)
    lambdaOff <- predict(mod, eps=eps)[["off"]]
    lmin <- min(lambdaOff) * 0.9
  } else {
    ## faster computation for package checker only
    lambdaX <- intensity(X)[as.integer(marks(X))]
    lmin <- intensity(X)[2] * 0.9
  }

  plot(FmultiInhom(X, J, lambda=lambdaX, lambdamin=lmin, eps=eps))

Nearest Neighbour Distance Distribution Function of a Three-Dimensional Point Pattern

Description

Estimates the nearest-neighbour distance distribution function G_3(r) from a three-dimensional point pattern.

Usage

G3est(X, ..., rmax = NULL, nrval = 128, correction = c("rs", "km", "Hanisch"))

Arguments

Details

For a stationary point process \Phi in three-dimensional space, the nearest-neighbour function is

G_3(r) = P(d^\ast(x,\Phi) \le r \mid x \in \Phi)

the cumulative distribution function of the distance d^\ast(x,\Phi) from a typical point x in \Phi to its nearest neighbour, i.e. to the nearest other point of \Phi.

The three-dimensional point pattern X is assumed to be a partial realisation of a stationary point process \Phi. The nearest neighbour function of \Phi can then be estimated using techniques described in the References. For each data point, the distance to the nearest neighbour is computed. The empirical cumulative distribution function of these values, with appropriate edge corrections, is the estimate of G_3(r).

The available edge corrections are:

"rs":

the reduced sample (aka minus sampling, border correction) estimator (Baddeley et al, 1993)

"km":

the three-dimensional version of the Kaplan-Meier estimator (Baddeley and Gill, 1997)

"Hanisch":

the three-dimensional generalisation of the Hanisch estimator (Hanisch, 1984).

Alternatively correction="all" selects all options.

Value

A function value table (object of class "fv") that can be plotted, printed or coerced to a data frame containing the function values.

Warnings

A large value of nrval is required in order to avoid discretisation effects (due to the use of histograms in the calculation).

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rana Moyeed.

References

Baddeley, A.J, Moyeed, R.A., Howard, C.V. and Boyde, A. (1993) Analysis of a three-dimensional point pattern with replication. Applied Statistics 42, 641–668.

Baddeley, A.J. and Gill, R.D. (1997) Kaplan-Meier estimators of interpoint distance distributions for spatial point processes. Annals of Statistics 25, 263–292.

Hanisch, K.-H. (1984) Some remarks on estimators of the distribution function of nearest neighbour distance in stationary spatial point patterns. Mathematische Operationsforschung und Statistik, series Statistics 15, 409–412.

See Also

pp3 to create a three-dimensional point pattern (object of class "pp3").

F3est, K3est, pcf3est for other summary functions of a three-dimensional point pattern.

Gest to estimate the empty space function of point patterns in two dimensions.

Examples

  X <- rpoispp3(42)
  Z <- G3est(X)
  if(interactive()) plot(Z)

Multitype Nearest Neighbour Distance Function (i-to-j)

Description

For a multitype point pattern, estimate the distribution of the distance from a point of type i to the nearest point of type j.

Usage

Gcross(X, i, j, r=NULL, breaks=NULL, ..., correction=c("rs", "km", "han"))

Arguments

Details

This function Gcross and its companions Gdot and Gmulti are generalisations of the function Gest to multitype point patterns.

A multitype point pattern is a spatial pattern of points classified into a finite number of possible “colours” or “types”. In the spatstat package, a multitype pattern is represented as a single point pattern object in which the points carry marks, and the mark value attached to each point determines the type of that point.

The argument X must be a point pattern (object of class "ppp") or any data that are acceptable to as.ppp. It must be a marked point pattern, and the mark vector X$marks must be a factor. The arguments i and j will be interpreted as levels of the factor X$marks. (Warning: this means that an integer value i=3 will be interpreted as the number 3, not the 3rd smallest level).

The “cross-type” (type i to type j) nearest neighbour distance distribution function of a multitype point process is the cumulative distribution function G_{ij}(r) of the distance from a typical random point of the process with type i the nearest point of type j.

An estimate of G_{ij}(r) is a useful summary statistic in exploratory data analysis of a multitype point pattern. If the process of type i points were independent of the process of type j points, then G_{ij}(r) would equal F_j(r), the empty space function of the type j points. For a multitype Poisson point process where the type i points have intensity \lambda_i, we have

G_{ij}(r) = 1 - e^{ - \lambda_j \pi r^2}

Deviations between the empirical and theoretical G_{ij} curves may suggest dependence between the points of types i and j.

This algorithm estimates the distribution function G_{ij}(r) from the point pattern X. It assumes that X can be treated as a realisation of a stationary (spatially homogeneous) random spatial point process in the plane, observed through a bounded window. The window (which is specified in X as Window(X)) may have arbitrary shape. Biases due to edge effects are treated in the same manner as in Gest.

The argument r is the vector of values for the distance r at which G_{ij}(r) should be evaluated. It is also used to determine the breakpoints (in the sense of hist) for the computation of histograms of distances. The reduced-sample and Kaplan-Meier estimators are computed from histogram counts. In the case of the Kaplan-Meier estimator this introduces a discretisation error which is controlled by the fineness of the breakpoints.

First-time users would be strongly advised not to specify r. However, if it is specified, r must satisfy r[1] = 0, and max(r) must be larger than the radius of the largest disc contained in the window. Furthermore, the successive entries of r must be finely spaced.

The algorithm also returns an estimate of the hazard rate function, \lambda(r), of G_{ij}(r). This estimate should be used with caution as G_{ij}(r) is not necessarily differentiable.

The naive empirical distribution of distances from each point of the pattern X to the nearest other point of the pattern, is a biased estimate of G_{ij}. However this is also returned by the algorithm, as it is sometimes useful in other contexts. Care should be taken not to use the uncorrected empirical G_{ij} as if it were an unbiased estimator of G_{ij}.

Value

An object of class "fv" (see fv.object).

Essentially a data frame containing six numeric columns

Warnings

The arguments i and j are always interpreted as levels of the factor X$marks. They are converted to character strings if they are not already character strings. The value i=1 does not refer to the first level of the factor.

The function G_{ij} does not necessarily have a density.

The reduced sample estimator of G_{ij} is pointwise approximately unbiased, but need not be a valid distribution function; it may not be a nondecreasing function of r. Its range is always within [0,1].

The spatial Kaplan-Meier estimator of G_{ij} is always nondecreasing but its maximum value may be less than 1.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net.

References

Cressie, N.A.C. Statistics for spatial data. John Wiley and Sons, 1991.

Diggle, P.J. Statistical analysis of spatial point patterns. Academic Press, 1983.

Diggle, P. J. (1986). Displaced amacrine cells in the retina of a rabbit : analysis of a bivariate spatial point pattern. J. Neurosci. Meth. 18, 115–125.

Harkness, R.D and Isham, V. (1983) A bivariate spatial point pattern of ants' nests. Applied Statistics 32, 293–303

Lotwick, H. W. and Silverman, B. W. (1982). Methods for analysing spatial processes of several types of points. J. Royal Statist. Soc. Ser. B 44, 406–413.

Ripley, B.D. Statistical inference for spatial processes. Cambridge University Press, 1988.

Stoyan, D, Kendall, W.S. and Mecke, J. Stochastic geometry and its applications. 2nd edition. Springer Verlag, 1995.

Van Lieshout, M.N.M. and Baddeley, A.J. (1999) Indices of dependence between types in multivariate point patterns. Scandinavian Journal of Statistics 26, 511–532.

See Also

Gdot, Gest, Gmulti

Examples

    # amacrine cells data
    G01 <- Gcross(amacrine)

    # equivalent to:
    
      G01 <- Gcross(amacrine, "off", "on")
    

    plot(G01)

    # empty space function of `on' points
    if(interactive()) {
       F1 <- Fest(split(amacrine)$on, r = G01$r)
       lines(F1$r, F1$km, lty=3)
    }

    # synthetic example    
    pp <- runifpoispp(30)
    pp <- pp %mark% factor(sample(0:1, npoints(pp), replace=TRUE))
    G <- Gcross(pp, "0", "1")   # note: "0" not 0

Inhomogeneous Multitype G Cross Function

Description

For a multitype point pattern, estimate the inhomogeneous version of the cross G function, which is the distribution of the distance from a point of type i to the nearest point of type j, adjusted for spatially varying intensity.

Usage

   Gcross.inhom(X, i, j,
              lambda = NULL, lambdaI = NULL, lambdaJ = NULL,
              lambdamin = NULL,
              ...,
              r = NULL,
              ReferenceMeasureMarkSetI = NULL,
              ratio = FALSE)

Arguments

Details

This is a generalisation of the function Gcross to include an adjustment for spatially inhomogeneous intensity, in a manner similar to the function Ginhom.

The argument lambdaI supplies the values of the intensity of the sub-process of points of type i. It may be either

a pixel image

(object of class "im") which gives the values of the type i intensity at all locations in the window containing X;

a numeric vector

containing the values of the type i intensity evaluated only at the data points of type i. The length of this vector must equal the number of type i points in X.

a function

of the form function(x,y) which can be evaluated to give values of the intensity at any locations.

a fitted point process model

(object of class "ppm", "kppm" or "dppm") whose fitted trend can be used as the fitted intensity. (If update=TRUE the model will first be refitted to the data X before the trend is computed.)

omitted:

if lambdaI is omitted then it will be estimated using a leave-one-out kernel smoother.

If lambdaI is omitted, then it will be estimated using a ‘leave-one-out’ kernel smoother.

Similarly the argument lambdaJ should contain estimated values of the intensity of the points of type j. It may be either a pixel image, a numeric vector of length equal to the number of points in X, a function, or omitted.

The argument r is the vector of values for the distance r at which G_{ij}(r) should be evaluated. The values of r must be increasing nonnegative numbers and the maximum r value must not exceed the radius of the largest disc contained in the window.

Value

An object of class "fv" (see fv.object) containing estimates of the inhomogeneous cross type G function.

Warnings

The argument i is interpreted as a level of the factor X$marks. It is converted to a character string if it is not already a character string. The value i=1 does not refer to the first level of the factor.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au.

References

Cronie, O. and Van Lieshout, M.N.M. (2015) Summary statistics for inhomogeneous marked point processes. Annals of the Institute of Statistical Mathematics DOI: 10.1007/s10463-015-0515-z

See Also

Gcross, Ginhom, Gcross.inhom, Gmulti.inhom.

Examples

  X <- rescale(amacrine)
  if(interactive() && require(spatstat.model)) {
    ## how to do it normally
    mod <- ppm(X ~ marks * x)
    lam <- fitted(mod, dataonly=TRUE)
    lmin <- min(predict(mod)[["off"]]) * 0.9
  } else {
    ## for package testing 
    lam <- intensity(X)[as.integer(marks(X))]
    lmin <- intensity(X)[2] * 0.9
  }
  GC <- Gcross.inhom(X, "on", "off", lambda=lam, lambdamin=lmin)

Multitype Nearest Neighbour Distance Function (i-to-any)

Description

For a multitype point pattern, estimate the distribution of the distance from a point of type i to the nearest other point of any type.

Usage

Gdot(X, i, r=NULL, breaks=NULL, ..., correction=c("km", "rs", "han"))

Arguments

Details

This function Gdot and its companions Gcross and Gmulti are generalisations of the function Gest to multitype point patterns.

A multitype point pattern is a spatial pattern of points classified into a finite number of possible “colours” or “types”. In the spatstat package, a multitype pattern is represented as a single point pattern object in which the points carry marks, and the mark value attached to each point determines the type of that point.

The argument X must be a point pattern (object of class "ppp") or any data that are acceptable to as.ppp. It must be a marked point pattern, and the mark vector X$marks must be a factor. The argument will be interpreted as a level of the factor X$marks. (Warning: this means that an integer value i=3 will be interpreted as the number 3, not the 3rd smallest level.)

The “dot-type” (type i to any type) nearest neighbour distance distribution function of a multitype point process is the cumulative distribution function G_{i\bullet}(r) of the distance from a typical random point of the process with type i the nearest other point of the process, regardless of type.

An estimate of G_{i\bullet}(r) is a useful summary statistic in exploratory data analysis of a multitype point pattern. If the type i points were independent of all other points, then G_{i\bullet}(r) would equal G_{ii}(r), the nearest neighbour distance distribution function of the type i points alone. For a multitype Poisson point process with total intensity \lambda, we have

G_{i\bullet}(r) = 1 - e^{ - \lambda \pi r^2}

Deviations between the empirical and theoretical G_{i\bullet} curves may suggest dependence of the type i points on the other points.

This algorithm estimates the distribution function G_{i\bullet}(r) from the point pattern X. It assumes that X can be treated as a realisation of a stationary (spatially homogeneous) random spatial point process in the plane, observed through a bounded window. The window (which is specified in X as Window(X)) may have arbitrary shape. Biases due to edge effects are treated in the same manner as in Gest.

The argument r is the vector of values for the distance r at which G_{i\bullet}(r) should be evaluated. It is also used to determine the breakpoints (in the sense of hist) for the computation of histograms of distances. The reduced-sample and Kaplan-Meier estimators are computed from histogram counts. In the case of the Kaplan-Meier estimator this introduces a discretisation error which is controlled by the fineness of the breakpoints.

First-time users would be strongly advised not to specify r. However, if it is specified, r must satisfy r[1] = 0, and max(r) must be larger than the radius of the largest disc contained in the window. Furthermore, the successive entries of r must be finely spaced.

The algorithm also returns an estimate of the hazard rate function, \lambda(r), of G_{i\bullet}(r). This estimate should be used with caution as G_{i\bullet}(r) is not necessarily differentiable.

The naive empirical distribution of distances from each point of the pattern X to the nearest other point of the pattern, is a biased estimate of G_{i\bullet}. However this is also returned by the algorithm, as it is sometimes useful in other contexts. Care should be taken not to use the uncorrected empirical G_{i\bullet} as if it were an unbiased estimator of G_{i\bullet}.

Value

An object of class "fv" (see fv.object).

Essentially a data frame containing six numeric columns

Warnings

The argument i is interpreted as a level of the factor X$marks. It is converted to a character string if it is not already a character string. The value i=1 does not refer to the first level of the factor.

The function G_{i\bullet} does not necessarily have a density.

The reduced sample estimator of G_{i\bullet} is pointwise approximately unbiased, but need not be a valid distribution function; it may not be a nondecreasing function of r. Its range is always within [0,1].

The spatial Kaplan-Meier estimator of G_{i\bullet} is always nondecreasing but its maximum value may be less than 1.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

References

Cressie, N.A.C. Statistics for spatial data. John Wiley and Sons, 1991.

Diggle, P.J. Statistical analysis of spatial point patterns. Academic Press, 1983.

Diggle, P. J. (1986). Displaced amacrine cells in the retina of a rabbit : analysis of a bivariate spatial point pattern. J. Neurosci. Meth. 18, 115–125.

Harkness, R.D and Isham, V. (1983) A bivariate spatial point pattern of ants' nests. Applied Statistics 32, 293–303

Lotwick, H. W. and Silverman, B. W. (1982). Methods for analysing spatial processes of several types of points. J. Royal Statist. Soc. Ser. B 44, 406–413.

Ripley, B.D. Statistical inference for spatial processes. Cambridge University Press, 1988.

Stoyan, D, Kendall, W.S. and Mecke, J. Stochastic geometry and its applications. 2nd edition. Springer Verlag, 1995.

Van Lieshout, M.N.M. and Baddeley, A.J. (1999) Indices of dependence between types in multivariate point patterns. Scandinavian Journal of Statistics 26, 511–532.

See Also

Gcross, Gest, Gmulti

Examples

    # amacrine cells data
    G0. <- Gdot(amacrine, "off") 
    plot(G0.)

    # synthetic example    
    pp <- runifpoispp(30)
    pp <- pp %mark% factor(sample(0:1, npoints(pp), replace=TRUE))
    G <- Gdot(pp, "0")
    G <- Gdot(pp, 0) # equivalent

Inhomogeneous Multitype G Dot Function

Description

For a multitype point pattern, estimate the inhomogeneous version of the dot G function, which is the distribution of the distance from a point of type i to the nearest other point of any type, adjusted for spatially varying intensity.

Usage

   Gdot.inhom(X, i,
              lambdaI = NULL, lambdadot = NULL, lambdamin = NULL,
              ...,
              r = NULL, ReferenceMeasureMarkSetI = NULL, ratio = FALSE)

Arguments

Details

This is a generalisation of the function Gdot to include an adjustment for spatially inhomogeneous intensity, in a manner similar to the function Ginhom.

The argument lambdaI supplies the values of the intensity of the sub-process of points of type i. It may be either

a pixel image

(object of class "im") which gives the values of the type i intensity at all locations in the window containing X;

a numeric vector

containing the values of the type i intensity evaluated only at the data points of type i. The length of this vector must equal the number of type i points in X.

a function

of the form function(x,y) which can be evaluated to give values of the intensity at any locations.

a fitted point process model

(object of class "ppm", "kppm" or "dppm") whose fitted trend can be used as the fitted intensity. (If update=TRUE the model will first be refitted to the data X before the trend is computed.)

omitted:

if lambdaI is omitted then it will be estimated using a leave-one-out kernel smoother.

If lambdaI is omitted, then it will be estimated using a ‘leave-one-out’ kernel smoother.

Similarly the argument lambdadot should contain estimated values of the intensity of the entire point process. It may be either a pixel image, a numeric vector of length equal to the number of points in X, a function, or omitted.

The argument r is the vector of values for the distance r at which G_{i\bullet}(r) should be evaluated. The values of r must be increasing nonnegative numbers and the maximum r value must not exceed the radius of the largest disc contained in the window.

Value

An object of class "fv" (see fv.object) containing estimates of the inhomogeneous dot type G function.

Warnings

The argument i is interpreted as a level of the factor X$marks. It is converted to a character string if it is not already a character string. The value i=1 does not refer to the first level of the factor.

Author(s)

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

References

Cronie, O. and Van Lieshout, M.N.M. (2015) Summary statistics for inhomogeneous marked point processes. Annals of the Institute of Statistical Mathematics DOI: 10.1007/s10463-015-0515-z

See Also

Gdot, Ginhom, Gcross.inhom, Gmulti.inhom.

Examples

  X <- rescale(amacrine)
  if(interactive() && require(spatstat.model)) {
    ## how to do it normally
    mod <- ppm(X ~ marks * x)
    lam <- fitted(mod, dataonly=TRUE)
    lmin <- min(predict(mod)[["off"]]) * 0.9
  } else {
    ## for package testing 
    lam <- intensity(X)[as.integer(marks(X))]
    lmin <- intensity(X)[2] * 0.9
  }
  lamI <- lam[marks(X) == "on"]
  GD <- Gdot.inhom(X, "on", lambdaI=lamI, lambdadot=lam, lambdamin=lmin)

Nearest Neighbour Distance Function G

Description

Estimates the nearest neighbour distance distribution function G(r) from a point pattern in a window of arbitrary shape.

Usage

Gest(X, r=NULL, breaks=NULL, ...,
     correction=c("rs", "km", "han"),
     domain=NULL)

Arguments

Details

The nearest neighbour distance distribution function (also called the “event-to-event” or “inter-event” distribution) of a point process X is the cumulative distribution function G of the distance from a typical random point of X to the nearest other point of X.

An estimate of G derived from a spatial point pattern dataset can be used in exploratory data analysis and formal inference about the pattern (Cressie, 1991; Diggle, 1983; Ripley, 1988). In exploratory analyses, the estimate of G is a useful statistic summarising one aspect of the “clustering” of points. For inferential purposes, the estimate of G is usually compared to the true value of G for a completely random (Poisson) point process, which is

G(r) = 1 - e^{ - \lambda \pi r^2}

where \lambda is the intensity (expected number of points per unit area). Deviations between the empirical and theoretical G curves may suggest spatial clustering or spatial regularity.

This algorithm estimates the nearest neighbour distance distribution function G from the point pattern X. It assumes that X can be treated as a realisation of a stationary (spatially homogeneous) random spatial point process in the plane, observed through a bounded window. The window (which is specified in X as Window(X)) may have arbitrary shape.

The argument X is interpreted as a point pattern object (of class "ppp", see ppp.object) and can be supplied in any of the formats recognised by as.ppp().

The estimation of G is hampered by edge effects arising from the unobservability of points of the random pattern outside the window. An edge correction is needed to reduce bias (Baddeley, 1998; Ripley, 1988). The edge corrections implemented here are the border method or “reduced sample” estimator, the spatial Kaplan-Meier estimator (Baddeley and Gill, 1997) and the Hanisch estimator (Hanisch, 1984).

The argument r is the vector of values for the distance r at which G(r) should be evaluated. It is also used to determine the breakpoints (in the sense of hist) for the computation of histograms of distances. The estimators are computed from histogram counts. This introduces a discretisation error which is controlled by the fineness of the breakpoints.

First-time users would be strongly advised not to specify r. However, if it is specified, r must satisfy r[1] = 0, and max(r) must be larger than the radius of the largest disc contained in the window. Furthermore, the successive entries of r must be finely spaced.

The algorithm also returns an estimate of the hazard rate function, \lambda(r), of G(r). The hazard rate is defined as the derivative

\lambda(r) = - \frac{d}{dr} \log (1 - G(r))

This estimate should be used with caution as G is not necessarily differentiable.

If the argument domain is given, the estimate of G(r) will be based only on the nearest neighbour distances measured from points falling inside domain (although their nearest neighbours may lie outside domain). This is useful in bootstrap techniques. The argument domain should be a window (object of class "owin") or something acceptable to as.owin. It must be a subset of the window of the point pattern X.

The naive empirical distribution of distances from each point of the pattern X to the nearest other point of the pattern, is a biased estimate of G. However it is sometimes useful. It can be returned by the algorithm, by selecting correction="none". Care should be taken not to use the uncorrected empirical G as if it were an unbiased estimator of G.

To simply compute the nearest neighbour distance for each point in the pattern, use nndist. To determine which point is the nearest neighbour of a given point, use nnwhich.

Value

An object of class "fv", see fv.object, which can be plotted directly using plot.fv.

Essentially a data frame containing some or all of the following columns:

Warnings

The function G does not necessarily have a density. Any valid c.d.f. may appear as the nearest neighbour distance distribution function of a stationary point process.

The reduced sample estimator of G is pointwise approximately unbiased, but need not be a valid distribution function; it may not be a nondecreasing function of r. Its range is always within [0,1].

The spatial Kaplan-Meier estimator of G is always nondecreasing but its maximum value may be less than 1.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

References

Baddeley, A.J. Spatial sampling and censoring. In O.E. Barndorff-Nielsen, W.S. Kendall and M.N.M. van Lieshout (eds) Stochastic Geometry: Likelihood and Computation. Chapman and Hall, 1998. Chapter 2, pages 37-78.

Baddeley, A.J. and Gill, R.D. Kaplan-Meier estimators of interpoint distance distributions for spatial point processes. Annals of Statistics 25 (1997) 263-292.

Cressie, N.A.C. Statistics for spatial data. John Wiley and Sons, 1991.

Diggle, P.J. Statistical analysis of spatial point patterns. Academic Press, 1983.

Hanisch, K.-H. (1984) Some remarks on estimators of the distribution function of nearest-neighbour distance in stationary spatial point patterns. Mathematische Operationsforschung und Statistik, series Statistics 15, 409–412.

Ripley, B.D. Statistical inference for spatial processes. Cambridge University Press, 1988.

Stoyan, D, Kendall, W.S. and Mecke, J. Stochastic geometry and its applications. 2nd edition. Springer Verlag, 1995.

See Also

nndist, nnwhich, Fest, Jest, Kest, km.rs, reduced.sample, kaplan.meier

Examples

  G <- Gest(cells)
  plot(G)

  # P-P style plot
  plot(G, cbind(km,theo) ~ theo)

  # the empirical G is below the Poisson G,
  # indicating an inhibited pattern

  if(interactive()) {
     plot(G, . ~ r)
     plot(G, . ~ theo)
     plot(G, asin(sqrt(.)) ~ asin(sqrt(theo)))
  }

Foxall's Distance Functions

Description

Given a point pattern X and a spatial object Y, compute estimates of Foxall's G and J functions.

Usage

Gfox(X, Y, r=NULL, breaks=NULL, correction=c("km", "rs", "han"), W, ...)
Jfox(X, Y, r=NULL, breaks=NULL, correction=c("km", "rs", "han"), W, ...,
     warn.trim=TRUE)

Arguments

Details

Given a point pattern X and another spatial object Y, these functions compute two nonparametric measures of association between X and Y, introduced by Foxall (Foxall and Baddeley, 2002).

Let the random variable R be the distance from a typical point of X to the object Y. Foxall's G-function is the cumulative distribution function of R:

G(r) = P(R \le r)

Let the random variable S be the distance from a fixed point in space to the object Y. The cumulative distribution function of S is the (unconditional) spherical contact distribution function

H(r) = P(S \le r)

which is computed by Hest.

Foxall's J-function is the ratio

J(r) = \frac{1-G(r)}{1-H(r)}

For further interpretation, see Foxall and Baddeley (2002).

Accuracy of Jfox depends on the pixel resolution, which is controlled by the arguments eps, dimyx and xy passed to as.mask. For example, use eps=0.1 to specify square pixels of side 0.1 units, and dimyx=256 to specify a 256 by 256 grid of pixels.

Value

A function value table (object of class "fv") which can be printed, plotted, or converted to a data frame of values.

Author(s)

Rob Foxall and Adrian Baddeley Adrian.Baddeley@curtin.edu.au

References

Foxall, R. and Baddeley, A. (2002) Nonparametric measures of association between a spatial point process and a random set, with geological applications. Applied Statistics 51, 165–182.

See Also

Gest, Hest, Jest, Fest

Examples

  X <- copper$SouthPoints
  Y <- copper$SouthLines
  G <- Gfox(X,Y)
  J <- Jfox(X,Y, correction="km")
  

Inhomogeneous Nearest Neighbour Function

Description

Estimates the inhomogeneous nearest neighbour function G of a non-stationary point pattern.

Usage

  Ginhom(X, lambda = NULL, lmin = NULL, ...,
        sigma = NULL, varcov = NULL,
        r = NULL, breaks = NULL, ratio = FALSE,
        update = TRUE, warn.bias=TRUE, savelambda=FALSE)

Arguments

Details

This command computes estimates of the inhomogeneous G-function (van Lieshout, 2010) of a point pattern. It is the counterpart, for inhomogeneous spatial point patterns, of the nearest-neighbour distance distribution function G for homogeneous point patterns computed by Gest.

The argument X should be a point pattern (object of class "ppp").

The inhomogeneous G function is computed using the border correction, equation (7) in Van Lieshout (2010).

The argument lambda should supply the (estimated) values of the intensity function \lambda of the point process. It may be either

a numeric vector

containing the values of the intensity function at the points of the pattern X.

a pixel image

(object of class "im") assumed to contain the values of the intensity function at all locations in the window.

a fitted point process model

(object of class "ppm" or "kppm") whose fitted trend can be used as the fitted intensity. (If update=TRUE the model will first be refitted to the data X before the trend is computed.)

a function

which can be evaluated to give values of the intensity at any locations.

omitted:

if lambda is omitted, then it will be estimated using a ‘leave-one-out’ kernel smoother.

If lambda is a numeric vector, then its length should be equal to the number of points in the pattern X. The value lambda[i] is assumed to be the the (estimated) value of the intensity \lambda(x_i) for the point x_i of the pattern X. Each value must be a positive number; NA's are not allowed.

If lambda is a pixel image, the domain of the image should cover the entire window of the point pattern. If it does not (which may occur near the boundary because of discretisation error), then the missing pixel values will be obtained by applying a Gaussian blur to lambda using blur, then looking up the values of this blurred image for the missing locations. (A warning will be issued in this case.)

If lambda is a function, then it will be evaluated in the form lambda(x,y) where x and y are vectors of coordinates of the points of X. It should return a numeric vector with length equal to the number of points in X.

If lambda is omitted, then it will be estimated using a ‘leave-one-out’ kernel smoother. The estimate lambda[i] for the point X[i] is computed by removing X[i] from the point pattern, applying kernel smoothing to the remaining points using density.ppp, and evaluating the smoothed intensity at the point X[i]. The smoothing kernel bandwidth is controlled by the arguments sigma and varcov, which are passed to density.ppp along with any extra arguments.

Value

An object of class "fv", see fv.object, which can be plotted directly using plot.fv.

Author(s)

Original code by Marie-Colette van Lieshout. C implementation and R adaptation by Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Ege Rubak rubak@math.aau.dk.

References

Van Lieshout, M.N.M. and Baddeley, A.J. (1996) A nonparametric measure of spatial interaction in point patterns. Statistica Neerlandica 50, 344–361.

Van Lieshout, M.N.M. (2010) A J-function for inhomogeneous point processes. Statistica Neerlandica 65, 183–201.

See Also

Finhom, Jinhom, Gest

Examples

  plot(Ginhom(swedishpines, sigma=10))

  
    plot(Ginhom(swedishpines, sigma=bw.diggle, adjust=2))
  

Marked Nearest Neighbour Distance Function

Description

For a marked point pattern, estimate the distribution of the distance from a typical point in subset I to the nearest point of subset J.

Usage

Gmulti(X, I, J, r=NULL, breaks=NULL, ...,
        disjoint=NULL, correction=c("rs", "km", "han"))

Arguments

Details

The function Gmulti generalises Gest (for unmarked point patterns) and Gdot and Gcross (for multitype point patterns) to arbitrary marked point patterns.

Suppose X_I, X_J are subsets, possibly overlapping, of a marked point process. This function computes an estimate of the cumulative distribution function G_{IJ}(r) of the distance from a typical point of X_I to the nearest distinct point of X_J.

The argument X must be a point pattern (object of class "ppp") or any data that are acceptable to as.ppp.

The arguments I and J specify two subsets of the point pattern. They may be any type of subset indices, for example, logical vectors of length equal to npoints(X), or integer vectors with entries in the range 1 to npoints(X), or negative integer vectors.

Alternatively, I and J may be functions that will be applied to the point pattern X to obtain index vectors. If I is a function, then evaluating I(X) should yield a valid subset index. This option is useful when generating simulation envelopes using envelope.

This algorithm estimates the distribution function G_{IJ}(r) from the point pattern X. It assumes that X can be treated as a realisation of a stationary (spatially homogeneous) random spatial point process in the plane, observed through a bounded window. The window (which is specified in X as Window(X)) may have arbitrary shape. Biases due to edge effects are treated in the same manner as in Gest.

The argument r is the vector of values for the distance r at which G_{IJ}(r) should be evaluated. It is also used to determine the breakpoints (in the sense of hist) for the computation of histograms of distances. The reduced-sample and Kaplan-Meier estimators are computed from histogram counts. In the case of the Kaplan-Meier estimator this introduces a discretisation error which is controlled by the fineness of the breakpoints.

First-time users would be strongly advised not to specify r. However, if it is specified, r must satisfy r[1] = 0, and max(r) must be larger than the radius of the largest disc contained in the window. Furthermore, the successive entries of r must be finely spaced.

The algorithm also returns an estimate of the hazard rate function, \lambda(r), of G_{IJ}(r). This estimate should be used with caution as G_{IJ}(r) is not necessarily differentiable.

The naive empirical distribution of distances from each point of the pattern X to the nearest other point of the pattern, is a biased estimate of G_{IJ}. However this is also returned by the algorithm, as it is sometimes useful in other contexts. Care should be taken not to use the uncorrected empirical G_{IJ} as if it were an unbiased estimator of G_{IJ}.

Value

An object of class "fv" (see fv.object).

Essentially a data frame containing six numeric columns

Warnings

The function G_{IJ} does not necessarily have a density.

The reduced sample estimator of G_{IJ} is pointwise approximately unbiased, but need not be a valid distribution function; it may not be a nondecreasing function of r. Its range is always within [0,1].

The spatial Kaplan-Meier estimator of G_{IJ} is always nondecreasing but its maximum value may be less than 1.

Author(s)

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

References

Cressie, N.A.C. Statistics for spatial data. John Wiley and Sons, 1991.

Diggle, P.J. Statistical analysis of spatial point patterns. Academic Press, 1983.

Diggle, P. J. (1986). Displaced amacrine cells in the retina of a rabbit : analysis of a bivariate spatial point pattern. J. Neurosci. Meth. 18, 115–125.

Harkness, R.D and Isham, V. (1983) A bivariate spatial point pattern of ants' nests. Applied Statistics 32, 293–303

Lotwick, H. W. and Silverman, B. W. (1982). Methods for analysing spatial processes of several types of points. J. Royal Statist. Soc. Ser. B 44, 406–413.

Ripley, B.D. Statistical inference for spatial processes. Cambridge University Press, 1988.

Stoyan, D, Kendall, W.S. and Mecke, J. Stochastic geometry and its applications. 2nd edition. Springer Verlag, 1995.

Van Lieshout, M.N.M. and Baddeley, A.J. (1999) Indices of dependence between types in multivariate point patterns. Scandinavian Journal of Statistics 26, 511–532.

See Also

Gcross, Gdot, Gest

Examples

    trees <- longleaf
     # Longleaf Pine data: marks represent diameter
    
    Gm <- Gmulti(trees, marks(trees) <= 15, marks(trees) >= 25)
    plot(Gm)

Inhomogeneous Marked G-Function

Description

For a marked point pattern, estimate the inhomogeneous version of the multitype G function, effectively the cumulative distribution function of the distance from a point in subset I to the nearest point in subset J, adjusted for spatially varying intensity.

Usage

  Gmulti.inhom(X, I, J,
             lambda = NULL, lambdaI = NULL, lambdaJ = NULL,
             lambdamin = NULL, ...,
             r = NULL,
             ReferenceMeasureMarkSetI = NULL,
             ratio = FALSE)

  GmultiInhom(X, I, J,
             lambda = NULL, lambdaI = NULL, lambdaJ = NULL,
             lambdamin = NULL, ...,
             r = NULL,
             ReferenceMeasureMarkSetI = NULL,
             ratio = FALSE)

Arguments

Details

See Cronie and Van Lieshout (2015).

The functions GmultiInhom and Gmulti.inhom are identical.

Value

Object of class "fv" containing the estimate of the inhomogeneous multitype G function.

Author(s)

Ottmar Cronie and Marie-Colette van Lieshout. Rewritten for spatstat by Adrian Baddeley Adrian.Baddeley@curtin.edu.au.

References

Cronie, O. and Van Lieshout, M.N.M. (2015) Summary statistics for inhomogeneous marked point processes. Annals of the Institute of Statistical Mathematics DOI: 10.1007/s10463-015-0515-z

See Also

Ginhom, Gmulti

Examples

  X <- rescale(amacrine)
  I <- (marks(X) == "on")
  J <- (marks(X) == "off")
  if(interactive() && require(spatstat.model)) {
    ## how to do it normally
    mod <- ppm(X ~ marks * x)
    lam <- fitted(mod, dataonly=TRUE)
    lmin <- min(predict(mod)[["off"]]) * 0.9
  } else {
    ## for package testing
    lam <- intensity(X)[as.integer(marks(X))]
    lmin <- intensity(X)[2] * 0.9
  }
  plot(GmultiInhom(X, I, J, lambda=lam, lambdamin=lmin))
  # equivalent
  plot(GmultiInhom(X, I, J, lambdaI=lam[I], lambdaJ=lam[J], lambdamin=lmin),
       main="")

Spherical Contact Distribution Function

Description

Estimates the spherical contact distribution function of a random set.

Usage

Hest(X, r=NULL, breaks=NULL, ...,
     W,
     correction=c("km", "rs", "han"),
     conditional=TRUE)

Arguments

Details

The spherical contact distribution function of a stationary random set X is the cumulative distribution function H of the distance from a fixed point in space to the nearest point of X, given that the point lies outside X. That is, H(r) equals the probability that X lies closer than r units away from the fixed point x, given that X does not cover x.

Let D = d(x,X) be the shortest distance from an arbitrary point x to the set X. Then the spherical contact distribution function is

H(r) = P(D \le r \mid D > 0)

For a point process, the spherical contact distribution function is the same as the empty space function F discussed in Fest.

The argument X may be a point pattern (object of class "ppp"), a line segment pattern (object of class "psp") or a window (object of class "owin"). It is assumed to be a realisation of a stationary random set.

The algorithm first calls distmap to compute the distance transform of X, then computes the Kaplan-Meier and reduced-sample estimates of the cumulative distribution following Hansen et al (1999). If conditional=TRUE (the default) the algorithm returns an estimate of the spherical contact function H(r) as defined above. If conditional=FALSE, it instead returns an estimate of the cumulative distribution function H^\ast(r) = P(D \le r) which includes a jump at r=0 if X has nonzero area.

Accuracy depends on the pixel resolution, which is controlled by the arguments eps, dimyx and xy passed to as.mask. For example, use eps=0.1 to specify square pixels of side 0.1 units, and dimyx=256 to specify a 256 by 256 grid of pixels.

Value

An object of class "fv", see fv.object, which can be plotted directly using plot.fv.

Essentially a data frame containing up to six columns:

Author(s)

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

References

Baddeley, A.J. Spatial sampling and censoring. In O.E. Barndorff-Nielsen, W.S. Kendall and M.N.M. van Lieshout (eds) Stochastic Geometry: Likelihood and Computation. Chapman and Hall, 1998. Chapter 2, pages 37-78.

Baddeley, A.J. and Gill, R.D. The empty space hazard of a spatial pattern. Research Report 1994/3, Department of Mathematics, University of Western Australia, May 1994.

Hansen, M.B., Baddeley, A.J. and Gill, R.D. First contact distributions for spatial patterns: regularity and estimation. Advances in Applied Probability 31 (1999) 15-33.

Ripley, B.D. Statistical inference for spatial processes. Cambridge University Press, 1988.

Stoyan, D, Kendall, W.S. and Mecke, J. Stochastic geometry and its applications. 2nd edition. Springer Verlag, 1995.

See Also

Fest

Examples

   X <- runifpoint(42)
   H <- Hest(X)
   Y <- rpoisline(10)
   H <- Hest(Y)
   H <- Hest(Y, dimyx=256)
   X <- heather$coarse
   plot(Hest(X))
   H <- Hest(X, conditional=FALSE)

   P <- owin(poly=list(x=c(5.3, 8.5, 8.3, 3.7, 1.3, 3.7),
                       y=c(9.7, 10.0, 13.6, 14.4, 10.7, 7.2)))
   plot(X)
   plot(P, add=TRUE, col="red")
   H <- Hest(X, W=P)
   Z <- as.im(FALSE, Frame(X))
   Z[X] <- TRUE
   Z <- Z[P, drop=FALSE]
   plot(Z)
   H <- Hest(Z)

Integrated Squared Error on an Envelope Object

Description

Compute integrated squared error of each of the simulated function estimates in an envelope object.

Usage

ISE.envelope(object, theo, domain, dimension=2)

Arguments

Details

The first argument should be an object of class "envelope" and should contain the simulated function estimates (i.e. it should have been computed using envelope with savefuns=TRUE).

The simulated function estimates are extracted from object, and their squared error from the true value theo is computed pointwise. The squared errors are integrated over the interval specified by domain, giving one value of integrated squared error for each simulated function estimate. These values are returned as a numerical vector.

Value

A numeric vector of length equal to the number of simulated functions.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Martin Hazelton Martin.Hazelton@otago.ac.nz and Tilman Davies Tilman.Davies@otago.ac.nz.

See Also

bias.envelope, MISE.envelope.

Examples

  E <- envelope(cells, Kest, correction="translate", nsim=20, savefuns=TRUE)
  theoK <- function(r) { pi * r^2 }
  dom <- c(0, 0.1)
  ISE.envelope(E, theoK, dom)

Estimate the I-function

Description

Estimates the summary function I(r) for a multitype point pattern.

Usage

  Iest(X, ..., eps=NULL, r=NULL, breaks=NULL, correction=NULL)

Arguments

Details

The I function summarises the dependence between types in a multitype point process (Van Lieshout and Baddeley, 1999) It is based on the concept of the J function for an unmarked point process (Van Lieshout and Baddeley, 1996). See Jest for information about the J function.

The I function is defined as

% I(r) = \sum_{i=1}^m p_i J_{ii}(r) % - J_{\bullet\bullet}(r)

where J_{\bullet\bullet} is the J function for the entire point process ignoring the marks, while J_{ii} is the J function for the process consisting of points of type i only, and p_i is the proportion of points which are of type i.

The I function is designed to measure dependence between points of different types, even if the points are not Poisson. Let X be a stationary multitype point process, and write X_i for the process of points of type i. If the processes X_i are independent of each other, then the I-function is identically equal to 0. Deviations I(r) < 1 or I(r) > 1 typically indicate negative and positive association, respectively, between types. See Van Lieshout and Baddeley (1999) for further information.

An estimate of I derived from a multitype spatial point pattern dataset can be used in exploratory data analysis and formal inference about the pattern. The estimate of I(r) is compared against the constant function 0. Deviations I(r) < 1 or I(r) > 1 may suggest negative and positive association, respectively.

This algorithm estimates the I-function from the multitype point pattern X. It assumes that X can be treated as a realisation of a stationary (spatially homogeneous) random spatial marked point process in the plane, observed through a bounded window.

The argument X is interpreted as a point pattern object (of class "ppp", see ppp.object) and can be supplied in any of the formats recognised by as.ppp(). It must be a multitype point pattern (it must have a marks vector which is a factor).

The function Jest is called to compute estimates of the J functions in the formula above. In fact three different estimates are computed using different edge corrections. See Jest for information.

Value

An object of class "fv", see fv.object, which can be plotted directly using plot.fv.

Essentially a data frame containing

Note

Sizeable amounts of memory may be needed during the calculation.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

References

Van Lieshout, M.N.M. and Baddeley, A.J. (1996) A nonparametric measure of spatial interaction in point patterns. Statistica Neerlandica 50, 344–361.

Van Lieshout, M.N.M. and Baddeley, A.J. (1999) Indices of dependence between types in multivariate point patterns. Scandinavian Journal of Statistics 26, 511–532.

See Also

Jest

Examples

   Ic <- Iest(amacrine)
   plot(Ic, main="Amacrine Cells data")
   # values are below I= 0, suggesting negative association
   # between 'on' and 'off' cells.

Multitype J Function (i-to-j)

Description

For a multitype point pattern, estimate the multitype J function summarising the interpoint dependence between points of type i and of type j.

Usage

Jcross(X, i, j, eps=NULL, r=NULL, breaks=NULL, ..., correction=NULL)

Arguments

Details

This function Jcross and its companions Jdot and Jmulti are generalisations of the function Jest to multitype point patterns.

A multitype point pattern is a spatial pattern of points classified into a finite number of possible “colours” or “types”. In the spatstat package, a multitype pattern is represented as a single point pattern object in which the points carry marks, and the mark value attached to each point determines the type of that point.

The argument X must be a point pattern (object of class "ppp") or any data that are acceptable to as.ppp. It must be a marked point pattern, and the mark vector X$marks must be a factor. The argument i will be interpreted as a level of the factor X$marks. (Warning: this means that an integer value i=3 will be interpreted as the number 3, not the 3rd smallest level).

The “type i to type j” multitype J function of a stationary multitype point process X was introduced by Van lieshout and Baddeley (1999). It is defined by

J_{ij}(r) = \frac{1 - G_{ij}(r)}{1 - F_{j}(r)}

where G_{ij}(r) is the distribution function of the distance from a type i point to the nearest point of type j, and F_{j}(r) is the distribution function of the distance from a fixed point in space to the nearest point of type j in the pattern.

An estimate of J_{ij}(r) is a useful summary statistic in exploratory data analysis of a multitype point pattern. If the subprocess of type i points is independent of the subprocess of points of type j, then J_{ij}(r) \equiv 1. Hence deviations of the empirical estimate of J_{ij} from the value 1 may suggest dependence between types.

This algorithm estimates J_{ij}(r) from the point pattern X. It assumes that X can be treated as a realisation of a stationary (spatially homogeneous) random spatial point process in the plane, observed through a bounded window. The window (which is specified in X as Window(X)) may have arbitrary shape. Biases due to edge effects are treated in the same manner as in Jest, using the Kaplan-Meier and border corrections. The main work is done by Gmulti and Fest.

The argument r is the vector of values for the distance r at which J_{ij}(r) should be evaluated. The values of r must be increasing nonnegative numbers and the maximum r value must not exceed the radius of the largest disc contained in the window.

Value

An object of class "fv" (see fv.object).

Essentially a data frame containing six numeric columns

The result also has two attributes "G" and "F" which are respectively the outputs of Gcross and Fest for the point pattern.

Warnings

The arguments i and j are always interpreted as levels of the factor X$marks. They are converted to character strings if they are not already character strings. The value i=1 does not refer to the first level of the factor.

Author(s)

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

References

Van Lieshout, M.N.M. and Baddeley, A.J. (1996) A nonparametric measure of spatial interaction in point patterns. Statistica Neerlandica 50, 344–361.

Van Lieshout, M.N.M. and Baddeley, A.J. (1999) Indices of dependence between types in multivariate point patterns. Scandinavian Journal of Statistics 26, 511–532.

See Also

Jdot, Jest, Jmulti

Examples

     # Lansing woods data: 6 types of trees
    woods <- lansing
    
    Jhm <- Jcross(woods, "hickory", "maple")
    # diagnostic plot for independence between hickories and maples
    plot(Jhm)

    # synthetic example with two types "a" and "b"
    pp <- runifpoint(30) %mark% factor(sample(c("a","b"), 30, replace=TRUE))
    J <- Jcross(pp)

Inhomogeneous Multitype J function (i-to-j)

Description

For a multitype point pattern, estimate the inhomogeneous multitype J function summarising the interpoint dependence between points of type i and of type j.

Usage

  Jcross.inhom(X, i, j,
               lambda = NULL, lambdaI = NULL, lambdaJ = NULL,
               lambdamin = NULL,
               ...,
               r = NULL, ReferenceMeasureMarkSetI = NULL, ratio = FALSE)

Arguments

Details

This function is the counterpart of Jcross for inhomogeneous patterns. It is computed as a special case of Jmulti.inhom.

Value

Object of class "fv" containing the estimate of the inhomogeneous multitype J function.

Author(s)

Jonatan Gonzalez and Adrian Baddeley Adrian.Baddeley@curtin.edu.au.

References

Cronie, O. and Van Lieshout, M.N.M. (2015) Summary statistics for inhomogeneous marked point processes. Annals of the Institute of Statistical Mathematics DOI: 10.1007/s10463-015-0515-z

See Also

Jdot.inhom, Jmulti.inhom, Jcross.

Examples

  X <- rescale(amacrine)
  if(interactive() && require(spatstat.model)) {
    ## how to do it normally
    mod <- ppm(X ~ marks * x)
    lam <- fitted(mod, dataonly=TRUE)
    lmin <- min(predict(mod)[["off"]]) * 0.9
    dd <- NULL
  } else {
    ## for package testing
    lam <- intensity(X)[as.integer(marks(X))]
    lmin <- intensity(X)[2] * 0.9
    dd <- 32
  }
  JC <- Jcross.inhom(X, "on", "off", lambda=lam, lambdamin=lmin, dimyx=dd)

Multitype J Function (i-to-any)

Description

For a multitype point pattern, estimate the multitype J function summarising the interpoint dependence between the type i points and the points of any type.

Usage

Jdot(X, i, eps=NULL, r=NULL, breaks=NULL, ..., correction=NULL)

Arguments

Details

This function Jdot and its companions Jcross and Jmulti are generalisations of the function Jest to multitype point patterns.

A multitype point pattern is a spatial pattern of points classified into a finite number of possible “colours” or “types”. In the spatstat package, a multitype pattern is represented as a single point pattern object in which the points carry marks, and the mark value attached to each point determines the type of that point.

The argument X must be a point pattern (object of class "ppp") or any data that are acceptable to as.ppp. It must be a marked point pattern, and the mark vector X$marks must be a factor. The argument i will be interpreted as a level of the factor X$marks. (Warning: this means that an integer value i=3 will be interpreted as the number 3, not the 3rd smallest level.)

The “type i to any type” multitype J function of a stationary multitype point process X was introduced by Van lieshout and Baddeley (1999). It is defined by

J_{i\bullet}(r) = \frac{1 - G_{i\bullet}(r)}{1 - F_{\bullet}(r)}

where G_{i\bullet}(r) is the distribution function of the distance from a type i point to the nearest other point of the pattern, and F_{\bullet}(r) is the distribution function of the distance from a fixed point in space to the nearest point of the pattern.

An estimate of J_{i\bullet}(r) is a useful summary statistic in exploratory data analysis of a multitype point pattern. If the pattern is a marked Poisson point process, then J_{i\bullet}(r) \equiv 1. If the subprocess of type i points is independent of the subprocess of points of all types not equal to i, then J_{i\bullet}(r) equals J_{ii}(r), the ordinary J function (see Jest and Van Lieshout and Baddeley (1996)) of the points of type i. Hence deviations from zero of the empirical estimate of J_{i\bullet} - J_{ii} may suggest dependence between types.

This algorithm estimates J_{i\bullet}(r) from the point pattern X. It assumes that X can be treated as a realisation of a stationary (spatially homogeneous) random spatial point process in the plane, observed through a bounded window. The window (which is specified in X as Window(X)) may have arbitrary shape. Biases due to edge effects are treated in the same manner as in Jest, using the Kaplan-Meier and border corrections. The main work is done by Gmulti and Fest.

The argument r is the vector of values for the distance r at which J_{i\bullet}(r) should be evaluated. The values of r must be increasing nonnegative numbers and the maximum r value must not exceed the radius of the largest disc contained in the window.

Value

An object of class "fv" (see fv.object).

Essentially a data frame containing six numeric columns

The result also has two attributes "G" and "F" which are respectively the outputs of Gdot and Fest for the point pattern.

Warnings

The argument i is interpreted as a level of the factor X$marks. It is converted to a character string if it is not already a character string. The value i=1 does not refer to the first level of the factor.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net.

References

Van Lieshout, M.N.M. and Baddeley, A.J. (1996) A nonparametric measure of spatial interaction in point patterns. Statistica Neerlandica 50, 344–361.

Van Lieshout, M.N.M. and Baddeley, A.J. (1999) Indices of dependence between types in multivariate point patterns. Scandinavian Journal of Statistics 26, 511–532.

See Also

Jcross, Jest, Jmulti

Examples

     # Lansing woods data: 6 types of trees
   woods <- lansing

    
    Jh. <- Jdot(woods, "hickory")
    plot(Jh.)
    # diagnostic plot for independence between hickories and other trees
    Jhh <- Jest(split(woods)$hickory)
    plot(Jhh, add=TRUE, legendpos="bottom")

    # synthetic example with two marks "a" and "b"
    
    pp <- runifpoint(30) %mark% factor(sample(c("a","b"), 30, replace=TRUE))
    J <- Jdot(pp, "a")
    

Inhomogeneous Multitype J function (i-to-any)

Description

For a multitype point pattern, estimate the inhomogeneous multitype J function summarising the interpoint dependence between points of type i and points of any type.

Usage

  Jdot.inhom(X, i, 
             lambdaI = NULL, lambdadot = NULL,
             lambdamin = NULL,
             ...,
             r = NULL, ReferenceMeasureMarkSetI = NULL, ratio = FALSE)

Arguments

Details

This function is the counterpart of Jdot for inhomogeneous patterns. It is computed as a special case of Jmulti.inhom.

Value

Object of class "fv" containing the estimate of the inhomogeneous multitype J function.

Author(s)

Jonatan Gonzalez and Adrian Baddeley Adrian.Baddeley@curtin.edu.au.

References

Cronie, O. and Van Lieshout, M.N.M. (2015) Summary statistics for inhomogeneous marked point processes. Annals of the Institute of Statistical Mathematics DOI: 10.1007/s10463-015-0515-z

See Also

Jdot.inhom, Jmulti.inhom, Jdot.

Examples

  X <- rescale(amacrine)
  if(interactive() && require(spatstat.model)) {
    ## how to do it normally
    mod <- ppm(X ~ marks * x)
    lam <- fitted(mod, dataonly=TRUE)
    lmin <- min(predict(mod)[["off"]]) * 0.9
    dd <- NULL
  } else {
    ## for package testing 
    lam <- intensity(X)[as.integer(marks(X))]
    lmin <- intensity(X)[2] * 0.9
    dd <- 32
  }
  lamI <- lam[marks(X) == "on"]
  JD <- Jdot.inhom(X, "on", lambdaI=lamI, lambdadot=lam, lambdamin=lmin,
                   dimyx=dd)

Estimate the J-function

Description

Estimates the summary function J(r) for a point pattern in a window of arbitrary shape.

Usage

  Jest(X, ..., eps=NULL, r=NULL, breaks=NULL, correction=NULL)

Arguments

Details

The J function (Van Lieshout and Baddeley, 1996) of a stationary point process is defined as

J(r) = \frac{1-G(r)}{1-F(r)}

where G(r) is the nearest neighbour distance distribution function of the point process (see Gest) and F(r) is its empty space function (see Fest).

For a completely random (uniform Poisson) point process, the J-function is identically equal to 1. Deviations J(r) < 1 or J(r) > 1 typically indicate spatial clustering or spatial regularity, respectively. The J-function is one of the few characteristics that can be computed explicitly for a wide range of point processes. See Van Lieshout and Baddeley (1996), Baddeley et al (2000), Thonnes and Van Lieshout (1999) for further information.

An estimate of J derived from a spatial point pattern dataset can be used in exploratory data analysis and formal inference about the pattern. The estimate of J(r) is compared against the constant function 1. Deviations J(r) < 1 or J(r) > 1 may suggest spatial clustering or spatial regularity, respectively.

This algorithm estimates the J-function from the point pattern X. It assumes that X can be treated as a realisation of a stationary (spatially homogeneous) random spatial point process in the plane, observed through a bounded window. The window (which is specified in X as Window(X)) may have arbitrary shape.

The argument X is interpreted as a point pattern object (of class "ppp", see ppp.object) and can be supplied in any of the formats recognised by as.ppp().

The functions Fest and Gest are called to compute estimates of F(r) and G(r) respectively. These estimates are then combined by simply taking the ratio J(r) = (1-G(r))/(1-F(r)).

In fact several different estimates are computed using different edge corrections (Baddeley, 1998).

The Kaplan-Meier estimate (returned as km) is the ratio J = (1-G)/(1-F) of the Kaplan-Meier estimates of 1-F and 1-G computed by Fest and Gest respectively. This is computed if correction=NULL or if correction includes "km".

The Hanisch-style estimate (returned as han) is the ratio J = (1-G)/(1-F) where F is the Chiu-Stoyan estimate of F and G is the Hanisch estimate of G. This is computed if correction=NULL or if correction includes "cs" or "han".

The reduced-sample or border corrected estimate (returned as rs) is the same ratio J = (1-G)/(1-F) of the border corrected estimates. This is computed if correction=NULL or if correction includes "rs" or "border".

These edge-corrected estimators are slightly biased for J, since they are ratios of approximately unbiased estimators. The logarithm of the Kaplan-Meier estimate is exactly unbiased for \log J.

The uncorrected estimate (returned as un and computed only if correction includes "none") is the ratio J = (1-G)/(1-F) of the uncorrected (“raw”) estimates of the survival functions of F and G, which are the empirical distribution functions of the empty space distances Fest(X,...)$raw and of the nearest neighbour distances Gest(X,...)$raw. The uncorrected estimates of F and G are severely biased. However the uncorrected estimate of J is approximately unbiased (if the process is close to Poisson); it is insensitive to edge effects, and should be used when edge effects are severe (see Baddeley et al, 2000).

The algorithm for Fest uses two discrete approximations which are controlled by the parameter eps and by the spacing of values of r respectively. See Fest for details. First-time users are strongly advised not to specify these arguments.

Note that the value returned by Jest includes the output of Fest and Gest as attributes (see the last example below). If the user is intending to compute the F,G and J functions for the point pattern, it is only necessary to call Jest.

Value

An object of class "fv", see fv.object, which can be plotted directly using plot.fv.

Essentially a data frame containing

The data frame also has attributes

Note

Sizeable amounts of memory may be needed during the calculation.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

References

Baddeley, A.J. Spatial sampling and censoring. In O.E. Barndorff-Nielsen, W.S. Kendall and M.N.M. van Lieshout (eds) Stochastic Geometry: Likelihood and Computation. Chapman and Hall, 1998. Chapter 2, pages 37–78.

Baddeley, A.J. and Gill, R.D. The empty space hazard of a spatial pattern. Research Report 1994/3, Department of Mathematics, University of Western Australia, May 1994.

Baddeley, A.J. and Gill, R.D. Kaplan-Meier estimators of interpoint distance distributions for spatial point processes. Annals of Statistics 25 (1997) 263–292.

Baddeley, A., Kerscher, M., Schladitz, K. and Scott, B.T. Estimating the J function without edge correction. Statistica Neerlandica 54 (2000) 315–328.

Borgefors, G. Distance transformations in digital images. Computer Vision, Graphics and Image Processing 34 (1986) 344–371.

Cressie, N.A.C. Statistics for spatial data. John Wiley and Sons, 1991.

Diggle, P.J. Statistical analysis of spatial point patterns. Academic Press, 1983.

Ripley, B.D. Statistical inference for spatial processes. Cambridge University Press, 1988.

Stoyan, D, Kendall, W.S. and Mecke, J. Stochastic geometry and its applications. 2nd edition. Springer Verlag, 1995.

Thonnes, E. and Van Lieshout, M.N.M, A comparative study on the power of Van Lieshout and Baddeley's J-function. Biometrical Journal 41 (1999) 721–734.

Van Lieshout, M.N.M. and Baddeley, A.J. A nonparametric measure of spatial interaction in point patterns. Statistica Neerlandica 50 (1996) 344–361.

See Also

Jinhom, Fest, Gest, Kest, km.rs, reduced.sample, kaplan.meier

Examples

   J <- Jest(cells, 0.01)
   plot(J, main="cells data")
   # values are far above J = 1, indicating regular pattern

   data(redwood)
   J <- Jest(redwood, 0.01, legendpos="center")
   plot(J, main="redwood data")
   # values are below J = 1, indicating clustered pattern

Inhomogeneous J-function

Description

Estimates the inhomogeneous J function of a non-stationary point pattern.

Usage

  Jinhom(X, lambda = NULL, lmin = NULL, ...,
        sigma = NULL, varcov = NULL,
        r = NULL, breaks = NULL, ratio=FALSE, 
        update = TRUE, warn.bias=TRUE, savelambda=FALSE)

Arguments

Details

This command computes estimates of the inhomogeneous J-function (Van Lieshout, 2010) of a point pattern. It is the counterpart, for inhomogeneous spatial point patterns, of the J function for homogeneous point patterns computed by Jest.

The argument X should be a point pattern (object of class "ppp").

The inhomogeneous J function is computed as Jinhom(r) = (1 - Ginhom(r))/(1-Finhom(r)) where Ginhom, Finhom are the inhomogeneous G and F functions computed using the border correction (equations (7) and (6) respectively in Van Lieshout, 2010).

The argument lambda should supply the (estimated) values of the intensity function \lambda of the point process. It may be either

a numeric vector

containing the values of the intensity function at the points of the pattern X.

a pixel image

(object of class "im") assumed to contain the values of the intensity function at all locations in the window.

a fitted point process model

(object of class "ppm" or "kppm") whose fitted trend can be used as the fitted intensity. (If update=TRUE the model will first be refitted to the data X before the trend is computed.)

a function

which can be evaluated to give values of the intensity at any locations.

omitted:

if lambda is omitted, then it will be estimated using a ‘leave-one-out’ kernel smoother.

If lambda is a numeric vector, then its length should be equal to the number of points in the pattern X. The value lambda[i] is assumed to be the the (estimated) value of the intensity \lambda(x_i) for the point x_i of the pattern X. Each value must be a positive number; NA's are not allowed.

If lambda is a pixel image, the domain of the image should cover the entire window of the point pattern. If it does not (which may occur near the boundary because of discretisation error), then the missing pixel values will be obtained by applying a Gaussian blur to lambda using blur, then looking up the values of this blurred image for the missing locations. (A warning will be issued in this case.)

If lambda is a function, then it will be evaluated in the form lambda(x,y) where x and y are vectors of coordinates of the points of X. It should return a numeric vector with length equal to the number of points in X.

If lambda is omitted, then it will be estimated using a ‘leave-one-out’ kernel smoother. The estimate lambda[i] for the point X[i] is computed by removing X[i] from the point pattern, applying kernel smoothing to the remaining points using density.ppp, and evaluating the smoothed intensity at the point X[i]. The smoothing kernel bandwidth is controlled by the arguments sigma and varcov, which are passed to density.ppp along with any extra arguments.

Value

An object of class "fv", see fv.object, which can be plotted directly using plot.fv.

Author(s)

Original code by Marie-Colette van Lieshout. C implementation and R adaptation by Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Ege Rubak rubak@math.aau.dk.

References

van Lieshout, M.N.M. and Baddeley, A.J. (1996) A nonparametric measure of spatial interaction in point patterns. Statistica Neerlandica 50, 344–361.

van Lieshout, M.N.M. (2010) A J-function for inhomogeneous point processes. Statistica Neerlandica 65, 183–201.

See Also

Ginhom, Finhom, Jest

Examples

  online <- interactive()
  if(online) {
    plot(Jinhom(swedishpines, sigma=10))
    plot(Jinhom(swedishpines, sigma=bw.diggle, adjust=2))
  } else {
    ## use a coarse grid for faster computation and package testing
    plot(Jinhom(swedishpines, sigma=10, dimyx=32))
  }

Marked J Function

Description

For a marked point pattern, estimate the multitype J function summarising dependence between the points in subset I and those in subset J.

Usage

  Jmulti(X, I, J, eps=NULL, r=NULL, breaks=NULL, ..., disjoint=NULL,
         correction=NULL)

Arguments

Details

The function Jmulti generalises Jest (for unmarked point patterns) and Jdot and Jcross (for multitype point patterns) to arbitrary marked point patterns.

Suppose X_I, X_J are subsets, possibly overlapping, of a marked point process. Define

J_{IJ}(r) = \frac{1 - G_{IJ}(r)}{1 - F_J(r)}

where F_J(r) is the cumulative distribution function of the distance from a fixed location to the nearest point of X_J, and G_{IJ}(r) is the distribution function of the distance from a typical point of X_I to the nearest distinct point of X_J.

The argument X must be a point pattern (object of class "ppp") or any data that are acceptable to as.ppp.

The arguments I and J specify two subsets of the point pattern. They may be any type of subset indices, for example, logical vectors of length equal to npoints(X), or integer vectors with entries in the range 1 to npoints(X), or negative integer vectors.

Alternatively, I and J may be functions that will be applied to the point pattern X to obtain index vectors. If I is a function, then evaluating I(X) should yield a valid subset index. This option is useful when generating simulation envelopes using envelope.

It is assumed that X can be treated as a realisation of a stationary (spatially homogeneous) random spatial point process in the plane, observed through a bounded window. The window (which is specified in X as Window(X)) may have arbitrary shape. Biases due to edge effects are treated in the same manner as in Jest.

The argument r is the vector of values for the distance r at which J_{IJ}(r) should be evaluated. It is also used to determine the breakpoints (in the sense of hist) for the computation of histograms of distances. The reduced-sample and Kaplan-Meier estimators are computed from histogram counts. In the case of the Kaplan-Meier estimator this introduces a discretisation error which is controlled by the fineness of the breakpoints.

First-time users would be strongly advised not to specify r. However, if it is specified, r must satisfy r[1] = 0, and max(r) must be larger than the radius of the largest disc contained in the window. Furthermore, the successive entries of r must be finely spaced.

Value

An object of class "fv" (see fv.object).

Essentially a data frame containing six numeric columns

Author(s)

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

References

Van Lieshout, M.N.M. and Baddeley, A.J. (1999) Indices of dependence between types in multivariate point patterns. Scandinavian Journal of Statistics 26, 511–532.

See Also

Jcross, Jdot, Jest

Examples

    trees <- longleaf
     # Longleaf Pine data: marks represent diameter
    
    Jm <- Jmulti(trees, marks(trees) <= 15, marks(trees) >= 25)
    plot(Jm)

Inhomogeneous Marked J-Function

Description

For a marked point pattern, estimate the inhomogeneous version of the multitype J function.

Usage

Jmulti.inhom(X, I, J,
             lambda = NULL, lambdaI = NULL, lambdaJ = NULL,
             lambdamin = NULL,
             ...,
             r = NULL,
             ReferenceMeasureMarkSetI = NULL,
             ratio = FALSE)

Arguments

Details

This function is the counterpart of Jmulti for inhomogeneous patterns. It is computed by evaluating the inhomogeneous G function GmultiInhom and the inhomogeneous F function FmultiInhom and computing the ratio J = (1-G)/(1-F).

Value

Object of class "fv" containing the estimate of the inhomogeneous multitype J function.

Author(s)

Jonatan Gonzalez and Adrian Baddeley Adrian.Baddeley@curtin.edu.au.

References

Cronie, O. and Van Lieshout, M.N.M. (2015) Summary statistics for inhomogeneous marked point processes. Annals of the Institute of Statistical Mathematics DOI: 10.1007/s10463-015-0515-z

See Also

Jcross.inhom, Jdot.inhom for special cases.

GmultiInhom, FmultiInhom, Jmulti.

Examples

  X <- rescale(amacrine)
  I <- (marks(X) == "on")
  J <- (marks(X) == "off")
  if(interactive() && require(spatstat.model)) {
    ## how to do it normally
    mod <- ppm(X ~ marks * x)
    lam <- fitted(mod, dataonly=TRUE)
    lmin <- min(predict(mod)[["off"]]) * 0.9
    dd <- NULL
  } else {
    ## for package testing
    lam <- intensity(X)[as.integer(marks(X))]
    lmin <- intensity(X)[2] * 0.9
    dd <- 32
  }
  JM <- Jmulti.inhom(X, I, J, lambda=lam, lambdamin=lmin, dimyx=dd)

K-function of a Three-Dimensional Point Pattern

Description

Estimates the K-function from a three-dimensional point pattern.

Usage

  K3est(X, ...,
        rmax = NULL, nrval = 128,
        correction = c("translation", "isotropic"),
        ratio=FALSE)

Arguments

Details

For a stationary point process \Phi in three-dimensional space, the three-dimensional K function is

K_3(r) = \frac 1 \lambda E(N(\Phi, x, r) \mid x \in \Phi)

where \lambda is the intensity of the process (the expected number of points per unit volume) and N(\Phi,x,r) is the number of points of \Phi, other than x itself, which fall within a distance r of x. This is the three-dimensional generalisation of Ripley's K function for two-dimensional point processes (Ripley, 1977).

The three-dimensional point pattern X is assumed to be a partial realisation of a stationary point process \Phi. The distance between each pair of distinct points is computed. The empirical cumulative distribution function of these values, with appropriate edge corrections, is renormalised to give the estimate of K_3(r).

The available edge corrections are:

"translation":

the Ohser translation correction estimator (Ohser, 1983; Baddeley et al, 1993)

"isotropic":

the three-dimensional counterpart of Ripley's isotropic edge correction (Ripley, 1977; Baddeley et al, 1993).

Alternatively correction="all" selects all options.

Value

A function value table (object of class "fv") that can be plotted, printed or coerced to a data frame containing the function values.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rana Moyeed.

References

Baddeley, A.J, Moyeed, R.A., Howard, C.V. and Boyde, A. (1993) Analysis of a three-dimensional point pattern with replication. Applied Statistics 42, 641–668.

Ohser, J. (1983) On estimators for the reduced second moment measure of point processes. Mathematische Operationsforschung und Statistik, series Statistics, 14, 63 – 71.

Ripley, B.D. (1977) Modelling spatial patterns (with discussion). Journal of the Royal Statistical Society, Series B, 39, 172 – 212.

See Also

pp3 to create a three-dimensional point pattern (object of class "pp3").

pcf3est, F3est, G3est for other summary functions of a three-dimensional point pattern.

Kest to estimate the K-function of point patterns in two dimensions or other spaces.

Examples

  X <- rpoispp3(42)
  Z <- K3est(X)
  if(interactive()) plot(Z)

Multitype K Function (Cross-type)

Description

For a multitype point pattern, estimate the multitype K function which counts the expected number of points of type j within a given distance of a point of type i.

Usage

Kcross(X, i, j, r=NULL, breaks=NULL, correction,
       ..., ratio=FALSE, from, to )

Arguments

Details

This function Kcross and its companions Kdot and Kmulti are generalisations of the function Kest to multitype point patterns.

A multitype point pattern is a spatial pattern of points classified into a finite number of possible “colours” or “types”. In the spatstat package, a multitype pattern is represented as a single point pattern object in which the points carry marks, and the mark value attached to each point determines the type of that point.

The argument X must be a point pattern (object of class "ppp") or any data that are acceptable to as.ppp. It must be a marked point pattern, and the mark vector X$marks must be a factor.

The arguments i and j will be interpreted as levels of the factor X$marks. If i and j are missing, they default to the first and second level of the marks factor, respectively.

The “cross-type” (type i to type j) K function of a stationary multitype point process X is defined so that \lambda_j K_{ij}(r) equals the expected number of additional random points of type j within a distance r of a typical point of type i in the process X. Here \lambda_j is the intensity of the type j points, i.e. the expected number of points of type j per unit area. The function K_{ij} is determined by the second order moment properties of X.

An estimate of K_{ij}(r) is a useful summary statistic in exploratory data analysis of a multitype point pattern. If the process of type i points were independent of the process of type j points, then K_{ij}(r) would equal \pi r^2. Deviations between the empirical K_{ij} curve and the theoretical curve \pi r^2 may suggest dependence between the points of types i and j.

This algorithm estimates the distribution function K_{ij}(r) from the point pattern X. It assumes that X can be treated as a realisation of a stationary (spatially homogeneous) random spatial point process in the plane, observed through a bounded window. The window (which is specified in X as Window(X)) may have arbitrary shape. Biases due to edge effects are treated in the same manner as in Kest, using the border correction.

The argument r is the vector of values for the distance r at which K_{ij}(r) should be evaluated. The values of r must be increasing nonnegative numbers and the maximum r value must not exceed the radius of the largest disc contained in the window.

The pair correlation function can also be applied to the result of Kcross; see pcf.

Value

An object of class "fv" (see fv.object).

Essentially a data frame containing numeric columns

together with a column or columns named "border", "bord.modif", "iso" and/or "trans", according to the selected edge corrections. These columns contain estimates of the function K_{ij}(r) obtained by the edge corrections named.

If ratio=TRUE then the return value also has two attributes called "numerator" and "denominator" which are "fv" objects containing the numerators and denominators of each estimate of K(r).

Warnings

The arguments i and j are always interpreted as levels of the factor X$marks. They are converted to character strings if they are not already character strings. The value i=1 does not refer to the first level of the factor.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net.

References

Cressie, N.A.C. Statistics for spatial data. John Wiley and Sons, 1991.

Diggle, P.J. Statistical analysis of spatial point patterns. Academic Press, 1983.

Harkness, R.D and Isham, V. (1983) A bivariate spatial point pattern of ants' nests. Applied Statistics 32, 293–303

Lotwick, H. W. and Silverman, B. W. (1982). Methods for analysing spatial processes of several types of points. J. Royal Statist. Soc. Ser. B 44, 406–413.

Ripley, B.D. Statistical inference for spatial processes. Cambridge University Press, 1988.

Stoyan, D, Kendall, W.S. and Mecke, J. Stochastic geometry and its applications. 2nd edition. Springer Verlag, 1995.

See Also

Kdot, Kest, Kmulti, pcf

Examples

    # amacrine cells data
    K01 <- Kcross(amacrine, "off", "on") 
    plot(K01)

    

    # synthetic example: point pattern with marks 0 and 1
    
     pp <- runifpoispp(50)
     pp <- pp %mark% factor(sample(0:1, npoints(pp), replace=TRUE))
     K <- Kcross(pp, "0", "1")
     K <- Kcross(pp, 0, 1) # equivalent
    

Inhomogeneous Cross K Function

Description

For a multitype point pattern, estimate the inhomogeneous version of the cross K function, which counts the expected number of points of type j within a given distance of a point of type i, adjusted for spatially varying intensity.

Usage

Kcross.inhom(X, i, j, lambdaI=NULL, lambdaJ=NULL, ...,  r=NULL, breaks=NULL,
         correction = c("border", "isotropic", "Ripley", "translate"),
         sigma=NULL, varcov=NULL,
         lambdaIJ=NULL,
         lambdaX=NULL, update=TRUE, leaveoneout=TRUE)

Arguments

Details

This is a generalisation of the function Kcross to include an adjustment for spatially inhomogeneous intensity, in a manner similar to the function Kinhom.

The inhomogeneous cross-type K function is described by Moller and Waagepetersen (2003, pages 48-49 and 51-53).

Briefly, given a multitype point process, suppose the sub-process of points of type j has intensity function \lambda_j(u) at spatial locations u. Suppose we place a mass of 1/\lambda_j(\zeta) at each point \zeta of type j. Then the expected total mass per unit area is 1. The inhomogeneous “cross-type” K function K_{ij}^{\mbox{inhom}}(r) equals the expected total mass within a radius r of a point of the process of type i.

If the process of type i points were independent of the process of type j points, then K_{ij}^{\mbox{inhom}}(r) would equal \pi r^2. Deviations between the empirical K_{ij} curve and the theoretical curve \pi r^2 suggest dependence between the points of types i and j.

The argument X must be a point pattern (object of class "ppp") or any data that are acceptable to as.ppp. It must be a marked point pattern, and the mark vector X$marks must be a factor.

The arguments i and j will be interpreted as levels of the factor X$marks. (Warning: this means that an integer value i=3 will be interpreted as the number 3, not the 3rd smallest level). If i and j are missing, they default to the first and second level of the marks factor, respectively.

The argument lambdaI supplies the values of the intensity of the sub-process of points of type i. It may be either

a pixel image

(object of class "im") which gives the values of the type i intensity at all locations in the window containing X;

a numeric vector

containing the values of the type i intensity evaluated only at the data points of type i. The length of this vector must equal the number of type i points in X.

a function

which can be evaluated to give values of the intensity at any locations.

a fitted point process model

(object of class "ppm", "kppm" or "dppm") whose fitted trend can be used as the fitted intensity. (If update=TRUE the model will first be refitted to the data X before the trend is computed.)

omitted:

if lambdaI is omitted then it will be estimated using a leave-one-out kernel smoother.

If lambdaI is omitted, then it will be estimated using a ‘leave-one-out’ kernel smoother, as described in Baddeley, Moller and Waagepetersen (2000). The estimate of lambdaI for a given point is computed by removing the point from the point pattern, applying kernel smoothing to the remaining points using density.ppp, and evaluating the smoothed intensity at the point in question. The smoothing kernel bandwidth is controlled by the arguments sigma and varcov, which are passed to density.ppp along with any extra arguments.

Similarly lambdaJ should contain estimated values of the intensity of the sub-process of points of type j. It may be either a pixel image, a function, a numeric vector, or omitted.

Alternatively if the argument lambdaX is given, then it specifies the intensity values for all points of X, and the arguments lambdaI, lambdaJ will be ignored.

The optional argument lambdaIJ is for advanced use only. It is a matrix containing estimated values of the products of these two intensities for each pair of data points of types i and j respectively.

The argument r is the vector of values for the distance r at which K_{ij}(r) should be evaluated. The values of r must be increasing nonnegative numbers and the maximum r value must not exceed the radius of the largest disc contained in the window.

The argument correction chooses the edge correction as explained e.g. in Kest.

The pair correlation function can also be applied to the result of Kcross.inhom; see pcf.

Value

An object of class "fv" (see fv.object).

Essentially a data frame containing numeric columns

together with a column or columns named "border", "bord.modif", "iso" and/or "trans", according to the selected edge corrections. These columns contain estimates of the function K_{ij}(r) obtained by the edge corrections named.

Warnings

The arguments i and j are always interpreted as levels of the factor X$marks. They are converted to character strings if they are not already character strings. The value i=1 does not refer to the first level of the factor.

Author(s)

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

References

Baddeley, A., Moller, J. and Waagepetersen, R. (2000) Non- and semiparametric estimation of interaction in inhomogeneous point patterns. Statistica Neerlandica 54, 329–350.

Moller, J. and Waagepetersen, R. Statistical Inference and Simulation for Spatial Point Processes Chapman and Hall/CRC Boca Raton, 2003.

See Also

Kcross, Kinhom, Kdot.inhom, Kmulti.inhom, pcf

Examples

    # Lansing Woods data
    woods <- lansing
    
    ma <- split(woods)$maple
    wh <- split(woods)$whiteoak

    # method (1): estimate intensities by nonparametric smoothing
    lambdaM <- density.ppp(ma, sigma=0.15, at="points")
    lambdaW <- density.ppp(wh, sigma=0.15, at="points")
    K <- Kcross.inhom(woods, "whiteoak", "maple", lambdaW, lambdaM)

    # method (2): leave-one-out
    K <- Kcross.inhom(woods, "whiteoak", "maple", sigma=0.15)

    # method (3): fit parametric intensity model
    if(require("spatstat.model")) {
    fit <- ppm(woods ~marks * polynom(x,y,2))
    # alternative (a): use fitted model as 'lambda' argument
    online <- interactive()
    K <- Kcross.inhom(woods, "whiteoak", "maple",
                      lambdaI=fit, lambdaJ=fit,
                      update=online, leaveoneout=online)
    K <- Kcross.inhom(woods, "whiteoak", "maple",
                      lambdaX=fit,
                      update=online, leaveoneout=online)
    # alternative (b): evaluate fitted intensities at data points
    # (these are the intensities of the sub-processes of each type)
    inten <- fitted(fit, dataonly=TRUE, leaveoneout=FALSE)
    # split according to types of points
    lambda <- split(inten, marks(woods))
    K <- Kcross.inhom(woods, "whiteoak", "maple",
              lambda$whiteoak, lambda$maple)
    }
    
    # synthetic example: type A points have intensity 50,
    #                    type B points have intensity 100 * x
    lamB <- as.im(function(x,y){50 + 100 * x}, owin())
    X <- superimpose(A=runifpoispp(50), B=rpoispp(lamB))
    K <- Kcross.inhom(X, "A", "B",
        lambdaI=as.im(50, Window(X)), lambdaJ=lamB)

Multitype K Function (i-to-any)

Description

For a multitype point pattern, estimate the multitype K function which counts the expected number of other points of the process within a given distance of a point of type i.

Usage

Kdot(X, i, r=NULL, breaks=NULL, correction, ..., ratio=FALSE, from)

Arguments

Details

This function Kdot and its companions Kcross and Kmulti are generalisations of the function Kest to multitype point patterns.

A multitype point pattern is a spatial pattern of points classified into a finite number of possible “colours” or “types”. In the spatstat package, a multitype pattern is represented as a single point pattern object in which the points carry marks, and the mark value attached to each point determines the type of that point.

The argument X must be a point pattern (object of class "ppp") or any data that are acceptable to as.ppp. It must be a marked point pattern, and the mark vector X$marks must be a factor.

The argument i will be interpreted as a level of the factor X$marks. If i is missing, it defaults to the first level of the marks factor, i = levels(X$marks)[1].

The “type i to any type” multitype K function of a stationary multitype point process X is defined so that \lambda K_{i\bullet}(r) equals the expected number of additional random points within a distance r of a typical point of type i in the process X. Here \lambda is the intensity of the process, i.e. the expected number of points of X per unit area. The function K_{i\bullet} is determined by the second order moment properties of X.

An estimate of K_{i\bullet}(r) is a useful summary statistic in exploratory data analysis of a multitype point pattern. If the subprocess of type i points were independent of the subprocess of points of all types not equal to i, then K_{i\bullet}(r) would equal \pi r^2. Deviations between the empirical K_{i\bullet} curve and the theoretical curve \pi r^2 may suggest dependence between types.

This algorithm estimates the distribution function K_{i\bullet}(r) from the point pattern X. It assumes that X can be treated as a realisation of a stationary (spatially homogeneous) random spatial point process in the plane, observed through a bounded window. The window (which is specified in X as Window(X)) may have arbitrary shape. Biases due to edge effects are treated in the same manner as in Kest, using the chosen edge correction(s).

The argument r is the vector of values for the distance r at which K_{i\bullet}(r) should be evaluated. The values of r must be increasing nonnegative numbers and the maximum r value must not exceed the radius of the largest disc contained in the window.

The pair correlation function can also be applied to the result of Kdot; see pcf.

Value

An object of class "fv" (see fv.object).

Essentially a data frame containing numeric columns

together with a column or columns named "border", "bord.modif", "iso" and/or "trans", according to the selected edge corrections. These columns contain estimates of the function K_{i\bullet}(r) obtained by the edge corrections named.

If ratio=TRUE then the return value also has two attributes called "numerator" and "denominator" which are "fv" objects containing the numerators and denominators of each estimate of K(r).

Warnings

The argument i is interpreted as a level of the factor X$marks. It is converted to a character string if it is not already a character string. The value i=1 does not refer to the first level of the factor.

The reduced sample estimator of K_{i\bullet} is pointwise approximately unbiased, but need not be a valid distribution function; it may not be a nondecreasing function of r.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net.

References

Cressie, N.A.C. Statistics for spatial data. John Wiley and Sons, 1991.

Diggle, P.J. Statistical analysis of spatial point patterns. Academic Press, 1983.

Harkness, R.D and Isham, V. (1983) A bivariate spatial point pattern of ants' nests. Applied Statistics 32, 293–303

Lotwick, H. W. and Silverman, B. W. (1982). Methods for analysing spatial processes of several types of points. J. Royal Statist. Soc. Ser. B 44, 406–413.

Ripley, B.D. Statistical inference for spatial processes. Cambridge University Press, 1988.

Stoyan, D, Kendall, W.S. and Mecke, J. Stochastic geometry and its applications. 2nd edition. Springer Verlag, 1995.

See Also

Kdot, Kest, Kmulti, pcf

Examples

     # Lansing woods data: 6 types of trees
    woods <- lansing

    

    Kh. <- Kdot(woods, "hickory") 
    # diagnostic plot for independence between hickories and other trees
    plot(Kh.)

    # synthetic example with two marks "a" and "b"
    
      pp <- runifpoispp(50)
      pp <- pp %mark% factor(sample(c("a","b"), npoints(pp), replace=TRUE))
      K <- Kdot(pp, "a")
   

Inhomogeneous Multitype K Dot Function

Description

For a multitype point pattern, estimate the inhomogeneous version of the dot K function, which counts the expected number of points of any type within a given distance of a point of type i, adjusted for spatially varying intensity.

Usage

Kdot.inhom(X, i, lambdaI=NULL, lambdadot=NULL, ..., r=NULL, breaks=NULL,
         correction = c("border", "isotropic", "Ripley", "translate"),
         sigma=NULL, varcov=NULL, lambdaIdot=NULL,
         lambdaX=NULL, update=TRUE, leaveoneout=TRUE)

Arguments

Details

This is a generalisation of the function Kdot to include an adjustment for spatially inhomogeneous intensity, in a manner similar to the function Kinhom.

Briefly, given a multitype point process, consider the points without their types, and suppose this unmarked point process has intensity function \lambda(u) at spatial locations u. Suppose we place a mass of 1/\lambda(\zeta) at each point \zeta of the process. Then the expected total mass per unit area is 1. The inhomogeneous “dot-type” K function K_{i\bullet}^{\mbox{inhom}}(r) equals the expected total mass within a radius r of a point of the process of type i, discounting this point itself.

If the process of type i points were independent of the points of other types, then K_{i\bullet}^{\mbox{inhom}}(r) would equal \pi r^2. Deviations between the empirical K_{i\bullet} curve and the theoretical curve \pi r^2 suggest dependence between the points of types i and j for j\neq i.

The argument X must be a point pattern (object of class "ppp") or any data that are acceptable to as.ppp. It must be a marked point pattern, and the mark vector X$marks must be a factor.

The argument i will be interpreted as a level of the factor X$marks. (Warning: this means that an integer value i=3 will be interpreted as the number 3, not the 3rd smallest level). If i is missing, it defaults to the first level of the marks factor, i = levels(X$marks)[1].

The argument lambdaI supplies the values of the intensity of the sub-process of points of type i. It may be either

a pixel image

(object of class "im") which gives the values of the type i intensity at all locations in the window containing X;

a numeric vector

containing the values of the type i intensity evaluated only at the data points of type i. The length of this vector must equal the number of type i points in X.

a function

of the form function(x,y) which can be evaluated to give values of the intensity at any locations.

a fitted point process model

(object of class "ppm", "kppm" or "dppm") whose fitted trend can be used as the fitted intensity. (If update=TRUE the model will first be refitted to the data X before the trend is computed.)

omitted:

if lambdaI is omitted then it will be estimated using a leave-one-out kernel smoother.

If lambdaI is omitted, then it will be estimated using a ‘leave-one-out’ kernel smoother, as described in Baddeley, Moller and Waagepetersen (2000). The estimate of lambdaI for a given point is computed by removing the point from the point pattern, applying kernel smoothing to the remaining points using density.ppp, and evaluating the smoothed intensity at the point in question. The smoothing kernel bandwidth is controlled by the arguments sigma and varcov, which are passed to density.ppp along with any extra arguments.

Similarly the argument lambdadot should contain estimated values of the intensity of the entire point process. It may be either a pixel image, a numeric vector of length equal to the number of points in X, a function, or omitted.

Alternatively if the argument lambdaX is given, then it specifies the intensity values for all points of X, and the arguments lambdaI, lambdadot will be ignored. (The two arguments lambdaI, lambdadot allow the user to specify two different methods for calculating the intensities of the two kinds of points, while lambdaX ensures that the same method is used for both kinds of points.)

For advanced use only, the optional argument lambdaIdot is a matrix containing estimated values of the products of these two intensities for each pair of points, the first point of type i and the second of any type.

The argument r is the vector of values for the distance r at which K_{i\bullet}(r) should be evaluated. The values of r must be increasing nonnegative numbers and the maximum r value must not exceed the radius of the largest disc contained in the window.

The argument correction chooses the edge correction as explained e.g. in Kest.

The pair correlation function can also be applied to the result of Kdot.inhom; see pcf.

Value

An object of class "fv" (see fv.object).

Essentially a data frame containing numeric columns

together with a column or columns named "border", "bord.modif", "iso" and/or "trans", according to the selected edge corrections. These columns contain estimates of the function K_{i\bullet}(r) obtained by the edge corrections named.

Warnings

The argument i is interpreted as a level of the factor X$marks. It is converted to a character string if it is not already a character string. The value i=1 does not refer to the first level of the factor.

Author(s)

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

References

Moller, J. and Waagepetersen, R. Statistical Inference and Simulation for Spatial Point Processes Chapman and Hall/CRC Boca Raton, 2003.

See Also

Kdot, Kinhom, Kcross.inhom, Kmulti.inhom, pcf

Examples

    # Lansing Woods data
    woods <- lansing
    woods <- woods[seq(1,npoints(woods), by=10)]
    ma <- split(woods)$maple
    lg <- unmark(woods)

    # Estimate intensities by nonparametric smoothing
    lambdaM <- density.ppp(ma, sigma=0.15, at="points")
    lambdadot <- density.ppp(lg, sigma=0.15, at="points")
    K <- Kdot.inhom(woods, "maple", lambdaI=lambdaM,
                                      lambdadot=lambdadot)

    # Equivalent
    K <- Kdot.inhom(woods, "maple", sigma=0.15)

    # Fit model
    if(require("spatstat.model")) {
    fit <- ppm(woods ~ marks * polynom(x,y,2))
    K <- Kdot.inhom(woods, "maple", lambdaX=fit,
                    update=FALSE, leaveoneout=FALSE)
    }
    
    # synthetic example: type A points have intensity 50,
    #                    type B points have intensity 50 + 100 * x
    lamB <- as.im(function(x,y){50 + 100 * x}, owin())
    lamdot <- as.im(function(x,y) { 100 + 100 * x}, owin())
    X <- superimpose(A=runifpoispp(50), B=rpoispp(lamB))
    K <- Kdot.inhom(X, "B",  lambdaI=lamB,     lambdadot=lamdot)

K-function

Description

Estimates Ripley's reduced second moment function K(r) from a point pattern in a window of arbitrary shape.

Usage

  Kest(X, ..., r=NULL, rmax=NULL, breaks=NULL, 
     correction=c("border", "isotropic", "Ripley", "translate"),
    nlarge=3000, domain=NULL, var.approx=FALSE, ratio=FALSE)

Arguments

Details

The K function (variously called “Ripley's K-function” and the “reduced second moment function”) of a stationary point process X is defined so that \lambda K(r) equals the expected number of additional random points within a distance r of a typical random point of X. Here \lambda is the intensity of the process, i.e. the expected number of points of X per unit area. The K function is determined by the second order moment properties of X.

An estimate of K derived from a spatial point pattern dataset can be used in exploratory data analysis and formal inference about the pattern (Cressie, 1991; Diggle, 1983; Ripley, 1977, 1988). In exploratory analyses, the estimate of K is a useful statistic summarising aspects of inter-point “dependence” and “clustering”. For inferential purposes, the estimate of K is usually compared to the true value of K for a completely random (Poisson) point process, which is K(r) = \pi r^2. Deviations between the empirical and theoretical K curves may suggest spatial clustering or spatial regularity.

This routine Kest estimates the K function of a stationary point process, given observation of the process inside a known, bounded window. The argument X is interpreted as a point pattern object (of class "ppp", see ppp.object) and can be supplied in any of the formats recognised by as.ppp().

The estimation of K is hampered by edge effects arising from the unobservability of points of the random pattern outside the window. An edge correction is needed to reduce bias (Baddeley, 1998; Ripley, 1988). The corrections implemented here are

border

the border method or “reduced sample” estimator (see Ripley, 1988). This is the least efficient (statistically) and the fastest to compute. It can be computed for a window of arbitrary shape.

isotropic/Ripley

Ripley's isotropic correction (see Ripley, 1988; Ohser, 1983). This is implemented for rectangular and polygonal windows (not for binary masks).

translate/translation

Translation correction (Ohser, 1983). Implemented for all window geometries, but slow for complex windows.

rigid

Rigid motion correction (Ohser and Stoyan, 1981). Implemented for all window geometries, but slow for complex windows.

none

Uncorrected estimate. An estimate of the K function without edge correction. (i.e. setting e_{ij} = 1 in the equation below. This estimate is biased and should not be used for data analysis, unless you have an extremely large point pattern (more than 100,000 points).

periodic

Periodic (toroidal) edge correction. Defined only for rectangular windows.

best

Selects the best edge correction that is available for the geometry of the window. Currently this is Ripley's isotropic correction for a rectangular or polygonal window, and the translation correction for masks.

good

Selects the best edge correction that can be computed in a reasonable time. This is the same as "best" for datasets with fewer than 3000 points; otherwise the selected edge correction is "border", unless there are more than 100,000 points, when it is "none".

The estimates of K(r) are of the form

\hat K(r) = \frac a {n (n-1) } \sum_i \sum_j I(d_{ij}\le r) e_{ij}

where a is the area of the window, n is the number of data points, and the sum is taken over all ordered pairs of points i and j in X. Here d_{ij} is the distance between the two points, and I(d_{ij} \le r) is the indicator that equals 1 if the distance is less than or equal to r. The term e_{ij} is the edge correction weight (which depends on the choice of edge correction listed above).

Note that this estimator assumes the process is stationary (spatially homogeneous). For inhomogeneous point patterns, see Kinhom.

If the point pattern X contains more than about 3000 points, the isotropic and translation edge corrections can be computationally prohibitive. The computations for the border method are much faster, and are statistically efficient when there are large numbers of points. Accordingly, if the number of points in X exceeds the threshold nlarge, then only the border correction will be computed. Setting nlarge=Inf or correction="best" will prevent this from happening. Setting nlarge=0 is equivalent to selecting only the border correction with correction="border".

If X contains more than about 100,000 points, even the border correction is time-consuming. You may want to consider setting correction="none" in this case. There is an even faster algorithm for the uncorrected estimate.

Approximations to the variance of \hat K(r) are available, for the case of the isotropic edge correction estimator, assuming complete spatial randomness (Ripley, 1988; Lotwick and Silverman, 1982; Diggle, 2003, pp 51-53). If var.approx=TRUE, then the result of Kest also has a column named rip giving values of Ripley's (1988) approximation to \mbox{var}(\hat K(r)), and (if the window is a rectangle) a column named ls giving values of Lotwick and Silverman's (1982) approximation.

If the argument domain is given, the calculations will be restricted to a subset of the data. In the formula for K(r) above, the first point i will be restricted to lie inside domain. The result is an approximately unbiased estimate of K(r) based on pairs of points in which the first point lies inside domain and the second point is unrestricted. This is useful in bootstrap techniques. The argument domain should be a window (object of class "owin") or something acceptable to as.owin. It must be a subset of the window of the point pattern X.

The estimator Kest ignores marks. Its counterparts for multitype point patterns are Kcross, Kdot, and for general marked point patterns see Kmulti.

Some writers, particularly Stoyan (1994, 1995) advocate the use of the “pair correlation function”

g(r) = \frac{K'(r)}{2\pi r}

where K'(r) is the derivative of K(r). See pcf on how to estimate this function.

Value

An object of class "fv", see fv.object, which can be plotted directly using plot.fv.

Essentially a data frame containing columns

together with columns named "border", "bord.modif", "iso" and/or "trans", according to the selected edge corrections. These columns contain estimates of the function K(r) obtained by the edge corrections named.

If var.approx=TRUE then the return value also has columns rip and ls containing approximations to the variance of \hat K(r) under CSR.

If ratio=TRUE then the return value also has two attributes called "numerator" and "denominator" which are "fv" objects containing the numerators and denominators of each estimate of K(r).

Envelopes, significance bands and confidence intervals

To compute simulation envelopes for the K-function under CSR, use envelope.

To compute a confidence interval for the true K-function, use varblock or lohboot.

Warnings

The estimator of K(r) is approximately unbiased for each fixed r, for point processes which do not have very strong interaction. (For point processes with a strong clustering interaction, the estimator is negatively biased; for point processes with a strong inhibitive interaction, the estimator is positively biased.)

Bias increases with r and depends on the window geometry. For a rectangular window it is prudent to restrict the r values to a maximum of 1/4 of the smaller side length of the rectangle (Ripley, 1977, 1988; Diggle, 1983). Bias may become appreciable for point patterns consisting of fewer than 15 points.

While K(r) is always a non-decreasing function, the estimator of K is not guaranteed to be non-decreasing. This is rarely a problem in practice, except for the border correction estimators when the number of points is small.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

References

Baddeley, A.J. Spatial sampling and censoring. In O.E. Barndorff-Nielsen, W.S. Kendall and M.N.M. van Lieshout (eds) Stochastic Geometry: Likelihood and Computation. Chapman and Hall, 1998. Chapter 2, pages 37–78.

Cressie, N.A.C. Statistics for spatial data. John Wiley and Sons, 1991.

Diggle, P.J. Statistical analysis of spatial point patterns. Academic Press, 1983.

Ohser, J. (1983) On estimators for the reduced second moment measure of point processes. Mathematische Operationsforschung und Statistik, series Statistics, 14, 63 – 71.

Ohser, J. and Stoyan, D. (1981) On the second-order and orientation analysis of planar stationary point processes. Biometrical Journal 23, 523–533.

Ripley, B.D. (1977) Modelling spatial patterns (with discussion). Journal of the Royal Statistical Society, Series B, 39, 172 – 212.

Ripley, B.D. Statistical inference for spatial processes. Cambridge University Press, 1988.

Stoyan, D, Kendall, W.S. and Mecke, J. (1995) Stochastic geometry and its applications. 2nd edition. Springer Verlag.

Stoyan, D. and Stoyan, H. (1994) Fractals, random shapes and point fields: methods of geometrical statistics. John Wiley and Sons.

See Also

localK to extract individual summands in the K function.

pcf for the pair correlation.

Fest, Gest, Jest for alternative summary functions.

Kcross, Kdot, Kinhom, Kmulti for counterparts of the K function for multitype point patterns.

reduced.sample for the calculation of reduced sample estimators.

Examples

 X <- runifpoint(50)
 K <- Kest(X)
 K <- Kest(cells, correction="isotropic")
 plot(K)
 plot(K, main="K function for cells")
 # plot the L function
 plot(K, sqrt(iso/pi) ~ r)
 plot(K, sqrt(./pi) ~ r, ylab="L(r)", main="L function for cells")

K-function using FFT

Description

Estimates the reduced second moment function K(r) from a point pattern in a window of arbitrary shape, using the Fast Fourier Transform.

Usage

  Kest.fft(X, sigma, r=NULL, ..., breaks=NULL)

Arguments

Details

This is an alternative to the function Kest for estimating the K function. It may be useful for very large patterns of points.

Whereas Kest computes the distance between each pair of points analytically, this function discretises the point pattern onto a rectangular pixel raster and applies Fast Fourier Transform techniques to estimate K(t). The hard work is done by the function Kmeasure.

The result is an approximation whose accuracy depends on the resolution of the pixel raster. The resolution is controlled by the arguments ..., or by setting the parameter npixel in spatstat.options.

Value

An object of class "fv" (see fv.object).

Essentially a data frame containing columns

Author(s)

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

References

Cressie, N.A.C. Statistics for spatial data. John Wiley and Sons, 1991.

Diggle, P.J. Statistical analysis of spatial point patterns. Academic Press, 1983.

Ohser, J. (1983) On estimators for the reduced second moment measure of point processes. Mathematische Operationsforschung und Statistik, series Statistics, 14, 63 – 71.

Ripley, B.D. Statistical inference for spatial processes. Cambridge University Press, 1988.

Stoyan, D, Kendall, W.S. and Mecke, J. (1995) Stochastic geometry and its applications. 2nd edition. Springer Verlag.

Stoyan, D. and Stoyan, H. (1994) Fractals, random shapes and point fields: methods of geometrical statistics. John Wiley and Sons.

See Also

Kest, Kmeasure, spatstat.options

Examples

 pp <- runifpoint(10000)
 
 Kpp <- Kest.fft(pp, 0.01)
 plot(Kpp)
 

Inhomogeneous K-function

Description

Estimates the inhomogeneous K function of a non-stationary point pattern.

Usage

  Kinhom(X, lambda=NULL, ..., r = NULL, breaks = NULL,
    correction=c("border", "bord.modif", "isotropic", "translate"),
    renormalise=TRUE,
    normpower=1,
    update=TRUE,
    leaveoneout=TRUE,
    nlarge = 1000,
    lambda2=NULL, reciplambda=NULL, reciplambda2=NULL,
    diagonal=TRUE,
    sigma=NULL, varcov=NULL,
    ratio=FALSE)

Arguments

Details

This computes a generalisation of the K function for inhomogeneous point patterns, proposed by Baddeley, Moller and Waagepetersen (2000).

The “ordinary” K function (variously known as the reduced second order moment function and Ripley's K function), is described under Kest. It is defined only for stationary point processes.

The inhomogeneous K function K_{\mbox{\scriptsize\rm inhom}}(r) is a direct generalisation to nonstationary point processes. Suppose x is a point process with non-constant intensity \lambda(u) at each location u. Define K_{\mbox{\scriptsize\rm inhom}}(r) to be the expected value, given that u is a point of x, of the sum of all terms 1/\lambda(x_j) over all points x_j in the process separated from u by a distance less than r. This reduces to the ordinary K function if \lambda() is constant. If x is an inhomogeneous Poisson process with intensity function \lambda(u), then K_{\mbox{\scriptsize\rm inhom}}(r) = \pi r^2.

Given a point pattern dataset, the inhomogeneous K function can be estimated essentially by summing the values 1/(\lambda(x_i)\lambda(x_j)) for all pairs of points x_i, x_j separated by a distance less than r.

This allows us to inspect a point pattern for evidence of interpoint interactions after allowing for spatial inhomogeneity of the pattern. Values K_{\mbox{\scriptsize\rm inhom}}(r) > \pi r^2 are suggestive of clustering.

The argument lambda should supply the (estimated) values of the intensity function \lambda. It may be either

a numeric vector

containing the values of the intensity function at the points of the pattern X.

a pixel image

(object of class "im") assumed to contain the values of the intensity function at all locations in the window.

a fitted point process model

(object of class "ppm", "kppm" or "dppm") whose fitted trend can be used as the fitted intensity. (If update=TRUE the model will first be refitted to the data X before the trend is computed.)

a function

which can be evaluated to give values of the intensity at any locations.

omitted:

if lambda is omitted, then it will be estimated using a ‘leave-one-out’ kernel smoother.

If lambda is a numeric vector, then its length should be equal to the number of points in the pattern X. The value lambda[i] is assumed to be the the (estimated) value of the intensity \lambda(x_i) for the point x_i of the pattern X. Each value must be a positive number; NA's are not allowed.

If lambda is a pixel image, the domain of the image should cover the entire window of the point pattern. If it does not (which may occur near the boundary because of discretisation error), then the missing pixel values will be obtained by applying a Gaussian blur to lambda using blur, then looking up the values of this blurred image for the missing locations. (A warning will be issued in this case.)

If lambda is a function, then it will be evaluated in the form lambda(x,y) where x and y are vectors of coordinates of the points of X. It should return a numeric vector with length equal to the number of points in X.

If lambda is omitted, then it will be estimated using a ‘leave-one-out’ kernel smoother, as described in Baddeley, Moller and Waagepetersen (2000). The estimate lambda[i] for the point X[i] is computed by removing X[i] from the point pattern, applying kernel smoothing to the remaining points using density.ppp, and evaluating the smoothed intensity at the point X[i]. The smoothing kernel bandwidth is controlled by the arguments sigma and varcov, which are passed to density.ppp along with any extra arguments.

Edge corrections are used to correct bias in the estimation of K_{\mbox{\scriptsize\rm inhom}}. Each edge-corrected estimate of K_{\mbox{\scriptsize\rm inhom}}(r) is of the form

\widehat K_{\mbox{\scriptsize\rm inhom}}(r) = (1/A) \sum_i \sum_j \frac{1\{d_{ij} \le r\} e(x_i,x_j,r)}{\lambda(x_i)\lambda(x_j)}

where A is a constant denominator, d_{ij} is the distance between points x_i and x_j, and e(x_i,x_j,r) is an edge correction factor. For the ‘border’ correction,