lurking: Lurking Variable Plot

In spatstat.core: Core Functionality of the 'spatstat' Family

Lurking Variable Plot

Description

Plot spatial point process residuals against a covariate

Usage

lurking(object, ...)

## S3 method for class 'ppm'
lurking(object, covariate,
                    type="eem",
                    cumulative=TRUE,
                    ...,
                    plot.it = TRUE,
                    plot.sd = is.poisson(object),
                    clipwindow=default.clipwindow(object),
                    rv = NULL,
                    envelope=FALSE, nsim=39, nrank=1,
                    typename,
                    covname,
                    oldstyle=FALSE,
                    check=TRUE,
                    verbose=TRUE,
                    nx=128,
                    splineargs=list(spar=0.5),
                    internal=NULL) 

## S3 method for class 'ppp'
lurking(object, covariate,
                    type="eem",
                    cumulative=TRUE,
                    ...,
                    plot.it = TRUE,
                    plot.sd = is.poisson(object),
                    clipwindow=default.clipwindow(object),
                    rv = NULL,
                    envelope=FALSE, nsim=39, nrank=1,
                    typename,
                    covname,
                    oldstyle=FALSE,
                    check=TRUE,
                    verbose=TRUE,
                    nx=128,
                    splineargs=list(spar=0.5),
                    internal=NULL) 

Arguments

object	The fitted point process model (an object of class "ppm") for which diagnostics should be produced. This object is usually obtained from ppm. Alternatively, object may be a point pattern (object of class "ppp").
covariate	The covariate against which residuals should be plotted. Either a numeric vector, a pixel image, or an expression. See Details below.
type	String indicating the type of residuals or weights to be computed. Choices include "eem", "raw", "inverse" and "pearson". See diagnose.ppm for all possible choices.
cumulative	Logical flag indicating whether to plot a cumulative sum of marks (cumulative=TRUE) or the derivative of this sum, a marginal density of the smoothed residual field (cumulative=FALSE).
...	Arguments passed to plot.default and lines to control the plot behaviour.
plot.it	Logical value indicating whether plots should be shown. If plot.it=FALSE, only the computed coordinates for the plots are returned. See Value.
plot.sd	Logical value indicating whether error bounds should be added to plot. The default is TRUE for Poisson models and FALSE for non-Poisson models. See Details.
clipwindow	If not NULL this argument indicates that residuals shall only be computed inside a subregion of the window containing the original point pattern data. Then clipwindow should be a window object of class "owin".
rv	Usually absent. If this argument is present, the point process residuals will not be calculated from the fitted model object, but will instead be taken directly from rv.
envelope	Logical value indicating whether to compute simulation envelopes for the plot. Alternatively envelope may be a list of point patterns to use for computing the simulation envelopes, or an object of class "envelope" containing simulated point patterns.
nsim	Number of simulated point patterns to be generated to produce the simulation envelope, if envelope=TRUE.
nrank	Integer. Rank of the envelope value amongst the nsim simulated values. A rank of 1 means that the minimum and maximum simulated values will be used.
typename	Usually absent. If this argument is present, it should be a string, and will be used (in the axis labels of plots) to describe the type of residuals.
covname	A string name for the covariate, to be used in axis labels of plots.
oldstyle	Logical flag indicating whether error bounds should be plotted using the approximation given in the original paper (oldstyle=TRUE), or using the correct asymptotic formula (oldstyle=FALSE).
check	Logical flag indicating whether the integrity of the data structure in object should be checked.
verbose	Logical value indicating whether to print progress reports during Monte Carlo simulation.
nx	Integer. Number of covariate values to be used in the plot.
splineargs	A list of arguments passed to smooth.spline for the estimation of the derivatives in the case cumulative=FALSE.
internal	Internal use only.

Details

This function generates a ‘lurking variable’ plot for a fitted point process model. Residuals from the model represented by object are plotted against the covariate specified by covariate. This plot can be used to reveal departures from the fitted model, in particular, to reveal that the point pattern depends on the covariate.

The function lurking is generic, with methods for ppm and ppp documented here, and possibly other methods.

The argument object would usually be a fitted point process model (object of class "ppm") produced by the model-fitting algorithm ppm). If object is a point pattern (object of class "ppp") then the model is taken to be the uniform Poisson process (Complete Spatial Randomness) fitted to this point pattern.

First the residuals from the fitted model (Baddeley et al, 2004) are computed at each quadrature point, or alternatively the ‘exponential energy marks’ (Stoyan and Grabarnik, 1991) are computed at each data point. The argument type selects the type of residual or weight. See diagnose.ppm for options and explanation.

A lurking variable plot for point processes (Baddeley et al, 2004) displays either the cumulative sum of residuals/weights (if cumulative = TRUE) or a kernel-weighted average of the residuals/weights (if cumulative = FALSE) plotted against the covariate. The empirical plot (solid lines) is shown together with its expected value assuming the model is true (dashed lines) and optionally also the pointwise two-standard-deviation limits (grey shading).

To be more precise, let Z(u) denote the value of the covariate at a spatial location u.

• If cumulative=TRUE then we plot H(z) against z, where H(z) is the sum of the residuals over all quadrature points where the covariate takes a value less than or equal to z, or the sum of the exponential energy weights over all data points where the covariate takes a value less than or equal to z.

• If cumulative=FALSE then we plot h(z) against z, where h(z) is the derivative of H(z), computed approximately by spline smoothing.

For the point process residuals E(H(z)) = 0, while for the exponential energy weights E(H(z)) = area of the subset of the window satisfying Z(u) ≤ z.

If the empirical and theoretical curves deviate substantially from one another, the interpretation is that the fitted model does not correctly account for dependence on the covariate. The correct form (of the spatial trend part of the model) may be suggested by the shape of the plot.

If plot.sd = TRUE, then superimposed on the lurking variable plot are the pointwise two-standard-deviation error limits for H(x) calculated for the inhomogeneous Poisson process. The default is plot.sd = TRUE for Poisson models and plot.sd = FALSE for non-Poisson models.

By default, the two-standard-deviation limits are calculated from the exact formula for the asymptotic variance of the residuals under the asymptotic normal approximation, equation (37) of Baddeley et al (2006). However, for compatibility with the original paper of Baddeley et al (2005), if oldstyle=TRUE, the two-standard-deviation limits are calculated using the innovation variance, an over-estimate of the true variance of the residuals.

The argument covariate is either a numeric vector, a pixel image, or an R language expression. If it is a numeric vector, it is assumed to contain the values of the covariate for each of the quadrature points in the fitted model. The quadrature points can be extracted by quad.ppm(object).

If covariate is a pixel image, it is assumed to contain the values of the covariate at each location in the window. The values of this image at the quadrature points will be extracted.

Alternatively, if covariate is an expression, it will be evaluated in the same environment as the model formula used in fitting the model object. It must yield a vector of the same length as the number of quadrature points. The expression may contain the terms x and y representing the cartesian coordinates, and may also contain other variables that were available when the model was fitted. Certain variable names are reserved words; see ppm.

Note that lurking variable plots for the x and y coordinates are also generated by diagnose.ppm, amongst other types of diagnostic plots. This function is more general in that it enables the user to plot the residuals against any chosen covariate that may have been present.

For advanced use, even the values of the residuals/weights can be altered. If the argument rv is present, the residuals will not be calculated from the fitted model object but will instead be taken directly from the object rv. If type = "eem" then rv should be similar to the return value of eem, namely, a numeric vector with length equal to the number of data points in the original point pattern. Otherwise, rv should be similar to the return value of residuals.ppm, that is, rv should be an object of class "msr" (see msr) representing a signed measure.

Value

The (invisible) return value is an object belonging to the class "lurk", for which there are methods for plot and print.

This object is a list containing two dataframes empirical and theoretical. The first dataframe empirical contains columns covariate and value giving the coordinates of the lurking variable plot. The second dataframe theoretical contains columns covariate, mean and sd giving the coordinates of the plot of the theoretical mean and standard deviation.

Author(s)

\adrian

and \rolf.

References

Baddeley, A., Turner, R., \Moller, J. and Hazelton, M. (2005) Residual analysis for spatial point processes. Journal of the Royal Statistical Society, Series B 67, 617–666.

Baddeley, A., \Moller, J. and Pakes, A.G. (2006) Properties of residuals for spatial point processes. Annals of the Institute of Statistical Mathematics 60, 627–649.

Stoyan, D. and Grabarnik, P. (1991) Second-order characteristics for stochastic structures connected with Gibbs point processes. Mathematische Nachrichten, 151:95–100.

See Also

residuals.ppm, diagnose.ppm, residuals.ppm, qqplot.ppm, eem, ppm

Examples

  (a <- lurking(nztrees, expression(x), type="raw"))
  fit <- ppm(nztrees ~x, Poisson(), nd=128)
  (b <- lurking(fit, expression(x), type="raw"))
  lurking(fit, expression(x), type="raw", cumulative=FALSE)

spatstat.core documentation built on May 18, 2022, 9:05 a.m.