Class "sts" – surveillance time series
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.
sts(observed, start = c(2000, 1), frequency = 52,
epoch = NULL, population = NULL, ...)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 |
start,frequency |
basic characteristics of the time series data
just like for simple |
epoch |
observation times, either as an integer sequence (default)
or as a |
population |
a vector of length the number of columns in
|
... |
further named arguments with names corresponding to slot
names (see the list below). For instance, in the public health surveillance context,
the |
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: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: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.
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.
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").
signature(x = "sts"):
see aggregate.sts.
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.
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.
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
showClass("sts")
## 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)
}Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.