"sts"
-- surveillance time seriessts-class.Rd
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, ...)
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.
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
: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 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.
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)
}