Class

This is a lightweight S4 class to implement (multivariate) time series of counts, typically from public health surveillance. The "sts" class supersedes the informal "disProg" class used in early versions of package surveillance. Converters are available, see disProg2sts.

The constructor function sts can be used to setup an "sts" object. For areal time series, it can also capture a map of the regions, where the counts originate from. See Section “Slots” below for a description of all class components, and Section “Methods” for a list of extraction, conversion and visualization methods.

Usage

sts(observed, start = c(2000, 1), frequency = 52,
    epoch = NULL, population = NULL, map = NULL, ...)

Arguments

observed: a vector (for a single time series) or matrix (one time series per column) of counts. A purely numeric data frame will also do (transformed via as.matrix). This argument sets the observed slot, which is the core element of the resulting "sts" object. It determines the dimensions and colnames for several other slots. The columns (“units”) typically correspond to different regions, diseases, or age groups.
start,frequency: basic characteristics of the time series data just like for simple "ts" objects. The (historical) default values correspond to weekly data starting in the first week of 2000. The epoch and epochInYear methods use the ISO 8601 specification when converting between week numbers and dates, see isoWeekYear.
epoch: observation times, either as an integer sequence (default) or as a Date vector (in which case epochAsDate is automatically set to TRUE).
population: the population sizes (or fractions) underlying the observed counts, especially relevant for multivariate time series (for incidence maps or as offsets in epidemic models). If assumed constant over time, population can be supplied as a vector of length the number of columns (regions, groups, etc.) in observed. Otherwise, population needs to be a matrix of the same dimension as observed. The population argument is an alias for the corresponding slot populationFrac. The default NULL value sets equal population fractions across all units.
map: optional spatial data representing the regions, either of class "SpatialPolygons" (or "SpatialPolygonsDataFrame") or of class "sf" (requires package sf). Its row.names() must contain the region IDs to be matched against colnames(observed).
...: further named arguments with names corresponding to slot names (see the list below). For instance, in the public health surveillance context, the state slot is used to indicate outbreaks (default: FALSE for all observations). For areal time series data, the map and neighbourhood slots are used to store the spatial structure of the observation region.

Slots

epoch:: a numeric vector specifying the time of observation, typically a week index. Depending on the freq slot, it could also index days or months. Furthermore, if epochAsDate=TRUE then epoch is the integer representation of Dates giving the exact date of the observation.
freq:: number of observations per year, e.g., 52 for weekly data, 12 for monthly data.
start:: vector of length two denoting the year and the sample number (week, month, etc.) of the first observation.
observed:: matrix of size length(epoch) times the number of regions containing the weekly/monthly number of counts in each region. The colnames of the matrix should match the ID values of the shapes in the map slot.
state:: matrix with the same dimensions as observed containing Booleans whether at the specific time point there was an outbreak in the region.
alarm:: matrix with the same dimensions as observed specifying whether an outbreak detection algorithm declared a specific time point in the region as having an alarm.
upperbound:: matrix with upper-bound values.
neighbourhood:: symmetric matrix of size \((number of regions)^2\) describing the neighbourhood structure. It may either be a binary adjacency matrix or contain neighbourhood orders (see the Examples for how to infer the latter from the map).
populationFrac:: matrix of population fractions or absolute numbers (see multinomialTS below) with dimensions dim(observed).
map:: object of class "SpatialPolygons" (or "SpatialPolygonsDataFrame") providing a shape of the areas which are monitored or modelled.
control:: list of settings; this is a rather free data type to be returned by the surveillance algorithms.
epochAsDate:: a Boolean indicating if the epoch slot corresponds to Dates.
multinomialTS:: a Boolean stating whether to interpret the object as observed out of population, i.e. a multinomial interpretation instead of a count interpretation.

Methods

Extraction of slots

There is an extraction (and replacement) method for almost every slot. The name of the method corresponds to the slot name, with three exceptions: the freq slot can be extracted by frequency(), the populationFrac slot is accessed by population(), and the alarm slot is accessed by alarms().

epoch: signature(x = "sts"): extract the epoch slot. If the sts object is indexed by dates (epochAsDate = TRUE), the returned vector is of class Date, otherwise numeric (usually the integer sequence 1:nrow(x)).
By explicitly requesting epoch(x, as.Date = TRUE), dates can also be extracted if the sts object is not internally indexed by dates but has a standard frequency of 12 (monthly) or 52 (weekly). The transformation is based on start and freq and will return the first day of each month (freq=12) and the Monday of each week (freq=52), respectively.
frequency: signature(x = "sts"): extract the freq slot.
start: signature(x = "sts"): extract the start slot.
observed: signature(x = "sts"): extract the observed slot.
alarms: signature(x = "sts"): extract the alarm slot.
upperbound: signature(x = "sts"): extract the upperbound slot.
neighbourhood: signature(x = "sts"): extract the neighbourhood slot.
population: signature(x = "sts"): extract the populationFrac slot.
control: signature(x = "sts"): extract the control slot.
multinomialTS: signature(x = "sts"): extract the multinomialTS slot.

Other extraction methods

dim: signature(x = "sts"): extract matrix dimensions of observed. This method also enables nrow(x) and ncol(x).
dimnames: signature(x = "sts"): extract the dimnames of the observed matrix. This method also enables rownames(x) and colnames(x).
year: signature(x = "sts"): extract the corresponding year of each observation.
epochInYear: signature(x = "sts"): extract the epoch number within the year. This corresponds to cycle(as.ts(x)).
[: signature(x = "sts"): subset rows (time points) and/or columns (units), see help("[,sts-method").

Transformation methods

aggregate: signature(x = "sts"): see aggregate.sts.
as.data.frame: signature(x = "sts"): the default as.data.frame call will collect the following slots into a data frame: observed, epoch, state, alarm, upperbound, and populationFrac. Additional columns will be created for freq (potentially varying by year for weekly or daily data if x@epochAsDate is TRUE) and epochInPeriod (the epoch fraction within the current year).
Calling the as.data.frame method with the argument tidy = TRUE will return tidy.sts(x), which reshapes multivariate sts objects to the “long” format (one row per epoch and observational unit). The tidy format is particularly useful for standard regression models and customized plotting.
coerce: signature(from="sts", to="ts") and signature(from="ts", to="sts"), to be called via as(stsObj, "ts") (or as.ts(stsObj)) and as(tsObj, "sts"), respectively.
as.xts: convert to the xts package format.

Visualization methods

plot: signature(x = "sts", y = "missing"): entry point to a collection of plot variants. The type of plot is specified using a formula, see plot.sts for details.
autoplot: a ggplot2 variant of the standard time-series-type plot, see autoplot.sts.
animate: see animate.sts.
toLatex: see toLatex.sts.

Author

Michael Höhle and Sebastian Meyer

Examples

showClass("sts")

## create an sts object from time-series data
salmonellaDF <- read.table(system.file("extdata/salmonella.agona.txt",
                                       package = "surveillance"), header = TRUE)
str(salmonellaDF)
salmonella <- with(salmonellaDF,
                   sts(observed = observed, state = state,
                       start = c(1990, 1), frequency = 52))
salmonella
plot(salmonella)

## these data are also available as a legacy "disProg" object in the package
data(salmonella.agona)
stopifnot(all.equal(salmonella, disProg2sts(salmonella.agona)))


## A typical dataset with weekly counts of measles from several districts
data("measlesWeserEms")
measlesWeserEms

## reconstruct data("measlesWeserEms") from its components
counts <- observed(measlesWeserEms)
map <- measlesWeserEms@map
populationFrac <- population(measlesWeserEms)
weserems_nbOrder <- neighbourhood(measlesWeserEms)
## orders of adjacency can also be determined from the map
if (requireNamespace("spdep")) {
    stopifnot(identical(weserems_nbOrder,
                        nbOrder(poly2adjmat(map))))
}
mymeasles <- sts(counts, start = c(2001, 1), frequency = 52,
                 population = populationFrac,
                 neighbourhood = weserems_nbOrder, map = map)
stopifnot(identical(mymeasles, measlesWeserEms))

## convert ts/mts object to sts
z <- ts(matrix(rpois(300,10), 100, 3), start = c(1961, 1), frequency = 12)
z.sts <- as(z, "sts")
plot(z.sts)

## conversion of "sts" objects to the quasi-standard "xts" class
if (requireNamespace("xts")) {
    z.xts <- as.xts.sts(z.sts)
    plot(z.xts)
}

Class "sts" – surveillance time series