"twinstim"
twinstim_epitest.Rd
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.
epitest(model, data, tiles, method = "time", B = 199,
eps.s = NULL, eps.t = NULL, fixed = NULL,
verbose = TRUE, compress = FALSE, ...)
# S3 method for epitest
coef(object, which = c("m1", "m0"), ...)
# S3 method for epitest
plot(x, teststat = c("simpleR0", "D"), ...)
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.
an object of class "epidataCS"
, the data
to
which the model
was fitted.
(only used by method = "simulate"
)
a "SpatialPolygons"
representation of the
tile
s in data$stgrid
.
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
).
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)
.
arguments for simpleR0
.
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.
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.
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.
an object of class "epitest"
as returned by epitest
.
a character string indicating either the full ("m1"
, default)
or the endemic-only ("m0"
) model.
a character string determining the test statistic to plot, either
"simpleR0"
or "D"
(twice the log-likelihood
difference of the models).
a list (inheriting from "htest"
) with the following components:
a character string indicating the type of test performed.
a character string giving the supplied data
and
model
arguments.
the observed test statistic.
the (effective) number of permutations used to calculate the p-value (only those with convergent fits are used).
the p-value for the test. For the method
s
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"
.
the list of model fits (endemic-only and epidemic)
from the B
permutations.
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).
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"
).
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. doi: 10.1016/j.sste.2016.03.002 . Eprint: https://arxiv.org/abs/1512.09052.
Sebastian Meyer
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,
epidemic = ~1, epilink = "identity", siaf = NULL,
start = c("e.(Intercept)" = 0))
## simple likelihood ratio test
epitest(imdfitB50, imdepiB50, method = "LRT")
## permutation test (only a few permutations for speed)
et <- epitest(imdfitB50, imdepiB50, B = 3 + 26*surveillance.options("allExamples"),
verbose = 2 * (.Platform$OS.type == "unix"),
.seed = 1, .parallel = 1 + surveillance.options("allExamples"))
et
plot(et)
## evidence against the null hypothesis of no space-time interaction
summary(coef(et, which = "m1"))