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

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, the epoch slot is used to store the observation time, either as an integer sequence (default) or as the numeric representation of Dates (if also epochAsDate=TRUE). 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:

Object of class numeric or specifying the time of observation. In old versions of the package this used to be the week numbers. However, depending on the freq argument, it can now be day or month as well. Furthermore, if epochAsDate=TRUE then it is the as.numeric representation of Date objects giving the exact date of the observation. Note: This slot used to be called week in earlier versions of the package, but has now been renamed to reflect the greater flexibility in the choice of observation time.

freq:

If weekly data freq corresponds to 52, in case of monthly data freq is 12.

start:

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

observed:

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.

state:

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

alarm:

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.

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:

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

map:

Object of class SpatialPolygonsDataFrame providing a shape of the areas which are monitored.

control:

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

epochAsDate:

Object of class "logical" stating whether to use a ISO 8601 representation of the epoch slot using the Date class (epochAsDate=TRUE) or just to interpret the epochs as numerics (epochAsDate=FALSE).

multinomialTS:

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

Methods

dim

signature(x = "sts"): extract matrix dimensions of observed.

dimnames

signature(x="sts"): extract the dimnames of the observed matrix.

observed

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

population

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

multinomialTS

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

neighbourhood

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

alarms

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

upperbound

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

control

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

epoch

signature(x = "sts"): extract the epoch slot of an sts object. If ISO dates are used then the returned object is of class Date.

epochInYear

signature(x = "sts"): Returns the epoch number within the year of the epoch slot.

initialize

signature(x="sts"): the internal function init.sts is called, which assigns all slots.

[

subsetting "sts" objects, see [,sts-method.

aggregate

signature(x="sts"): see aggregate,sts-method

year

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

as.data.frame

signature(x = "sts"): converts the observed, epoch, state and alarm slots of x into a data frame with column names matching the colnames of the respective slots. Useful when one wants to fit a model based on the object

plot

signature(x="sts",y="missing"): this method is the entry point to a collection of plot variants. It is also the successor of the plot.disProg and plot.survRes functions. The type of plot is specified using a formula type. See stsplot for details.

animate

see animate.sts.

coerce

signature(from="sts", to="ts") (can also be called via the S3 generic as.ts) and the reverse signature(from="ts", to="sts").

toLatex

see toLatex,sts-method.

Author(s)

Michael Höhle and Sebastian Meyer

Examples

## 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), maxlag = 10)))
}
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.16.1 Index]