surveillance: epidataCS_plot – R documentation

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

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 class '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, ...)

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

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

Author(s)

Sebastian Meyer

Examples

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)))
  grid::grid.text("Population density [per km2]", x=0.95, rot=90)
}

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