R: Class '"sts"' - surveillance time series

sts-class {surveillance}

R Documentation

Class `"sts"` – surveillance time series

Description

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.

For areal time series, the class can also capture the spatial layout of the regions, where the data originate from. The constructor function sts can be used to setup an "sts" object. Conversion of simple time-series objects (of class "ts") is also possible. The slots of the "sts" class and available methods are described below.

Usage

sts(observed, start = c(2000, 1), frequency = 52,
    epoch = NULL, population = 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`	a vector of length the number of columns in `observed` or a matrix of the same dimension as `observed`. Especially for multivariate time series, the population numbers (or fractions) underlying the counts in each unit are relevant for visualization and statistical inference. The `population` argument is an alias for the corresponding slot `populationFrac`. The default `NULL` value sets equal population fractions across all units.
`...`	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.
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 two exceptions: the populationFrac slot is addressed by a population method, and the alarm slot is addressed by an alarms method.

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.
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.
[: 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(s)

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)
}

[Package surveillance version 1.23.0 Index]

Class "sts" – surveillance time series