twinstim_epitest: Permutation Test for Space-Time Interaction in '"twinstim"'

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

Permutation Test for Space-Time Interaction in "twinstim"

Description

The function epitest takes a "twinstim" model and tests if the spatio-temporal interaction invoked by the epidemic model component is statistically significant. The test only works for simple epidemic models, where epidemic = ~1 (no additional parameters for event-specific infectivity), and requires the non-canonical epilink="identity" (see twinstim). A permutation test is performed by default, which is only valid if the endemic intensity is space-time separable. The approach is described in detail in Meyer et al. (2016), where it is also compared to alternative global tests for clustering such as the knox test.

Usage

epitest(model, data, tiles, method = "time", B = 199,
        eps.s = NULL, eps.t = NULL, fixed = NULL,
        verbose = TRUE, compress = FALSE, ...)

## S3 method for class 'epitest'
coef(object, which = c("m1", "m0"), ...)
## S3 method for class 'epitest'
plot(x, teststat = c("simpleR0", "D"), ...)

Arguments

model	a simple epidemic "twinstim" with epidemic = ~1, fitted using the non-canonical epilink="identity". Note that the permutation test is only valid for models with a space-time separable endemic intensity, where covariates vary either in space or time but not both.
data	an object of class "epidataCS", the data to which the model was fitted.
tiles	(only used by method = "simulate") a "\linkSPclass{SpatialPolygons}" representation of the tiles in data$stgrid.
method	one of the following character strings specifying the test method: "LRT": a simple likelihood ratio test of the epidemic model against the corresponding endemic-only model, "time"/"space": a Monte Carlo permutation test where the null distribution is obtained by relabeling time points or locations, respectively (using permute.epidataCS). "simulate": obtain the null distribution of the test statistic by simulations from the endemic-only model (using simEndemicEvents).
B	the number of permutations for the Monte Carlo approach. The default number is rather low; if computationally feasible, B = 999 is more appropriate. Note that this determines the “resolution” of the p-value: the smallest attainable p-value is 1/(B+1).
eps.s, eps.t	arguments for simpleR0.
fixed	optional character vector naming parameters to fix at their original value when re-fitting the model on permuted data. The special value fixed = TRUE means to fix all epidemic parameters but the intercept.
verbose	the amount of tracing in the range 0:3. Set to 0 (or FALSE) for no output, 1 (or TRUE, the default) for a progress bar, 2 for the test statistics resulting from each permutation, and to 3 for additional tracing of the log-likelihood maximization in each permutation (not useful if parallelized). Tracing does not work if permutations are parallelized using clusters. See plapply for other choices.
compress	logical indicating if the nobs-dependent elements "fitted", "fittedComponents", and "R0" should be dropped from the permutation-based model fits. Not keeping these elements saves a lot of memory especially with a large number of events. Note, however, that the returned permfits then no longer are fully valid "twinstim" objects (but most methods will still work).
...	further arguments for plapply to configure parallel operation, i.e., .parallel as well as .seed to make the results reproducible. For the plot-method, further arguments passed to truehist. Ignored by the coef-method.
object, x	an object of class "epitest" as returned by epitest.
which	a character string indicating either the full ("m1", default) or the endemic-only ("m0") model.
teststat	a character string determining the test statistic to plot, either "simpleR0" or "D" (twice the log-likelihood difference of the models).

Details

This space-time interaction test is limited to models with epidemic = ~1, since covariate effects are not identifiable under the null hypothesis of no space-time interaction. Estimating a rich epidemic model based on permuted data will most likely result in singular convergence. A similar issue might arise when the model employs parametric interaction functions, in which case fixed=TRUE can be used. For further details see Meyer et al. (2016).

The test statistic is the reproduction number simpleR0. A likelihood ratio test of the supplied epidemic model against the corresponding endemic-only model is also available. By default, the null distribution of the test statistic under no space-time interaction is obtained by a Monte Carlo permutation approach (via permute.epidataCS) and therefore relies on a space-time separable endemic model component.

The plot-method shows a truehist of the simulated null distribution together with the observed value. The coef-method extracts the parameter estimates from the B permfits (by default for the full model which = "m1").

Value

a list (inheriting from "htest") with the following components:

method	a character string indicating the type of test performed.
data.name	a character string giving the supplied data and model arguments.
statistic	the observed test statistic.
parameter	the (effective) number of permutations used to calculate the p-value (only those with convergent fits are used).
p.value	the p-value for the test. For the methods involving resampling under the null (method != "LRT"), it is based on the subset of convergent fits only and the p-value from the simple LRT is attached as an attribute "LRT".

In addition, if method != "LRT", the result will have the following elements:

permfits	the list of model fits (endemic-only and epidemic) from the B permutations.
permstats	a data frame with B rows and the columns "l0" (log-likelihood of the endemic-only model m0), "l1" (log-likelihood of the epidemic model m1), "D" (twice their difference), "simpleR0" (the results of simpleR0(m1, eps.s, eps.t)), and "converged" (a boolean indicator if both models converged).

The plot-method invisibly returns NULL. The coef-method returns the B x length(coef(model)) matrix of parameter estimates.

Author(s)

Sebastian Meyer

References

Meyer, S., Warnke, I., Rössler, W. and Held, L. (2016): Model-based testing for space-time interaction using point processes: An application to psychiatric hospital admissions in an urban area. Spatial and Spatio-temporal Epidemiology, 17, 15-25. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.sste.2016.03.002")}. Eprint: https://arxiv.org/abs/1512.09052.

See Also

permute.epidataCS, knox

Examples

data("imdepi", "imdepifit")

## test for space-time interaction of the B-cases
## assuming spatial interaction to be constant within 50 km
imdepiB50 <- update(subset(imdepi, type == "B"), eps.s = 50)
imdfitB50 <- update(imdepifit, data = imdepiB50, subset = NULL,
                    epidemic = ~1, epilink = "identity", siaf = NULL,
                    start = c("e.(Intercept)" = 0))

## simple likelihood ratio test
epitest(imdfitB50, imdepiB50, method = "LRT")

## permutation test
et <- epitest(imdfitB50, imdepiB50,
              B = 5,        # CAVE: limited here for speed
              verbose = 2,  # (tracing does not work on Windows
              .seed = 1, .parallel = 1)       # if parallelized)
et
plot(et)

## summary of parameter estimates under permutation
summary(coef(et, which = "m1"))

surveillance documentation built on Nov. 4, 2024, 3 a.m.