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

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

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.

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

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:
eventsa "SpatialPointsDataFrame" (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]
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), 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 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

## construct an object of class "epidataCS" from these components
myimdepi <- as.epidataCS(events, stgrid, W, qmatrix, 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)")

## take a look into the internal structure of an epidataCS-object
str(imdepi, max.level=4)
Run the code above in your browser using DataLab