epidata_animate {surveillance}

Spatio-Temporal Animation of an Epidemic

Description

Function for the animation of epidemic data, i.e. objects inheriting from class "epidata". This only works with 1- or 2-dimensional coordinates and is not useful if some individuals share the same coordinates (overlapping). There are two types of animation, see argument time.spacing. Besides the direct plotting in the R session, it is also possible to generate a sequence of graphics files to create animations outside R.

Usage

## S3 method for class 'summary.epidata'
animate(object, main = "An animation of the epidemic",
        pch = 19, col = c(3, 2, gray(0.6)), time.spacing = NULL,
        sleep = quote(5/.nTimes), legend.opts = list(), timer.opts = list(),
        end = NULL, generate.snapshots = NULL, ...)

## S3 method for class 'epidata'
animate(object, ...)

Arguments

object

an object inheriting from class "epidata" or "summary.epidata". In the former case, its summary is calculated and the function continues as in the latter case, passing all ... arguments to the summary.epidata method.

main

a main title for the plot, see also title.

pch, col

vectors of length 3 specifying the point symbols and colors for susceptible, infectious and removed individuals (in this order). The vectors are recycled if necessary. By default, susceptible individuals are marked as filled green circles, infectious individuals as filled red circles and removed individuals as filled gray circles. Note that the symbols are iteratively drawn (overlaid) in the same plotting region as time proceeds. For information about the possible values of pch and col, see the help pages of points and par, respectively.

time.spacing

time interval for the animation steps. If NULL (the default), the events are plotted one by one with pauses of sleep seconds. 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 plots. 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). The argument sleep will be the artificial pause in seconds between two of those time points.

sleep

time in seconds to Sys.sleep before the next plotting event. By default, each artificial pause is of length 5/.nTimes seconds, where .nTimes is the number of events (infections and removals) of the epidemic, which is evaluated in the function body. Thus, for time.spacing = NULL the animation has a duration of approximately 5 seconds. In the other case, sleep is the duration of the artificial pause between two time points. Note that sleep is ignored on non-interactive devices (see dev.interactive)

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, i.e.

x:

"topright"

legend:

c("susceptible", "infectious", "removed")

pch:

same as argument pch of the main function

col:

same as argument col of the main function

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.

end

ending time of the animation in case of time.spacing not being NULL. By default (NULL), time stops after the last event.

generate.snapshots

By default (NULL), the animation is not saved to image files but only shown on the on-screen device. In order to print to files, time.spacing must not be NULL, a screen device must be available, and there are two options:
If the framework of the animation package should be used, i.e. the animate-call is passed as the expr argument to one of the save* functions of the animation package, then set generate.snapshots = img.name, where img.name is the base name for the generated images (the same as passed to the save* function). The path and format (type, width, height) for the generated images is derived from ani.options. See the last example below.
Alternatively, generate.snapshots may be a list of arguments passed to the function dev.print, which then is executed at each time point of the grid defined by time.spacing. Essentially, this is used for saving the produced snapshots to files, e.g.

generate.snapshots = list(device=pdf, file=quote(paste("epidemic_",sprintf(form,tp),".pdf", sep="")))

will store the animation steps in pdf-files in the current working directory, where the file names each end with the time point represented by the corresponding plot. Because the variables tp and form should only be evaluated inside the function the file argument is quoted. Alternatively, the file name could also make use of the internal plot index i, e.g., use file=quote(paste("epidemic",i,".pdf",sep="")).

...

further graphical parameters passed to the basic call of plot, e.g. las, cex.axis (etc.) and mgp.

Author(s)

Sebastian Meyer

See Also

summary.epidata for the data, on which the plot is based. plot.epidata for plotting the evolution of an epidemic by the numbers of susceptible, infectious and removed individuals.

The contributed R package animation.

Examples

data("hagelloch")
(s <- summary(hagelloch))

# plot the ordering of the events only
animate(s)   # or: animate(hagelloch)

# with timer (animate only up to t=10)
animate(s, time.spacing=0.1, end=10, sleep=0.01,
        legend.opts=list(x="topleft"))

# Such an animation can be saved in various ways using tools of
# the animation package, e.g., saveHTML()
if (interactive() && require("animation")) {
  oldwd <- setwd(tempdir())  # to not clutter up the current working dir
  saveHTML({
    par(bg="white")  # default "transparent" is grey in some browsers
    animate(s, time.spacing=1, sleep=0, legend.opts=list(x="topleft"),
            generate.snapshots="epiani")
  }, use.dev=FALSE, img.name="epiani", ani.width=600, interval=0.5)
  setwd(oldwd)
}