pcfinhom: Inhomogeneous Pair Correlation Function

In spatstat.explore: Exploratory Data Analysis for the 'spatstat' Family

Inhomogeneous Pair Correlation Function

Description

Estimates the inhomogeneous pair correlation function of a point pattern using kernel methods.

Usage

pcfinhom(X, lambda = NULL, ...,
            r = NULL, adaptive = FALSE,
            kernel = "epanechnikov", bw = NULL, h = NULL,
            bw.args = list(), stoyan = 0.15, adjust = 1,
            correction = c("translate", "Ripley"),
            divisor = c("r", "d", "a", "t"),
            zerocor=c("weighted", "reflection", "convolution",
                      "bdrykern", "JonesFoster", "none"),
            renormalise = TRUE, normpower = 1,
            update = TRUE, leaveoneout = TRUE,
            reciplambda = NULL, sigma = NULL, adjust.sigma = 1, varcov = NULL,
            gref = NULL, tau = 0, fast = TRUE, var.approx = FALSE,
            domain = NULL, ratio = FALSE, close = NULL)

Arguments

X	A point pattern (object of class "ppp").
lambda	Optional. Values of the estimated intensity function. Either a vector giving the intensity values at the points of the pattern X, a pixel image (object of class "im") giving the intensity values at all locations, a fitted point process model (object of class "ppm", "kppm" or "dppm") or a function(x,y) which can be evaluated to give the intensity value at any location.
...	Arguments passed to density.default or to densityBC controlling the kernel smoothing.
r	Vector of values for the argument r at which g(r) should be evaluated. There is a sensible default.
adaptive	Logical value specifying whether to use adaptive kernel smoothing (adaptive=TRUE) or fixed-bandwidth kernel smoothing (adaptive=FALSE, the default).
kernel	Choice of smoothing kernel, passed to density.default.
bw	Bandwidth for smoothing kernel. Either a single numeric value giving the standard deviation of the kernel, or a character string specifying a bandwidth selection rule, or a function that computes the selected bandwidth. See Details.
h	Kernel halfwidth h (incompatible with argument bw). A numerical value. The parameter h is defined as the half-width of the support of the kernel, except for the Gaussian kernel where h is the standard deviation.
bw.args	Optional. List of additional arguments to be passed to bw when bw is a function. Alternatively, bw may be a function that should be applied to X to produce a list of additional arguments.
stoyan	Coefficient for Stoyan's bandwidth selection rule; see Details.
adjust	Numerical adjustment factor for the bandwidth. The bandwidth actually used is adjust * bw. This makes it easy to specify choices like ‘half the selected bandwidth’.
correction	Edge correction. A character vector specifying the choice (or choices) of edge correction. See Details.
divisor	Choice of divisor in the estimation formula: either "r" (the default) or "d", or the new alternatives "a" or "t". See Details.
zerocor	String (partially matched) specifying a correction for the boundary effect bias at r=0. Possible values are "none", "weighted", "convolution", "reflection", "bdrykern" and "JonesFoster". See Details, or help file for densityBC.
renormalise	Logical. Whether to renormalise the estimate. See Details.
normpower	Integer (usually either 1 or 2). Normalisation power. See Details.
update	Logical. If lambda is a fitted model (class "ppm", "kppm" or "dppm") and update=TRUE (the default), the model will first be refitted to the data X (using update.ppm or update.kppm) before the fitted intensity is computed. If update=FALSE, the fitted intensity of the model will be computed without re-fitting it to X.
leaveoneout	Logical value (passed to density.ppp or fitted.ppm) specifying whether to use a leave-one-out rule when calculating the intensity.
reciplambda	Alternative to lambda. Values of the estimated reciprocal 1/\lambda of the intensity function. Either a vector giving the reciprocal intensity values at the points of the pattern X, a pixel image (object of class "im") giving the reciprocal intensity values at all locations, or a function(x,y) which can be evaluated to give the reciprocal intensity value at any location.
sigma, varcov	Optional arguments passed to density.ppp to control the smoothing bandwidth, when lambda is estimated by kernel smoothing.
adjust.sigma	Numeric value. sigma will be multiplied by this value.
gref	Optional. A pair correlation function that will be used as the reference for the transformation to uniformity, when divisor="t". Either a function in the R language giving the pair correlation function, or a fitted model (object of class "kppm", "dppm", "ppm" or "slrm") or a theoretical point process model (object of class "zclustermodel" or "detpointprocfamily") for which the pair correlation function can be computed.
tau	Optional shrinkage coefficient. A single numeric value.
fast	Logical value specifying whether to compute the kernel smoothing using a Fast Fourier Transform algorithm (fast=TRUE) or an exact analytic kernel sum (fast=FALSE).
var.approx	Logical value indicating whether to compute an analytic approximation to the variance of the estimated pair correlation.
domain	Optional. Calculations will be restricted to this subset of the window. See Details.
ratio	Logical. If TRUE, the numerator and denominator of each edge-corrected estimate will also be saved, for use in analysing replicated point patterns.
close	Advanced use only. Precomputed data. See section on Advanced Use.

Details

The inhomogeneous pair correlation function g_{\rm inhom}(r) is a summary of the dependence between points in a spatial point process that does not have a uniform density of points.

The best intuitive interpretation is the following: the probability p(r) of finding two points at locations x and y separated by a distance r is equal to

p(r) = \lambda(x) lambda(y) g(r) \,{\rm d}x \, {\rm d}y

where \lambda is the intensity function of the point process. For a Poisson point process with intensity function \lambda, this probability is p(r) = \lambda(x) \lambda(y) so g_{\rm inhom}(r) = 1.

The inhomogeneous pair correlation function is related to the inhomogeneous K function through

g_{\rm inhom}(r) = \frac{K'_{\rm inhom}(r)}{2\pi r}

where K'_{\rm inhom}(r) is the derivative of K_{\rm inhom}(r), the inhomogeneous K function. See Kinhom for information about K_{\rm inhom}(r).

The command pcfinhom estimates the inhomogeneous pair correlation using a modified version of the algorithm in pcf. In this modified version, the contribution from each pair of points X[i], X[j] is weighted by 1/(\lambda(X[i]) \lambda(X[j])). The arguments divisor, correction and zerocor are interpreted as described in the help file for pcf.

If renormalise=TRUE (the default), then the estimates are multiplied by c^{\mbox{normpower}} where c = \mbox{area}(W)/\sum (1/\lambda(x_i)). This rescaling reduces the variability and bias of the estimate in small samples and in cases of very strong inhomogeneity. The default value of normpower is 1 but the most sensible value is 2, which would correspond to rescaling the lambda values so that \sum (1/\lambda(x_i)) = \mbox{area}(W).

Value

A function value table (object of class "fv"). Essentially a data frame containing the variables

r	the vector of values of the argument r at which the pair correlation function g(r) has been estimated
theo	vector of values equal to 1, the theoretical value of g(r) for the Poisson process
trans	vector of values of g(r) estimated by translation correction
iso	vector of values of g(r) estimated by Ripley isotropic correction
v	vector of approximate values of the variance of the estimate of g(r)

as required.

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 g(r).

The return value also has an attribute "bw" giving the smoothing bandwidth that was used, and an attribute "info" containing details of the algorithm parameters.

Author(s)

\spatstatAuthorsComma

, \martinH and \tilman.

References

\smoothpcfpaper

See Also

pcf, bw.bdh, bw.pcfinhom

Examples

  g <- pcfinhom(japanesepines, divisor="a")

spatstat.explore documentation built on Aug. 8, 2025, 7:36 p.m.