surveillance (version 1.20.3)

sts_animate: Animated Maps and Time Series of Disease Counts or Incidence

Description

The animate-method for sts objects supersedes the stsplot type observed~1|unit*time implemented by the function stsplot_spacetime. Maps generated by stsplot_space are sequentially plotted along time (optionally showing cumulative counts/incidence), with an optional time series chart below the map to track the epidemic curve. It is worth using functionality of the animation package (e.g., saveHTML) to directly export the animation into a useful format. See Meyer and Held (2014, Supplement A) for an example with the fluBYBW data.

Usage

# S3 method for sts
animate(object, tps = NULL, cumulative = FALSE,
        population = NULL, at = 10, ...,
        timeplot = list(pos = 1, size = 0.3, fill = TRUE),
        sleep = 0.5, verbose = interactive(), draw = TRUE)

Value

(invisibly) a list of the length(tps) sequential plot objects. These are of class "gtable" (from gtable) if the timeplot is included, otherwise of class

"\code{trellis".

Arguments

object

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 (as part of ...).

tps

a numeric vector of one or more time points at which to plot the map. The default tps=NULL means the whole time period 1:nrow(object).

cumulative

logical specifying if the cumulative counts/incidence over time should be plotted. The cumulative incidence is relative to the population from the first time point tps[1] throughout the whole animation, while cumulative=FALSE computes the incidence from the current population numbers.

population,at,...

arguments for stsplot_space.

timeplot

if a list and package gridExtra is available, a time series chart of the counts along the selected time points tps will be plotted next to the map. The list elements determine both the positioning of this plot (pos, size, and fill) and its appearance. The default pos=1 and size=0.3 arguments put the time series plot below the map, using 30% of the total plot height. The logical value fill indicates whether to make the panel as big as possible (default: TRUE). An alternative to fill=FALSE is to manually specify an aspect (ratio) value in timeplot. Other list elements are arguments for the internal (and currently undocumented) function stsplot_timeSimple. For example, inactive and active are lists of graphical parameters (e.g., col) determining the appearance of the bars (e.g., default color is grey when inactive and black when active), and the boolean as.Date determines whether dates should be put on the x-axis (instead of the tps indexes).

sleep

time to wait (Sys.sleep) between subsequent snapshots (only if dev.interactive), in seconds.

verbose

logical indicating if a txtProgressBar should be shown during generation of the animation -- which may take a while. Default is to do so in interactive sessions.

draw

logical indicating if the produced plots at each time point should be drawn directly (the default) or not. The setting draw = FALSE is useful if one would like to manually arrange the plots, which are always returned invisibly in a list of length length(tps).

Author

Sebastian Meyer

References

Meyer, S. and Held, L. (2014): Power-law models for infectious disease spread. The Annals of Applied Statistics, 8 (3), 1612-1639. tools:::Rd_expr_doi("10.1214/14-AOAS743").
Supplement A is available from https://www.biostat.uzh.ch/static/powerlaw/.

See Also

the other plot types documented in stsplot for static time series plots and maps.

Examples

data("measlesWeserEms")

## animate the weekly counts of measles (during weeks 12-16 only, for speed)
if (interactive() && require("animation")) {
    oldwd <- setwd(tempdir())  # to not clutter up the current working dir
    saveHTML(animate(measlesWeserEms, tps=12:16),
             title="Evolution of the measles epidemic in the Weser-Ems region",
             ani.width=500, ani.height=600)
    setwd(oldwd)
}

if (FALSE) {
## animate the weekly incidence of measles (per 100'000 inhabitants),
## and label the time series plot with dates in a specified format
animate(measlesWeserEms, tps=12:16,
        population = measlesWeserEms@map$POPULATION / 100000,
        timeplot = list(as.Date = TRUE,
                        scales = list(x = list(format = "%G/%V"))))
}