tessdev: Calculate tessellation deviance residuals

Description

tessdev divides the space-time window into cells using a Voronoi tessellation and calculates the deviance residuals within each cell between two competing conditional intensity models.

Usage

tessdev(X, cifunction1, cifunction2, theta1 = NULL, theta2 = NULL, 
lambda1 = NULL, lambda2 = NULL, algthm1 = c("mc", "miser", "none"), 
algthm2 = c("mc", "miser", "none"), n = 100, n1.miser = 10000, 
n2.miser = 10000, ints1 = NULL, ints2 = NULL)

Arguments

A stpp object.

cifunction1

A function returning estimates of the conditional intensity at all points in X, according to model 1 (cifunction1). The function should take arguments X and an optional vector of parameters theta1.

cifunction2

A function returning estimates of the conditional intensity at all points in X, according to model 2 (cifunction2) which should be different than model 1 (cifunction1). The function should take arguments X

theta1

Optional: A vector of parameters to be passed to cifunction1.

theta2

Optional: A vector of parameters to be passed to cifunction2.

lambda1

Optional: A vector of conditional intensities based on cifunction1 at each point in X.

lambda2

Optional: A vector of conditional intensities based on cifunction2 at each point in X.

algthm1

The algorithm used for estimating the integrals in each cell for model 1. The three algorithms are mc, miser, and none

algthm2

The algorithm used for estimating the integrals in each cell for model 2. The three algorithms are mc, miser, and none

Initial number of sample points in each cell for approximating integrals. The number of sample points are iteratively increased by n until some accuracy threshold is reached.

n1.miser

The total number of sample points for estimating all integrals for model 1 if the miser algorithm is selected.

n2.miser

The total number of sample points for estimating all integrals for model 2 if the miser algorithm is selected.

ints1

An optional vector of integrals for model 1. Must be the same length as the number of tessellation cells, and each element of ints1 should correspond to each cell in the tile.list that is returned using the deldir fu

ints2

An optional vector of integrals for model 2. Must be the same length as the number of tessellation cells, and each element of ints2 should correspond to each cell in the tile.list that is returned using the deldir fu

Value

Prints to the screen the number of simulated points used to approximate the integrals.
Outputs an object of class tessdev, which is a list of
XAn object of class stpp.
tile.listAn object of class tile.list.
residualsA vector of tessellation deviance residuals. The order of the residuals corresponds with the order of the cells (tiles) in tile.list.
If algthm = mc, then a list of the following elements are also included for each model that uses the mc algorithm:
nVector of the total number of points used for approximating integrals.
integralVector of actual integral approximations in each grid cell.
mean.lambdaVector of the approximate final mean of lambda in each grid cell.
sd.lambdaVector of the approximate standard deviation of lambda in each grid cell.
If the miser algorithm is selected, then a list of the following elements are also included for each model that uses the miser algorithm:
nTotal number of points used for approximating integrals.
integralVector of actual integral approximations in each grid cell.
mean.lambdaVector of the approximate final mean of lambda in each grid cell.
sd.lambdaVector of the approximate standard deviation of lambda in each grid cell.
app.ptsA data frame of the x,y, and t coordinates of a sample of 10,000 of the sampled points for integral approximation, along with the value of lambda (l).

Details

The tessellation deviance residuals are the differences in the tessellation residuals of model 1 vs. model 2 within each Voronoi tessellation cell, denoted here as $V_{i}$. The tessellation deviance residual is given by

$$R_{TD}(V_{i}) = \left(1 - \int_{V_{i}}\hat{\lambda}_{1}(x)dx\right)/\sqrt{\int_{V_{i}}\hat{\lambda}_{1}(x)dx}-\left(1 - \int_{V_{i}}\hat{\lambda}_{2}(x)dx\right)/\sqrt{\int_{V_{i}}\hat{\lambda}_{2}(x)dx},$$ where $\hat{\lambda}(x)$ is the fitted conditional intensity model.

The conditional intensity functions, cifunction1 and cifunction2, should take X as their first argument, and an optional theta as their second argument, and return a vector of conditional intensity estimates with length equal to the number of points in X, i.e. the length of X$x. Both cifunction1 and cifunction2 are required. lambda1 and lambda2 are optional, and if passed will eliminate the need for devresid to calculate the conditional intensities at each observed point in X.

The integrals in $R_{TD}(V_{i})$ are approximated using one of two algorithms: a simple Monte Carlo (mc) algorithm, or the MISER algorithm. The simple Monte Carlo iteratively adds n sample points to each tessellation cell to approximate the integral, and the iteration stops when some threshold in the accuracy of the approximation is reached. The MISER algorithm samples a total number of n.miser points in a recursive way, sampling the points in locations that have the highest variance. This part can be very slow and the approximations can be very inaccurate. For highest accuracy these algorithms will require a very large n or n.miser depending on the complexity of the conditional intensity functions (some might say ~1 billion sample points are needed for a good approximation).

Passing the arguments ints1 and/or ints2 eliminates the need for approximating the integrals using either of the two algorithms here. However, the tile.list must first be obtained in order to assure that each element of ints1 and/or ints2 corresponds to the correct cell. The tile.list can be obtained, either by using the deldir function separately, or by using tessresid with one of the included algorithms first (the tile.list is returned along with the residuals). tessresid can then be called again with ints1 and/or ints2 included and algthm = none.

Note that if miser is selected, and if the points in the point pattern are very densely clustered, the integral in some cells may end up being approximated based on only the observed point in the point pattern that is contained in that cell. This happens because the cells in these clusters of points will be very small, and so it may be likely that sampled points based on the MISER algorithm will miss these cells entirely. For this reason, the simple Monte Carlo algorithm might be preferred.

Examples

Run this code

#===> load simulated data <===#
data(simdata)
X <- stpp(simdata$x, simdata$y, simdata$t)

#===> define two conditional intensity functions <===#
ci1 <- function(X, theta){theta*exp(-2*X$x - 2*X$y - 2*X$t)} #correct model

ci2 <- function(X, theta = NULL){rep(250, length(X$x))} #homogeneous Poisson model

deviance <- tessdev(X, ci1, ci2, theta1 = 3000)
#===> plot results <===#
plot(deviance)