incidence: Compute incidence of events from a vector of dates.

Description Usage Arguments Details Value Note Author(s) See Also Examples

View source: R/incidence.R

Description

This function computes incidence based on dates of events provided in various formats. A fixed interval, provided as numbers of days, is used to define time intervals. Counts within an interval always include the first date, after which they are labeled, and exclude the second. For instance, intervals labeled as 0, 3, 6, ... mean that the first bin includes days 0, 1 and 2, the second interval includes 3, 4 and 5 etc.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
incidence(dates, interval = 1L, ...)

## Default S3 method:
incidence(dates, interval = 1L, ...)

## S3 method for class 'Date'
incidence(dates, interval = 1L, standard = TRUE,
  groups = NULL, na_as_group = TRUE, first_date = NULL,
  last_date = NULL, ...)

## S3 method for class 'integer'
incidence(dates, interval = 1L, groups = NULL,
  na_as_group = TRUE, first_date = NULL, last_date = NULL, ...)

## S3 method for class 'numeric'
incidence(dates, interval = 1L, groups = NULL,
  na_as_group = TRUE, first_date = NULL, last_date = NULL, ...)

## S3 method for class 'POSIXt'
incidence(dates, interval = 1L, standard = TRUE,
  groups = NULL, na_as_group = TRUE, first_date = NULL,
  last_date = NULL, ...)

## S3 method for class 'incidence'
print(x, ...)

Arguments

dates

A vector of dates, which can be provided as objects of the class: integer, numeric, Date, POSIXct. Note that decimal numbers will be floored with a warning.

interval

An integer or character indicating the (fixed) size of the time interval used for computing the incidence; defaults to 1 day. This can also be a text string that corresponds to a valid date interval: day, week, month, quarter, or year. See Note.

...

Additional arguments passed to other methods (none are used).

standard

(Only applicable to Date objects) When TRUE (default) and the interval one of "week", "month", "quarter", or "year", then this will cause the bins for the counts to start at the beginning of the interval (See Note). This is overridden by defining a non-NULL first_date.

groups

An optional factor defining groups of observations for which incidence should be computed separately.

na_as_group

A logical value indicating if missing group (NA) should be treated as a separate group.

first_date, last_date

optional first/last dates to be used in the epicurve. When these are NULL (default), the dates from the first/last dates are taken from the observations. If these dates are provided, the observations will be trimmed to the range of [first_date, last_date].

x

An 'incidence' object.

Details

For details about the incidence class, see the dedicated vignette:
vignette("incidence_class", package = "incidence")

Value

An list with the class incidence, which contains the following items:

Note

If interval is a valid character (e.g. "week" or "month"), then the bin will start at the beginning of the interval just before the first observation by default. For example, if the first case was recorded on Wednesday, 2018-05-09:

These default intervals can be overridden in two ways:

  1. Specify standard = FALSE, which sets the interval to begin at the first observed case.

  2. Specify a date in the first_date field.

The intervals for "month", "quarter", and "year" will necessarily vary in the number of days they encompass and warnings will be generated when the first date falls outside of a calendar date that is easily represented across the interval.

Author(s)

Thibaut Jombart, Rich Fitzjohn, Zhian Kamvar

See Also

The main other functions of the package include:

The following vignettes are also available:

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
## toy example
incidence(c(1, 5, 8, 3, 7, 2, 4, 6, 9, 2))
incidence(c(1, 5, 8, 3, 7, 2, 4, 6, 9, 2), 2)

## example using simulated dataset
if(require(outbreaks)) { withAutoprint({
  onset <- ebola_sim$linelist$date_of_onset

  ## daily incidence
  inc <- incidence(onset)
  inc
  plot(inc)

  ## weekly incidence
  inc.week <- incidence(onset, interval = 7, standard = FALSE)
  inc.week
  plot(inc.week)
  plot(inc.week, border = "white") # with visible border
  inc.isoweek <- incidence(onset, interval = 7, standard = TRUE)
  inc.isoweek
  ## use group information
  sex <- ebola_sim$linelist$gender
  inc.week.gender <- incidence(onset, interval = 7,
                               groups = sex, standard = FALSE)
  inc.week.gender
  head(inc.week.gender$counts)
  plot(inc.week.gender)
  inc.isoweek.gender <- incidence(onset, interval = 7,
                                  groups = sex, standard = TRUE)
  inc.isoweek.gender
})}

incidence documentation built on Nov. 30, 2018, 4:23 p.m.