surveillance (version 1.24.0)

epidataCS_animate: Spatio-Temporal Animation of a Continuous-Time Continuous-Space Epidemic

Description

Function for the animation of continuous-time continuous-space epidemic data, i.e. objects inheriting from class "epidataCS". There are three types of animation, see argument time.spacing. Besides the on-screen plotting in the interactive R session, it is possible and recommended to redirect the animation to an off-screen graphics device using the contributed R package animation. For instance, the animation can be watched and navigated in a web browser via saveHTML (see Examples).

Usage

# S3 method for epidataCS
animate(object, interval = c(0,Inf), time.spacing = NULL,
        nmax = NULL, sleep = NULL, legend.opts = list(), timer.opts = list(),
        pch = 15:18, col.current = "red", col.I = "#C16E41",
        col.R = "#B3B3B3", col.influence = NULL,
        main = NULL, verbose = interactive(), ...)

Arguments

object

an object inheriting from class "epidataCS".

interval

time range of the animation.

time.spacing

time interval for the animation steps.
If NULL (the default), the events are plotted sequentially by producing a snapshot at every time point where an event occurred. Thus, it is just the ordering of the events, which is shown.
To plot the appearance of events proportionally to the exact time line, time.spacing can be set to a numeric value indicating the period of time between consecutive snapshots. Then, for each time point in seq(0, end, by = time.spacing) the current state of the epidemic can be seen and an additional timer indicates the current time (see timer.opts below).
If time.spacing = NA, then the time spacing is automatically determined in such a way that nmax snapshots result. In this case, nmax must be given a finite value.

nmax

maximum number of snapshots to generate. The default NULL means to take the value from ani.options("nmax") if the animation package is available, and no limitation (Inf) otherwise.

sleep

numeric scalar specifying the artificial pause in seconds between two time points (using Sys.sleep), or NULL (default), when this is taken from ani.options("interval") if the animation package is available, and set to 0.1 otherwise. Note that sleep is ignored on non-interactive devices (see dev.interactive), e.g., if generating an animation inside animation's saveHTML.

pch, col

vectors of length equal to the number of event types specifying the point symbols and colors for events to plot (in this order). The vectors are recycled if necessary.

legend.opts

either a list of arguments passed to the legend function or NULL (or NA), in which case no legend will be plotted. All necessary arguments have sensible defaults and need not be specified.

timer.opts

either a list of arguments passed to the legend function or NULL (or NA), in which case no timer will be plotted. All necessary arguments have sensible defaults and need not be specified, i.e.

x:

"bottomright"

title:

"time"

box.lty:

0

adj:

c(0.5,0.5)

inset:

0.01

bg:

"white"

Note that the argument legend, which is the current time of the animation, can not be modified.

col.current

color of events when occurring (new).

col.I

color once infectious.

col.R

color event has once “recovered”. If NA, then recovered events will not be shown.

col.influence

color with which the influence region is drawn. Use NULL (default) if no influence regions should be drawn.

main

optional main title placed above the map.

verbose

logical specifying if a (textual) progress bar should be shown during snapshot generation. This is especially useful if the animation is produced within saveHTML or similar.

...

further graphical parameters passed to the plot method for "SpatialPolygons".

Author

Sebastian Meyer with documentation contributions by Michael Höhle

See Also

plot.epidataCS for plotting the numbers of events by time (aggregated over space) or the locations of the events in the observation region W (aggregated over time).

The contributed R package animation.

Examples

data("imdepi")
imdepiB <- subset(imdepi, type == "B")

if (FALSE) {
# Animate the first year of type B with a step size of 7 days
animate(imdepiB, interval=c(0,365), time.spacing=7, nmax=Inf, sleep=0.1)

# Sequential animation of type B events during the first year
animate(imdepiB, interval=c(0,365), time.spacing=NULL, sleep=0.1)

# Animate the whole time range but with nmax=20 snapshots only
animate(imdepiB, time.spacing=NA, nmax=20, sleep=0.1)
}

# Such an animation can be saved in various ways using the tools of
# the animation package, e.g., saveHTML()
if (interactive() && require("animation")) {
  oldwd <- setwd(tempdir())  # to not clutter up the current working dir
  saveHTML(animate(imdepiB, interval = c(0,365), time.spacing = 7),
           nmax = Inf, interval = 0.2, loop = FALSE,
           title = "Animation of the first year of type B events")
  setwd(oldwd)
}