stsplot_time function

Time-Series Plots for "sts" Objects

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

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

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.

Details

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

Returns

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

Author(s)

Michael H hle and Sebastian Meyer

See Also

There is an autoplot-method, which implements list("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)")