surveillance (version 1.8-0)

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 epidemic intensity models with the function 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 = FALSE)
## S3 method for class 'epidataCS':
subset(x, subset, select, drop = FALSE, ...)
## 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, ...)

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

W

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.

T

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

arguments passed to the [-method for SpatialPointDataFrames for subsetting the events (not stgrid or W).

drop, ...

unused (arguments of the generics). However, the print method for "epidataCS" passes ...to the print.data.frame method, and the print method for <

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.epidataCS should also include the event coordinates. This defaults to TRUE.

object

an object of class "epidataCS".

Value

• An object of class "epidataCS" is a list containing the following components:
• events
  a "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]
• stgrid
  a 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.
• W
  a "SpatialPolygons" object representing the observation region.
• qmatrix
  see 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. DOI-Link: http://dx.doi.org/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. DOI-Link: http://dx.doi.org/10.1111/j.1541-0420.2011.01684.x

Meyer, S. (2010): Spatio-Temporal Infectious Disease Epidemiology based on Point Processes. Master's Thesis, Ludwig-Maximilians-Universit�{ae}t M�{ue}nchen. Available as http://epub.ub.uni-muenchen.de/11703/

See Also

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

## take a look at the data object
print(imdepi, n=5, digits=2)
s <- summary(imdepi)
s
plot(s$counter, 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)

## see the help page on the 'imdepi' dataset for more insight

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


### now reconstruct the 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)
# similar to using the convenient plot-method for "epidataCS"
    plot(imdepi, "space")

## reconstruct the "imdepi" object from its components
myimdepi <- as.epidataCS(events = events, stgrid = stgrid,
                         W = stateD, qmatrix = diag(2), nCircle2Poly = 16)
## should be equal as long as the internal structures of "epidataCS" and
## of the embedded classes ("owin", "SpatialPolygons", ...) do not change
if (!identical(imdepi, myimdepi))
    warning("@Sebastian: update data(imdepi)")

## internal structure of an "epidataCS"-object
str(imdepi, max.level=4)

Run the code above in your browser using DataLab