surveillance: stsplot_space – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

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

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`.
`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 is the square root transformation (`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.
`...`	further arguments for `spplot`.

Value

a lattice plot of class "trellis", but see spplot.

Author(s)

Sebastian Meyer

Examples

data("measlesWeserEms")

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

# compare with old implementation
plot(measlesWeserEms, type = observed~1|unit)

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

# incidence in a particular week, manual color breaks, display total
plot(measlesWeserEms, type=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], type = observed~unit,
     gpar.missing = list(col="gray", lty=4))

surveillance

Temporal and Spatio-Temporal Modeling and Monitoring of Epidemic Phenomena

v1.19.1

GPL-2

Authors

Michael H<f6>hle [aut, ths] (<https://orcid.org/0000-0002-0423-6702>), Sebastian Meyer [aut, cre] (<https://orcid.org/0000-0002-1791-9449>), Michaela Paul [aut], Leonhard Held [ctb, ths], Howard Burkom [ctb], Thais Correa [ctb], Mathias Hofmann [ctb], Christian Lang [ctb], Juliane Manitz [ctb], Andrea Riebler [ctb], Daniel Saban<e9>s Bov<e9> [ctb], Ma<eb>lle Salmon [ctb], Dirk Schumacher [ctb], Stefan Steiner [ctb], Mikko Virtanen [ctb], Wei Wei [ctb], Valentin Wimmer [ctb], R Core Team [ctb] (A few code segments are modified versions of code from base R)

Initial release

2021-03-30