surveillance (version 1.24.0)

sts-class: 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.

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

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.

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.

[

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