# Class `"sts"`

– surveillance time series

`sts-class.Rd`

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`Date`

s 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`Date`

s.`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`

.

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