Skip to contents

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.


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



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.


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.


observation times, either as an integer sequence (default) or as a Date vector (in which case epochAsDate is automatically set to TRUE).


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.



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.


number of observations per year, e.g., 52 for weekly data, 12 for monthly data.


vector of length two denoting the year and the sample number (week, month, etc.) of the first observation


A 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.


Matrix with the same dimension as observed containing Booleans whether at the specific time point there was an outbreak in the region


Matrix with the same dimension as observed specifying whether an outbreak detection algorithm declared a specific time point in the region as having an alarm.


Matrix with upper bound values


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


A matrix of population fractions or absolute numbers (see multinomialTS below) with dimensions dim(observed).


Object of class SpatialPolygons (or SpatialPolygonsDataFrame) providing a shape of the areas which are monitored.


Object of class list, this is a rather free data type to be returned by the surveillance algorithms.


a Boolean indicating if the epoch slot corresponds to Dates.


a Boolean stating whether to interpret the object as observed out of population, i.e. a multinomial interpretation instead of a count interpretation.


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.


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.


signature(x = "sts"): extract the observed slot.


signature(x = "sts"): extract the alarm slot.


signature(x = "sts"): extract the upperbound slot.


signature(x = "sts"): extract the neighbourhood slot.


signature(x = "sts"): extract the populationFrac slot.


signature(x = "sts"): extract the control slot.


signature(x = "sts"): extract the multinomialTS slot.

Other extraction methods


signature(x = "sts"): extract matrix dimensions of observed. This method also enables nrow(x) and ncol(x).


signature(x = "sts"): extract the dimnames of the observed matrix. This method also enables rownames(x) and colnames(x).


signature(x = "sts"): extract the corresponding year of each observation.


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


signature(x = "sts"): see aggregate.sts.

signature(x = "sts"): the default 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 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.


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.


convert to the xts package format.

Visualization methods


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.


a ggplot2 variant of the standard time-series-type plot, see autoplot.sts.


see animate.sts.


see toLatex.sts.


Michael Höhle and Sebastian Meyer



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

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

## A typical dataset with weekly counts of measles from several districts

## 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")) {
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")

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