tol.classify: Classification by _p_-value surfaces

In tilmandavies/sparr: Spatial and Spatiotemporal Relative Risk

Classification by p-value surfaces

Description

Classifies observed case/control points according to an estimated p-value surface.

Usage

tol.classify(rs, cutoff = 0.05, pim = NULL, ...)

Arguments

rs	An object of class rrs giving the estimated relative risk function of the case-control points to be classified.
cutoff	A numeric value between 0 and 1, defining the cutoff p-value used to classify points; defaults to 0.05.
pim	A pixel image defining the p-value surface with respect to which the observations are to be classified. Typically the result of a call to tolerance. Ignored if rs possesses a non-NULL P component (which takes precedence).
...	Arguments to be passed to tolerance in order to compute the desired p-value surface in the event neither rs$P nor pim exist. Ignored otherwise.

Details

This function takes in a relative risk surface computed with risk and corresponding p-value surface (the latter used for drawing tolerance contours), and attempts to classify both the case and control points as either falling within or without contours drawn at a level of cutoff. Points that fall 'inside' the contours are deemed to be associated with p-values less than or equal to cutoff and hence are usually interpreted as being in spatial areas of significant risk. This is useful for identifying characteristics of points that fall inside 'pockets of significance' as delineated by tolerance contours.

Upon execution, the function first inspects the rs object to determine whether it possesses a P component (i.e. an internally computed p-value surface provided when risk is called with optional argument tolerate=TRUE). If it exists, this is used. If not, the function then looks to see if the pim argument has been supplied. If it has, it must be a pixel image compatible with the risk surface in rs$rr. If neither rs$P nor pim is present, the function internally calls tolerance with arguments supplied to ... to produce the desired surface.

The return object is a list that splits each of the case and control ppp data objects (these are stored as rs$f$pp and rs$g$pp) in the originally supplied risk surface object) into two constituent ppp objects – one comprising the points inside the cutoff contours (fin and gin), the other for those points outside the cutoff contours (fout and gout). In addition, the index values of the original data objects rs$f$pp and rs$g$pp that correspond to the points in fin and gin are provided as numeric vectors (findex and gindex). These objects are useful if you need to cross-reference data-specific characteristics from some other (corresponding) data set.

Further supplied in the returned list are quantities describing the overall classification structure (pcmask), as well as contour-specific identification and classification (finsplit, ginsplit, pcpolys). The pcpolys object can be plotted to illustrate the unique contour IDs with tol.classplot.

Value

A list of ten components:

fin	Point pattern of 'case' observations classified as being inside the cutoff contours of the p-value surface. An object of class ppp.
fout	Point pattern of 'case' observations falling outside the cutoff contours of the p-value surface. An object of class ppp.
gin	As fin, for the control points.
gout	As fout, for the control points.
findex	Numeric vector giving the raw index values of the original pattern of cases which provide fin.
gindex	As findex, for the controls.
finsplit	A list of the indexes in findex, with separate members splitting up the indexes of case observations as falling inside each unique tolerance contour.
ginsplit	As ginsplit, for the controls.
pcmask	The classification object of class owin. This is a pixel image mask derived from pim and cutoff.
pcpolys	A list of the same length as finsplit and ginsplit, identifying each unique contour as a polygonal owin. The order of these objects in the list correspond to the membership of finsplit and ginsplit. Use tol.classplot on this component to plot the classification indexes.

Author(s)

T. M. Davies

References

Davies, T.M. and Hazelton, M.L. (2010), Adaptive kernel estimation of spatial relative risk, Statistics in Medicine, 29(23) 2423-2437.

Hazelton, M.L. and Davies, T.M. (2009), Inference based on kernel estimates of the relative risk function in geographical epidemiology, Biometrical Journal, 51(1), 98-109.

Kelsall, J.E. and Diggle, P.J. (1995), Kernel estimation of relative risk, Bernoulli, 1, 3-16.

Examples

data(pbc)
pbccas <- split(pbc)$case
pbccon <- split(pbc)$control
h0 <- OS(pbc,nstar="geometric")

pbcrr <- risk(pbccas,pbccon,h0=h0,tolerate=TRUE)
pbcclass <- tol.classify(pbcrr)

## Not run: 
plot(pbcrr)
points(pbcclass$fin,col="red",pch=3,cex=0.5)
points(pbcclass$fout,col="seagreen4",cex=0.5)

chrr <- risk(chorley,h0=0.7,tolerate=TRUE)
chclass <- tol.classify(chrr,cutoff=0.4)
plot(chrr,tol.args=list(levels=0.4))
for(i in 1:length(chclass$finsplit)){
   points(chrr$f$pp[chclass$finsplit[[i]]],col=i,pch=19)
}

## End(Not run)

tilmandavies/sparr documentation built on July 8, 2024, 2:57 p.m.