epidataCS_plot: Plotting the Events of an Epidemic over Time and Space

Description

The plot method for class "epidataCS" either plots the number of events along the time axis (epidataCSplot_time) as a hist(), or the locations of the events in the observation region W (epidataCSplot_space). The spatial plot can be enriched with tile-specific color levels to indicate attributes such as the population (using spplot).

Usage

# S3 method for epidataCS
plot(x, aggregate = c("time", "space"), subset, by = type, ...)
epidataCSplot_time(x, subset, by = type,
                   t0.Date = NULL, breaks = "stgrid", freq = TRUE,
                   col = rainbow(nTypes), cumulative = list(),
                   add = FALSE, mar = NULL, xlim = NULL, ylim = NULL,
                   xlab = "Time", ylab = NULL, main = NULL,
                   panel.first = abline(h=axTicks(2), lty=2, col="grey"),
                   legend.types = list(), ...)
epidataCSplot_space(x, subset, by = type, tiles = x$W, pop = NULL,
                    cex.fun = sqrt, points.args = list(), add = FALSE,
                    legend.types = list(), legend.counts = list(),
                    sp.layout = NULL, ...)

Value

For aggregate="time" (i.e., epidataCSplot_time) the data of the histogram (as returned by hist), and for aggregate="space" (i.e., epidataCSplot_space) NULL, invisibly, or the trellis.object generated by spplot (if pop is non-NULL).

Arguments

x: an object of class "epidataCS".
aggregate: character, one of "time" and "space", referring to the specific plot functions epidataCSplot_time and epidataCSplot_time, respectively. For "time", the number of events over time is plotted as hist (or hist.Date). For "space", the observation region x$W (or the tiles) and the locations of the events therein are plotted.
subset: logical expression indicating a subset of events to consider for plotting: missing values are taken as false. Note that the expression is evaluated in the data frame of event marks (marks(x)), which means that column names can be referred to by name (like in subset.data.frame).
...: in the basic plot-method further arguments are passed to the aggregate-specific plot function. In epidataCSplot_time, further graphical parameters are passed to hist or hist.Date, respectively. In epidataCSplot_space, further arguments are passed to the plot-method for "SpatialPolygons", which draws tiles.
by: an expression evaluated in marks(x), defining how events should be stratified in the plot (the result is converted to a factor), or NULL to disregard event types. By default (by = type) the plot distinguishes between event types, i.e., the bars of the temporal plot are stacked by type, and the point colors in the spatial plot differ by type, respectively.
Note: to select specific event types for plotting use the subset argument, e.g., subset=(type=="B").
t0.Date: the beginning of the observation period t0 = x$stgrid$start[1] as a "Date" (or anything coercible by as.Date without further arguments), enabling a nice x-axis using hist.Date and sensible breaks of the histogram, e.g., breaks="months". The event times then equal t0.Date + as.integer(x$events$time - t0), i.e. possible fractional parts of the event times are removed (which ensures that using breaks = "months" or other automatic types always works).
breaks: a specification of the histogram break points, see hist (or hist.Date if t0.Date is used). The default value "stgrid" is special and means to use the temporal grid points with(x$stgrid, c(start[1L], unique.default(stop))) as breaks (or their "Date" equivalents).
freq: see hist, defaults to TRUE.
col: fill colour for the bars of the histogram, defaults to the vector of rainbow colours.
cumulative: if a list (of style options), lines for the cumulative number of events (per type) will be added to the plot. Possible options are axis (logical), lab (axis label), maxat (single integer affecting the axis range), lwd, col, and offset (a numeric vector of length the number of types).
add: logical (default: FALSE) indicating if the plot should be added to an existing window. Ignored if an spplot is created (if pop is non-NULL).
mar: see par. The default (NULL) is mar <- par("mar"), with mar[4] <- mar[2] if an axis is requested for the cumulative numbers.
xlim,ylim: NULL provides automatic axis limits.
xlab,ylab: axis labels (with sensible defaults).
main: main title of the plot (defaults to no title).
panel.first: expression that should be evaluated after the plotting window has been set up but before the histogram is plotted. Defaults to adding horizontal grid lines.
legend.types: if a list (of arguments for legend), a legend for the event types is added to the plot in case there is more than one type.
tiles: the observation region x$W (default) or, alternatively, a "SpatialPolygons" representation of the tiles of x$stgrid.
pop: if tiles is a "SpatialPolygonsDataFrame", pop can specify an attribute to be displayed in a levelplot behind the point pattern, see spplot. By default (NULL), the conventional graphics system is used to display the tiles and event locations, otherwise the result is a trellis.object.
cex.fun: function which takes a vector of counts of events at each unique location and returns a (vector of) cex value(s) for the sizes of the corresponding points. Defaults to the sqrt() function, which for the default circular pch=1 means that the area of each point is proportional to the number of events at its location.
points.args: a list of (type-specific) graphical parameters for points, specifically pch, lwd, and col, which are all recycled to give the length nlevels(x$events$type). In contrast, a possible cex element should be scalar (default: 0.5) and multiplies the sizes obtained from cex.fun.
legend.counts: if a list (of arguments for legend), a legend illustrating the effect of cex.fun is added to the plot. This list may contain a special element counts, which is an integer vector specifying the counts to illustrate.
sp.layout: optional list of additional layout items in case pop is non-NULL, see spplot.

Author

Sebastian Meyer

Examples

Run this code

data("imdepi")

## show the occurrence of events along time
plot(imdepi, "time", main = "Histogram of event time points")
plot(imdepi, "time", by = NULL, main = "Aggregated over both event types")

## show the distribution in space
plot(imdepi, "space", lwd = 2, col = "lavender")

if (surveillance.options("allExamples")) {
## with the district-specific population density in the background,
## a scale bar, and customized point style
load(system.file("shapes", "districtsD.RData", package = "surveillance"))
districtsD$log10popdens <- log10(districtsD$POPULATION/districtsD$AREA)
keylabels <- (c(1,2,5) * rep(10^(1:3), each=3))[-1]
plot(imdepi, "space", tiles = districtsD, pop = "log10popdens",
     ## modify point style for better visibility on gray background
     points.args = list(pch=c(1,3), col=c("orangered","blue"), lwd=2),
     ## metric scale bar, see proj4string(imdepi$W)
     sp.layout = layout.scalebar(imdepi$W, scale=100, labels=c("0","100 km")),
     ## gray scale for the population density and white borders
     col.regions = gray.colors(100, start=0.9, end=0.1), col = "white",
     ## color key is equidistant on log10(popdens) scale
     at = seq(1.3, 3.7, by=0.05),
     colorkey = list(labels=list(at=log10(keylabels), labels=keylabels),
                     title=expression("Population density per " * km^2)))
}