# Permutation Test for Space-Time Interaction in `"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.

## 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`"SpatialPolygons"`

representation of the`tile`

s 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).

## 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

`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"`

.

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.

## 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"`

).

## 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.
doi:10.1016/j.sste.2016.03.002
.
Eprint: https://arxiv.org/abs/1512.09052.

## 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"))
```