surveillance (version 1.24.0)

stsplot_time: Time-Series Plots for "sts" Objects

Description

These are the plot variants of type=observed~time|unit, type=observed~time, and type=alarm~time for "sts" objects (see the central "sts" plot-method for an overview of plot types).

Usage

stsplot_time(x, units=NULL,
             as.one=FALSE, same.scale=TRUE, par.list=list(), ...)
stsplot_time1(x, k=1, ylim=NULL,
              axes=TRUE, xaxis.tickFreq=list("%Q"=atChange),
              xaxis.labelFreq=xaxis.tickFreq, xaxis.labelFormat="%G\n\n%OQ",
              epochsAsDate=x@epochAsDate,
              xlab="time", ylab="No. infected", main=NULL,
              type="s", lty=c(1,1,2), col=c(NA,1,4), lwd=c(1,1,1),
              outbreak.symbol=list(pch=3, col=3, cex=1, lwd=1),
              alarm.symbol=list(pch=24, col=2, cex=1, lwd=1),
              legend.opts=list(),
              dx.upperbound=0L, hookFunc=function(){},
              .hookFuncInheritance=function() {}, ...)
stsplot_alarm(x, lvl=rep(1,ncol(x)),
              xaxis.tickFreq=list("%Q"=atChange),
              xaxis.labelFreq=xaxis.tickFreq, xaxis.labelFormat="%G\n\n%OQ",
              epochsAsDate=x@epochAsDate,
              xlab="time", ylab="", main=NULL,
              outbreak.symbol=list(pch=3, col=3, cex=1, lwd=1),
              alarm.symbol=list(pch=24, col=2, cex=1, lwd=1),
              cex.yaxis=1, ...)

Value

NULL (invisibly). The functions are called for their side-effects.

Arguments

x

an object of class "sts".

units

optional integer or character vector to select the units (=columns of observed(x)) to plot. The default is to plot all time series. If as.one=FALSE, stsplot_time1 is called for (k in units) with mfrow splitting (see par.list). Note that if there are too many units, the default mfrow setting might lead to the error “figure margins too large” (meaning that the units do not fit onto a single page).

as.one

logical indicating if all time series should be plotted in a single frame (using matplot).

same.scale

logical indicating if all time series should be plotted with the same ylim. Default is to do so. Only relevant for multivariate plots (ncol(x) > 1).

par.list

a list of arguments delivered to a call of par to set graphical parameters before plotting. The mfrow splitting is handled per default. Afterwards, the parameters are reverted to their original values. Use par.list=NULL to disable the internal par call.

k

the unit to plot, i.e., an element of 1:ncol(x).

ylim

the y limits of the plot(s). Ignored if same.scale=FALSE.

axes

a logical value indicating whether both axes should be drawn on the plot.

xaxis.tickFreq,xaxis.labelFreq,xaxis.labelFormat

arguments for addFormattedXAxis if epochsAsDate=TRUE. Use xaxis.labelFormat=NULL to get a standard x-axis (without date labels).

epochsAsDate

Boolean indicating whether to treat the epochs as Date objects (or to transform them to dates such that the new x-axis formatting is applied). Default: Value of the epochAsDate slot of x.

xlab

a title for the x axis. See plot.default.

ylab

a title for the y axis. See plot.default.

main

an overall title for the plot: see 'title'.

type

type of plot to do.

lty

vector of length 3 specifying the line type for the three lines in the plot -- see col argument.

col

Vector of length 3 specifying the color to use in the plot. The first color is the fill color of the polygons for the counts bars (NA for unfilled), the 2nd element denotes their border color, the 3rd element is the color of the upperbound plotting.

lwd

Vector of length 3 specifying the line width of the three elements to plot. See also the col argument.

alarm.symbol

a list with entries pch, col, cex and lwd specifying the appearance of the alarm symbol in the plot.

outbreak.symbol

a list with entries pch, col, cex and lwd specifying the appearance of the outbreak symbol in the plot. Currently ignored by stsplot_alarm.

legend.opts

a list of arguments for the legend. If missing(legend.opts) (i.e., not explicitly specified), the default legend will only be added if the "sts" object contains outbreaks, alarms, or upperbounds. The default legend options are

x

"top"

legend

c("Infected","Threshold","Outbreak","Alarm")[included]

lty,lwd,pch,col

the corresponding graphical settings of the included elements

where individual elements are only included in the legend if they are plotted (except for alarms, which are also included if upperbounds exist). To disable the legend, use legend.opts=NULL.

dx.upperbound

horizontal change in the plotting of the upperbound line. Sometimes it can be convenient to offset this line a little for better visibility.

lvl

A vector of length ncol(x), which is used to specify the hierarchy level for each time series in the sts object for alarm plots.

cex.yaxis

The magnification to be used for y-axis annotation.

hookFunc

a function that is called after all the basic plotting has be done, i.e., it is not possible to control formatting with this function. See Examples.

.hookFuncInheritance

a function which is altered by sub-classes plot method. Do not alter this function manually.

...

further arguments for the function matplot. If e.g. xlab or main are provided they overwrite the default values.

Author

Michael Höhle and Sebastian Meyer

Details

The time series plot relies on the work-horse stsplot_time1. Its arguments are (almost) similar to plot.survRes.

See Also

There is an autoplot-method, which implements ggplot2-based time-series plots of "sts" objects.

The stsplot help page gives an overview of other types of plots for "sts" objects.

Examples

data("ha.sts")
print(ha.sts)

plot(ha.sts, type=observed ~ time | unit)  # default multivariate type
plot(ha.sts, units=c("mitt", "pank"))      # selected units
plot(ha.sts, type=observed ~ time)         # aggregated over all districts

## Hook function example
hookFunc <- function() grid(NA,NULL,lwd=1)
plot(ha.sts, hookFunc=hookFunc)

## another multivariate time series example plotted "as.one"
data("measlesDE")
plot(measlesDE, units=1:2, as.one=TRUE, legend.opts=list(cex=0.8))
## more sophisticated plots are offered by package "xts"
if (requireNamespace("xts"))
    plot(as.xts.sts(measlesDE))

## Use ISO8601 date formatting (see ?strptime) and no legend
data("salmNewport")
plot(aggregate(salmNewport,by="unit"), xlab="Time (weeks)",
     xaxis.tickFreq=list("%m"=atChange,"%G"=atChange),
     xaxis.labelFreq=list("%G"=atMedian),xaxis.labelFormat="%G")

## Formatting also works for daily data (illustrated by artificial
## outbreak converted to sts object via 'linelist2sts')
set.seed(123)
exposureTimes <-  as.Date("2014-03-12") + sample(x=0:25,size=99,replace=TRUE)
sts <- linelist2sts(data.frame(exposure=exposureTimes),
                               dateCol="exposure",aggregate.by="1 day")
## Plot it with larger ticks for days than usual
surveillance.options("stsTickFactors"=c("%d"=1, "%W"=0.33,
                "%V"=0.33, "%m"=1.75, "%Q"=1.25, "%Y"=1.5, "%G"=1.5))
plot(sts,xaxis.tickFreq=list("%d"=atChange,"%m"=atChange),
     xaxis.labelFreq=list("%d"=at2ndChange),xaxis.labelFormat="%d-%b",
     xlab="Time (days)")