surveillance: stsplot_time – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

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,nrow(x)), ylim=NULL,
              xaxis.tickFreq=list("%Q"=atChange),
              xaxis.labelFreq=xaxis.tickFreq, xaxis.labelFormat="%G\n\n%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, ...)

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 `par`ameters 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`	see `addFormattedXAxis`.
`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 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 of arguments for `legend`. If `missing(legend.opts)` (i.e., not explicitly specified), the default legend will only be produced if `x` contains any information on outbreaks, alarms, or upperbounds. To disable the legend, use, e.g., `legend.opts=NULL`. Otherwise, the following arguments are default: `x` `"top"` `legend` `c("Infected","Threshold","Outbreak","Alarm")` `lty,pch,col` the corresponding graphical settings 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 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`	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.

Details

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

Value

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

Author(s)

Michael Höhle and Sebastian Meyer

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 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",
     xlab="Time (days)")

surveillance

Temporal and Spatio-Temporal Modeling and Monitoring of Epidemic Phenomena

v1.19.1

GPL-2

Authors

Michael H<f6>hle [aut, ths] (<https://orcid.org/0000-0002-0423-6702>), Sebastian Meyer [aut, cre] (<https://orcid.org/0000-0002-1791-9449>), Michaela Paul [aut], Leonhard Held [ctb, ths], Howard Burkom [ctb], Thais Correa [ctb], Mathias Hofmann [ctb], Christian Lang [ctb], Juliane Manitz [ctb], Andrea Riebler [ctb], Daniel Saban<e9>s Bov<e9> [ctb], Ma<eb>lle Salmon [ctb], Dirk Schumacher [ctb], Stefan Steiner [ctb], Mikko Virtanen [ctb], Wei Wei [ctb], Valentin Wimmer [ctb], R Core Team [ctb] (A few code segments are modified versions of code from base R)

Initial release

2021-03-30