epidataCS: Continuous Space-Time Marked Point Patterns with Grid-Based Covariates

Description

Data structure for continuous spatio-temporal event data, e.g. individual case reports of an infectious disease. Apart from the actual events, the class simultaneously holds a spatio-temporal grid of endemic covariates (similar to disease mapping) and a representation of the observation region.

The "epidataCS" class is the basis for fitting spatio-temporal endemic-epidemic intensity models with the function twinstim (Meyer et al., 2012). The implementation is described in Meyer et al. (2016, Section 3), see vignette("twinstim").

Usage

as.epidataCS(events, stgrid, W, qmatrix = diag(nTypes),
             nCircle2Poly = 32L, T = NULL,
             clipper = c("polyclip", "rgeos"), verbose = interactive())
## S3 method for class 'epidataCS':
print(x, n = 6L, digits = getOption("digits"), ...)
## S3 method for class 'epidataCS':
nobs(object, ...)
## S3 method for class 'epidataCS':
head(x, n = 6L, ...)
## S3 method for class 'epidataCS':
tail(x, n = 6L, ...)
## S3 method for class 'epidataCS':
[(x, i, j, ..., drop = TRUE)
## S3 method for class 'epidataCS':
subset(x, subset, select, drop = TRUE, ...)
## S3 method for class 'epidataCS':
marks(x, coords = TRUE, ...)
## S3 method for class 'epidataCS':
summary(object, ...)
## S3 method for class 'summary.epidataCS':
print(x, ...)
## S3 method for class 'epidataCS':
as.stepfun(x, ...)
getSourceDists(object, dimension = c("space", "time"))

Arguments

events

a "SpatialPointsDataFrame" of cases with the following obligatory columns (in the events@data data.frame): [object Object],[object Object],[object Object],[object Object],[obje

stgrid

a data.frame describing endemic covariates on a full spatio-temporal region x interval grid (e.g., district x week), which is a decomposition of the observation region W and peri

an object of class "SpatialPolygons" representing the observation region. It must have the same proj4string as events and all events must be within W. The funct

qmatrix

a square indicator matrix (0/1 or FALSE/TRUE) for possible transmission between the event types. The matrix will be internally converted to logical. Defaults to an independent spread of the event types, i

nCircle2Poly

accuracy (number of edges) of the polygonal approximation of a circle, see discpoly.

end of observation period (i.e. last stop time of stgrid). Must be specified if the start but not the stop times are supplied in stgrid (=> auto-generation of stop times).

clipper

polygon clipping engine to use for calculating the .influenceRegions of events (see the Value section below). Default is the polyclip package (called via intersect.owin

verbose

logical indicating if status messages should be printed
  during input checking and "epidataCS" generation. The default
  is to do so in interactive Rsessions.

x

an object of class "epidataCS" or
    "summary.epidataCS", respectively.

n

a single integer. If positive, the first (head, print)
    / last (tail) n events are extracted. If negative,
    all but the n first/last events are extracted.

digits

minimum number of significant digits to be printed in
    values.

i,j,drop

arguments passed to the
    [-method for
    SpatialPointDataFrames for subsetting the events while
    retaining stgrid and W

...

unused (arguments of the generics) with a few exceptions:
    The print method for "epidataCS" passes
    ... to the print.data.frame method, and the

subset, select

arguments used to subset the events from
    an "epidataCS" object like in subset.data.frame.

coords

logical indicating if the data frame of event marks
    returned by marks(x) should have the event
    coordinates appended as last columns. This defaults to TRUE.

object

an object of class "epidataCS".

dimension

the distances of all events to their potential source
    events can be computed in either the "space" or "time"
    dimension.

`Value`

An object of class "epidataCS" is a list containing the
  following components:
eventsa "SpatialPointsDataFrame" (see the
    description of the argument). 
    The input events are checked for requirements and sorted
    chronologically. The columns are in the following
    order: obligatory event columns, event marks, the columns BLOCK,
    start and endemic covariates copied from stgrid,
    and finally, hidden auxiliary columns. 
    The added auxiliary columns are:
    [object Object],[object Object],[object Object],[object Object]
stgrida data.frame (see description of the argument).
    The spatio-temporal grid of endemic covariates is sorted by time
    interval (indexed by the added variable BLOCK) and region
    (tile). It is a full BLOCK x tile grid.
Wa "SpatialPolygons" object representing
    the observation region.
qmatrixsee the above description of the argument. The
    storage.mode of the indicator matrix is set to logical
    and the dimnames are set to the levels of the event types.
The nobs-method returns the number of events.
  The head and tail methods subset the epidemic data using
  the extraction method ([), i.e. they return an object of class
  "epidataCS", which only contains (all but) the first/last
  n events.
  For the "epidataCS" class, the method of the generic function
  marks defined by the spatstat package
  returns a data.frame of the event marks (actually also
  including time and location of the events), disregarding endemic
  covariates and the auxiliary columns from the events component
  of the "epidataCS" object.
  The summary method (which has again a print method)
  returns a list of metadata, event data, the tables of tiles and types,
  a step function of the number of infectious individuals over time
  ($counter), i.e., the result of the
  as.stepfun-method for "epidataCS", and the number
  of potential sources of transmission for each event ($nSources)
  which is based on the given maximum interaction ranges eps.t
  and eps.s.

`encoding`

latin1

`Details`

The function as.epidataCS is used to generate objects of class
  "epidataCS", which is the data structure required for
  twinstim models.
  The extraction method for class "epidataCS"
  ensures that the subsetted object will be valid, for instance, it
  updates the auxiliary list of potential transmission paths stored
  in the object. This [-method is also the basis for the
  subset.epidataCS-method, which is implemented similar to the
  subset.data.frame-method.
  
  The print method for "epidataCS" prints some metadata
  of the epidemic, e.g., the observation period, the dimensions of the
  spatio-temporal grid, the types of events, and the total number of
  events. By default, it also prints the first n = 6 rows of the
  events.

`References`

Douglas, D. H. and Peucker, T. K. (1973):
  Algorithms for the reduction of the number of points required to
  represent a digitized line or its caricature.
  Cartographica: The International Journal for Geographic
  Information and Geovisualization, 10, 112-122.
  Harrower, M. and Bloch, M. (2006):
  MapShaper.org: A Map Generalization Web Service.
  IEEE Computer Graphics and Applications, 26(4), 22-27.
  10.1109/MCG.2006.85
  Meyer, S., Elias, J. and H�{oe}hle, M. (2012):
  A space-time conditional intensity model for invasive meningococcal
  disease occurrence. Biometrics, 68, 607-616.
  10.1111/j.1541-0420.2011.01684.x
  Meyer, S., Held, L. and H�{oe}hle, M. (2016):
  Spatio-temporal analysis of epidemic phenomena using the Rpackage
  surveillance. Journal of Statistical Software. In press.
Preprint available at http://arxiv.org/abs/1411.0416

`See Also`

vignette("twinstim").
  plot.epidataCS for plotting, and
  animate.epidataCS for the animation of such an epidemic.
  There is also an update method for the
  "epidataCS" class.
  Models for "epidataCS" can be fitted with twinstim.
  It is also possible to convert the data to epidata
  objects (discrete space) for analysis with twinSIR
  (see as.epidata.epidataCS).

`Examples`

Run this code## load "imdepi" example data (which is an object of class "epidataCS")
data("imdepi")

## print and summary
print(imdepi, n=5, digits=2)
print(s <- summary(imdepi))
plot(s$counter,  # same as 'as.stepfun(imdepi)'
     xlab = "Time [days]", ylab="Number of infectious individuals",
     main=paste("Time course of the number of infectious individuals",
                "assuming an infectious period of 30 days", sep=""))
plot(table(s$nSources), xlab="Number of "close" infective individuals",
     ylab="Number of events",
     main=paste("Distribution of the number of potential sources",
                "assuming an interaction range of 200 km and 30 days",
                sep=""))
## the summary object contains further information
str(s)

## a histogram of the spatial distances to potential source events
## (i.e., to events of the previous eps.t=30 days within eps.s=200 km)
sourceDists_space <- getSourceDists(imdepi, "space")
hist(sourceDists_space); rug(sourceDists_space)

## internal structure of an "epidataCS"-object
str(imdepi, max.level=4)
## see help("imdepi") for more info on the data set

## extraction methods subset the 'events' component
## (thereby taking care of the validity of the epidataCS object,
## for instance the hidden auxiliary column .sources)
imdepi[101:200,]
tail(imdepi, n=4)           # reduce the epidemic to the last 4 events
subset(imdepi, type=="B")   # only consider event type B

## see help("plot.epidataCS") for convenient plot-methods for "epidataCS"


###
### reconstruct the "imdepi" object from its components
###

## events
events <- marks(imdepi)
coordinates(events) <- c("x", "y")  # promote to a "SpatialPointsDataFrame"
proj4string(events) <- proj4string(imdepi$events)       # ETRS89 projection
summary(events)

## endemic covariates
head(stgrid <- imdepi$stgrid[,-1])

## (Simplified) observation region (as SpatialPolygons)
load(system.file("shapes", "districtsD.RData", package="surveillance"),
     verbose = TRUE)

## plot observation region with events
plot(stateD, axes=TRUE); title(xlab="x [km]", ylab="y [km]")
points(events, pch=unclass(events$type), cex=0.5, col=unclass(events$type))
legend("topright", legend=levels(events$type), title="Type", pch=1:2, col=1:2)

## reconstruct the "imdepi" object from its components
myimdepi <- as.epidataCS(events = events, stgrid = stgrid,
                         W = stateD, qmatrix = diag(2), nCircle2Poly = 16)
## -> equal to 'imdepi' as long as the internal structures of the embedded
##    classes ("owin", "SpatialPolygons", ...), and the calculation of the
##    influence regions by "polyclip" do not change:
##all.equal(imdepi, myimdepi, tolerance=1E-6)
Run the code above in your browser using DataLab