surveillance (version 1.8-3)

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, method=x@control$name, disease=x@control$data,
             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%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(x="top",legend=NULL,lty=NULL,pch=NULL,col=NULL),
              dx.upperbound=0L, hookFunc=function(){},
              .hookFuncInheritance=function() {}, ...)
stsplot_alarm(x, lvl=rep(1,nrow(x)), ylim=NULL,
              xaxis.tickFreq=list("%Q"=atChange),
              xaxis.labelFreq=xaxis.tickFreq, xaxis.labelFormat="%G%OQ",
              epochsAsDate=x@epochAsDate, xlab="time", main=NULL,
              type="hhs", lty=c(1,1,2), col=c(1,1,4),
              outbreak.symbol=list(pch=3, col=3, cex=1, lwd=1),
              alarm.symbol=list(pch=24, col=2, cex=1, lwd=1),
              cex=1, cex.yaxis=1, ...)
x{an object of class "sts".}
  units{optional integer vector to select the units (=columns of
    observed(x)) to plot. stsplot_time1 is called for
    k in units. The default is to plot all time series.}
  method{name of the surveillance method to be used in the main
    title. Currently ignored.}
  disease{name of the disease to be used in the main title.
    Currently ignored.}
  as.one{logical indicating if all time series should be plotted
    within the same frame. This is currently not implemented
    for the "sts" class, but see plot.disProg and
    sts2disProg.}
  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 before each plot.}
  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{see Details.}
  epochsAsDate{Boolean indicating whether to treat the epochs as
    Date objects. Default: Value of the corresponding slot in 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 argment.}
  alarm.symbol{a list with entries pch, col,
    cex and lwd specifying the appearance of the outbreak
    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.}
  legend.opts{a list containing the entries to be sent to the
  legend function. If no legend is requested use
  legend.opts=NULL. Otherwise, the following arguments are
  default 
    [object Object],[object Object],[object Object],[object Object],[object Object]
    
    Any further arguments to the legend function are
    just provided as additional elements of this list,
    e.g. horiz=TRUE.
  }
  dx.upperbound{horizontal change in the plotting of the
    upperbound line. Sometimes it can be convenient to offset this line
    a little for better visiability.}
  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{A numerical value giving the amount by which plotting text
    and symbols should be magnified relative to the default. See
    ?par for details.}
  cex.yaxis{The magnification to be used for y-axis annotation
    relative to the current setting of 'cex'.}
  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.}
The time series plot relies on the work-horse stsplot_time1.
  Its arguments are (almost) similiar to plot.survRes.
  In case the epochs of the sts object are Date objects it
  is possible to obtain very flexible formatting of the x-axis and its
  annotations using the xaxis.tickFreq, xaxis.labelFreq
  and xaxis.labelFormat. The first two are named lists containing
  pairs with the name being a strftime single
  conversion specification and the second part is a function which based
  on this conversion returns a subset of the rows in the sts
  objects. The subsetting function has the following header:
  function(x,xm1), where x is a vector containing
  the result of applying the conversion in name to the epochs of
  the sts object and xm1 is the scalar result when
  applying the conversion to the natural element just before the first
  epoch.  Three predefined subsetting functions exist:
  atChange, at2ndChange  and atMedian, which 
  are used to make a tick at each (each 2nd for at2ndChange)
  change and at the median index computed on all having the same value,
  respectively: 
  atChange <- function(x,xm1) which(diff(c(xm1,x)) != 0)
    at2ndChange <- function(x,xm1) which(diff(c(xm1,x) %/% 2) != 0)
    atMedian <- function(x,xm1) tapply(seq_along(x), INDEX=x, quantile, prob=0.5, type=3)
  By defining own functions here, one can obtain an arbitrary degree of
  flexibility. 
  Finally, xaxis.labelFormat is a strftime
  compatible formatting string., e.g. the default value is
  "%G\n\n%OQ", which means ISO year and quarter (in roman
  letters) stacked on top of each other.
NULL (invisibly).
  The functions are called for their side-effects.
[object Object],[object Object]
the central stsplot-documentation for an overview of
  plot types.
data("ha.sts")
print(ha.sts)
plot(ha.sts, type=observed ~ time | unit)  # default multivariate type
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)
## 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",
     legend.opts=NULL)
## Formatting now also works for daily data (illustrate by artifical
## outbreak converted to sts object by 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",
     legend.opts=NULL, xlab="Time (days)")
hplot
ts

encoding

latin1