stsplot_space: Map of Disease Counts/Incidence accumulated over a Given Period

Description

This is the plot variant of type=observed~unit for "sts" objects, i.e., plot(stsObj, type=observed~unit, ...) calls the function documented below. It produces an spplot where regions are color-coded according to disease incidence (either absolute counts or relative to population) over a given time period.

Usage

stsplot_space(x, tps = NULL, map = x@map, population = NULL,
              main = NULL, labels = FALSE, ...,
              at = 10, col.regions = NULL,
              colorkey = list(space = "bottom", labels = list(at=at)),
              total.args = NULL,
              gpar.missing = list(col = "darkgrey", lty = 2, lwd = 2),
              sp.layout = NULL, 
              xlim = bbox(map)[1, ], ylim = bbox(map)[2, ])

Value

a lattice plot of class

"trellis", but see

spplot.

Arguments

x

an object of class "sts" or a matrix of counts, i.e., observed(stsObj), where especially colnames(x) have to be contained in row.names(map). If a matrix, the map object has to be provided explicitly. The possibility of specifying a matrix is, e.g., useful to plot mean counts of simulations from simulate.hhh4.

tps

a numeric vector of one or more time points. The unit-specific sum over all time points tps is plotted. The default tps=NULL means accumulation over the whole time period 1:nrow(x).

map

an object inheriting from "SpatialPolygons" representing the ncol(x) regions. By default the map slot of x is queried (which might be empty and is not applicable if x is a matrix of counts).

population

if NULL (default), the map shows the region-specific numbers of cases accumulated over tps. For a disease incidence map, population can be specified in three ways:

a numeric vector of population numbers in the ncol(x) regions, used to divide the disease counts.
a matrix of population counts of dimension dim(x) (such as population(x) in an "sts" object). This will produce the cumulative incidence over tps relative to the population at the first time point, i.e., only population[tps[1],] is used.
[if is(x, "sts")] a scalar specifying how population(x) should be scaled for use as the population matrix, i.e., population(x)/population is used. For instance, if population(x) contains raw population numbers, population=1000 would produce the incidence per 1000 inhabitants.

main

a main title for the plot. If NULL and x is of class "sts", the time range of tps is put as the main title.

labels

determines if and how the regions of the map are labeled, see layout.labels.

...

further arguments for spplot, for example col = "white" for white polygon lines.

at

either a number of levels (default: 10) for the categorization (color-coding) of counts/incidence, or a numeric vector of specific break points, or a named list of a number of levels ("n"), a transformer ("trafo") of class "trans" defined by package scales, and optional further arguments for pretty. The default breaks are equally spaced on the square-root scale (equivalent to sqrt_trans). Note that intervals given by at are closed on the left and open to the right; if manually specified break points do not cover the data range, further breaks are automatically added at 0 and the maximum (rounded up to 1 significant digit), respectively.

col.regions

a vector of fill colors, sufficiently long to serve all levels (determined by at). “Heat” colors are used by default (NULL).

colorkey

a list describing the color key, see levelplot. The default list elements will be updated by the provided list using modifyList.

total.args

an optional list of arguments for grid.text to have the overall number/incidence of cases printed at an edge of the map. The default settings are list(label="Overall: ", x=1, y=0), and total.args=list() will use all of them.

gpar.missing

list of graphical parameters for sp.polygons applied to the regions of map, which are not part of x. Such extra regions won't be plotted if !is.list(gpar.missing).

sp.layout

optional list of additional layout items, see spplot.

xlim,ylim: numeric vectors of length 2 specifying the axis limits.

Author

Sebastian Meyer

Examples

Run this code

data("measlesWeserEms")

# default plot: total region-specific counts over all weeks
plot(measlesWeserEms, type = observed ~ unit)
stsplot_space(measlesWeserEms)  # the same

# cumulative incidence (per 100'000 inhabitants),
# with region labels and white borders
plot(measlesWeserEms, observed ~ unit,
     population = measlesWeserEms@map$POPULATION / 100000,
     labels = list(labels = "GEN", cex = 0.7, font = 3),
     col = "white", lwd = 2,
     sub = "cumulative incidence (per 100'000 inhabitants)")

# incidence in a particular week, manual color breaks, display total
plot(measlesWeserEms, observed ~ unit, tps = 62,
     population = measlesWeserEms@map$POPULATION / 100000,
     at = c(0, 1, 5),
     total.args = list(x = 0, label = "Overall incidence: "))

# if we had only observed a subset of the regions
plot(measlesWeserEms[,5:11], observed ~ unit,
     gpar.missing = list(col = "gray", lty = 4))