surveillance (version 1.5-4)

twinstim_epidataCS: Class for Representing Continuous Space-Time Point Process Data

Description

Data structure for (c)ontinuous (s)patio-temporal event data, typically cases of an infectious disease. The data structure simultaneously contains a spatio-temporal grid of endemic covariates 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)
## 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, ...)

Arguments

events

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

stgrid

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 period $t_0,T$. This means that for every com

W

an object of class "SpatialPolygons" indicating the observation region. Must have the same proj4string as events and all events must be within W. The function

qmatrix

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.e

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

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 class "epidataCS" passes ...to the print.data.frame method.

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
  see the description of the argument. The input events are checked for requirements, sorted chronologically and attributed an ID. The columns are in the following order: ID, 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
  see the 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
  observation region as SpatialPolygons (see the argument description).
• qmatrix
  see the 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), 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 that twinstim models work on.

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

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

## (Simplified) observation region (as SpatialPolygons)
W <- imdepi$W
summary(W)

## events
events <- marks(imdepi)[,-1]
coordinates(events) <- c("x", "y")    # promote to a SpatialPointsDataFrame
proj4string(events) <- proj4string(W) # ETRS89 projection (+units=km)
summary(events)

## plot W with events
plot(W, 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")

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

## indicator matrix for possible transmission between event types
qmatrix <- imdepi$qmatrix
qmatrix

## now construct an object of class "epidataCS" from these components
if (require("gpclib")) {
    oopt <- surveillance.options(gpclib=TRUE)
    myimdepi <- as.epidataCS(events, stgrid, W, qmatrix, nCircle2Poly=16)
    surveillance.options(oopt)
}

## should be equal as long as the internal structures of "epidataCS" and
## of the embedded class "owin" do not change
if (!identical(imdepi, myimdepi))
    warning("@Sebastian: update data(imdepi)")

## take a look into the internal structure of an epidataCS-object
str(imdepi, max.level=4)