rrstmix {spagmix}

Spatiotemporal relative risk surface generation

Description

Generates an appropriately scaled spatiotemporal (trivariate) relative risk surface using a supplied control density and N Gaussian-style hotspots.

Usage

rrstmix(g, rhotspots, rsds, rweights, rbase = 1, log = TRUE,
        tlim = NULL, tres = NULL)

Arguments

g

The control density as a stim, stden, or im object; this will be internally rescaled to integrate to 1 if it does not already do so. When a stim or stden object, the resolution and domain of the final result will be the same as this. When this argument is passed an object of class im, the function assumes a static (unchanging) control density over time (see Fernando and Hazelton, 2014), and the user must additionally specify tlim and tres.

rhotspots

A 3 \times N matrix specifying the spatiotemporal coordinates of the N peaks and troughs in the relative risk density. The three entries down each column will be respectively interpreted as x-coord., y-coord., and time-coordinate of each Gaussian bump.

rsds

A 3 \times N strictly positive numeric matrix specifying the standard deviations along each axis of each of the N bumps, the ordering of the components in each column is the same as rhotspots.

rweights

A vector of length N giving relative weightings for each peak (positive weight) or trough (negative).

rbase

The base level of the relative risk surface (default is 1). The peaks and troughs will be added or subtracted from this base level prior to normalisation.

log

A logical value. If TRUE (default), the relative risk surface is returned logged.

tlim

Only used if g is a pixel image object. A vector of length 2 giving the boundaries of the time interval on which the relative risk surface will be defined.

tres

Only used if g is a pixel image object. The resolution along the temporal axis of the final result.

Details

This function is the spatiotemporal (trivariate) equivalent of rrmix. See ‘Details’ in the documentation for that function for more information.

Value

An oject of class rrstim. This is a list with the following components:

f

An object of class stim giving the case density.

g

A copy of the object passed to the argument g, possibly renormalised to integrate to 1 if this was necessary. If g was originally an im, this will be converted to an object of class stim.

r

An object of class stim giving the (log) relative risk surface.

Author(s)

A.K. Redmond and T.M. Davies

References

Fernando, W.T.P.S. and Hazelton, M.L. (2014), Generalizing the spatial relative risk function, Spatial and Spatio-temporal Epidemiology, 8, 1-10.

Examples

# time-varying control density
gg1 <- stgmix(mean=matrix(c(2,1,3,0,-1,5),nrow=3),
             vcv=array(c(1,0,0,0,1,0,0,0,1,2,0,0,0,1,0,0,0,2),dim=c(3,3,2)),
             window=shp2,tlim=c(0,6))
rsk1 <- rrstmix(g=gg1,rhotspots=matrix(c(-2,0,2,1,2,5.5),nrow=3),
               rsds=sqrt(cbind(rep(1.5,3),rep(0.25,3))),rweights=c(-0.5,5))
plot(rsk1$g,sleep=0.1,fix.range=TRUE)
plot(rsk1$f,sleep=0.1,fix.range=TRUE)
plot(rsk1$r,sleep=0.1,fix.range=TRUE)

# time-constant control density
set.seed(321)
gg2 <- rgmix(7,window=shp2)
rsk2 <- rrstmix(g=gg2,rhotspots=matrix(c(-1,-1,2,2.5,0,5),nrow=3),
                rsds=sqrt(cbind(rep(0.75,3),c(0.05,0.01,0.5))),
                rweights=c(-0.4,7),tlim=c(0,6),tres=64)
plot(rsk2$g,sleep=0.1,fix.range=TRUE)
plot(rsk2$f,sleep=0.1,fix.range=TRUE)
plot(rsk2$r,sleep=0.1,fix.range=TRUE)