Incidence: A Robust Tool for Epidemic Curve Analysis

The philosophy underpinning the development of
incidence is to ‘do the basics well’. The objective of this package is to provide simple, user-friendly and robust tools for computing, manipulating, and plotting epidemic curves, with some additional facilities for basic models of incidence over time.
The general workflow (
Figure 1) revolves around a single type of object, formalised as the S3 class
incidence.
incidence objects are lists storing separately a matrix of case counts (with dates in rows and groups in columns), dates used as breaks, the time interval used, and an indication of whether incidence is cumulative or not (
Figure 1). The
incidence object is obtained by running the function
incidence() specifying two inputs: a vector of dates (representing onset of individual cases) and an interval specification. The dates can be any type of input representing dates including
Date and
POSIXct objects, as well as numeric and integer values. The dates are aggregated into counts based on the user-defined interval representing the number of days for each bin. The interval can also be defined as a text string of either "week", "month", "quarter", or "year" to represent intervals that can not be defined by a fixed number of days. For these higher-level intervals, an extra parameter—
standard—is available to specify if the interval should start at the standard beginning of the interval (e.g. weeks start on Monday and months start at the first of the month).
incidence() also accepts a
groups argument which can be used to obtain stratified incidence. The basic elements of the
incidence object can be obtained by the accessors
get_counts(),
get_dates(), and
get_interval().
This package facilitates the manipulation of
incidence objects by providing a set of handler functions for the most common tasks. The function
subset() can be used for isolating case data from a specific time window and/or groups, while the [ operator can be used for a finer control to subset dates and groups using integer, logical or character vectors. This is accomplished by using the same syntax as for matrix and data.frame objects, i.e.
x[i, j] where
x is the
incidence object, and
i and
j are subsets of dates and groups, respectively.
The function
pool() can be used to merge several groups into one, and the function
cumulate() will turn incidence data into cumulative incidence. To maximize interoperability,
incidence objects can also be exported to either a matrix using
get_counts() or a data.frame using
as.data.frame(), including an option for a ‘long’ format which is readily compatible with
ggplot2 (
Wickham, 2016 ) for further customization of graphics.
In line with RECON’s development guidelines, the
incidence package is thoroughly tested via automatic tests implemented using
testthat (
Wickham, 2011 ), with an overall coverage nearing 100% at all times. We use the continuous integration services
travis.ci and
appveyor to ensure that new versions of the code maintain all existing functionalities and give expected results on known datasets, including matching reference graphics tested using the visual regression testing implemented in
vdiffr (
Henry
et al., 2018). Overall, these practices aim to maximise the reliability of the package, and its sustainable development and maintenance over time.