knox: Knox Test for Space-Time Interaction

In jimhester/surveillance: Temporal and Spatio-Temporal Modeling and Monitoring of Epidemic Phenomena

Description

Given temporal and spatial distances as well as corresponding critical thresholds defining what “close” means, the function knox performs Knox (1963, 1964) test for space-time interaction. The corresponding p-value can be calculated either by the Poisson approximation or by a Monte Carlo permutation approach (Mantel, 1967) with support for parallel computation via plapply. There is a simple plot-method showing a truehist of the simulated null distribution together with the expected and observed values.

Usage

knox(dt, ds, eps.t, eps.s, simulate.p.value = TRUE, B = 999, ...)

## S3 method for class 'knox'
plot(x, ...)

Arguments

dt,ds	numeric vectors of length n*(n-1)/2 containing the pairwise temporal and spatial distances of n events. Logical vectors indicating temporal/spatial closeness may also be supplied, in which case eps.t/eps.s is ignored.
eps.t,eps.s	Critical distances defining closeness in time and space, respectively. Distances lower than or equal to the critical distance are considered “"close"”.
simulate.p.value	logical indicating if a Monte Carlo permutation test should be performed (as per default). Do not forget to set the .Random.seed via an extra .seed argument if reproducibility is required (see the ... arguments below). If simulate.p.value = FALSE, the Poisson approximation is used (but see the note below).
B	number of permutations for the Monte Carlo approach.
...	arguments configuring plapply: .parallel, .seed, and .verbose. By default, no parallelization is performed (.parallel = 1), and a progress bar is shown (.verbose = TRUE). For the plot-method, further arguments passed to truehist.
x	an object of class "knox" as returned by the knox test.

Value

an object of class "knox" (inheriting from "htest"), which is a list with the following components:

method	a character string indicating the type of test performed, and whether the Poisson approximation or Monte Carlo simulation was used.
data.name	a character string giving the supplied dt and ds arguments.
statistic	the number of close pairs.
parameter	if simulate.p.value = TRUE, the number B of permutations, otherwise the lambda parameter of the Poisson distribution, i.e., the same as null.value.
p.value	the p-value for the test. In case simulate.p.value = TRUE, the p-value from the Poisson approximation is still attached as an attribute "Poisson".
alternative	the character string "greater" (this is a one-sided test).
null.value	the expected number of close pairs in the absence of space-time interaction.
table	the contingency table of dt <= eps.t and ds <= eps.s.

The plot-method invisibly returns NULL.

Note

The Poisson approximation works well if the proportions of close pairs in both time and space are small (Kulldorf and Hjalmars, 1999), otherwise the Monte Carlo permutation approach is recommended.

Author(s)

Sebastian Meyer

References

Knox, G. (1963): Detection of low intensity epidemicity: application to cleft lip and palate. British Journal of Preventive & Social Medicine, 17, 121-127.

Knox, E. G. (1964): The detection of space-time interactions. Journal of the Royal Statistical Society. Series C (Applied Statistics), 13, 25-30.

Kulldorff, M. and Hjalmars, U. (1999): The Knox method and other tests for space-time interaction. Biometrics, 55, 544-552.

Mantel, N. (1967): The detection of disease clustering and a generalized regression approach. Cancer Research, 27, 209-220.

See Also

the space-time K-function test stKtest to combine information from different scales eps.t and eps.s while also handling edge effects, as well as function epitest for testing "twinstim" models.

Examples

data("imdepi")
imdepiB <- subset(imdepi, type == "B")

## Obtain the p-value via a Monte Carlo permutation test,
## where the permutations can be computed in parallel
## (using forking on Unix-alikes and a cluster on Windows, see ?plapply)
knoxtest <- knox(
    dt = dist(imdepiB$events$time), eps.t = 30,
    ds = dist(coordinates(imdepiB$events)), eps.s = 50,
    simulate.p.value = TRUE, B = 199,
    .parallel = 2, .seed = 1, .verbose = FALSE
)
knoxtest
plot(knoxtest)

jimhester/surveillance documentation built on May 19, 2019, 10:33 a.m.