incidence.Rd
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.
incidence(dates, interval = 1L, ...) # S3 method for default incidence(dates, interval = 1L, ...) # S3 method for Date incidence(dates, interval = 1L, standard = TRUE, groups = NULL, na_as_group = TRUE, first_date = NULL, last_date = NULL, ...) # S3 method for character incidence(dates, interval = 1L, standard = TRUE, groups = NULL, na_as_group = TRUE, first_date = NULL, last_date = NULL, ...) # S3 method for integer incidence(dates, interval = 1L, groups = NULL, na_as_group = TRUE, first_date = NULL, last_date = NULL, ...) # S3 method for numeric incidence(dates, interval = 1L, groups = NULL, na_as_group = TRUE, first_date = NULL, last_date = NULL, ...) # S3 method for POSIXt incidence(dates, interval = 1L, standard = TRUE, groups = NULL, na_as_group = TRUE, first_date = NULL, last_date = NULL, ...) # S3 method for incidence print(x, ...)
dates | A vector of dates, which can be provided as objects of the
class: integer, numeric, Date, POSIXct, POSIXlt, and character. (See Note
about |
---|---|
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 |
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 |
x | An 'incidence' object. |
An list with the class incidence
, which contains the
following items:
dates: The dates marking the left side of the bins used for counting events. When ISO week-based weekly incidence is computed, the dates are the first days of corresponding isoweeks.
counts: A matrix of incidence counts, which one column per group (and a single column if no groups were used).
timespan: The length of the period for which incidence is computed, in days.
interval: The bin size, in number of days; e.g. 7 indicates weekly incidence.
n: The total number of cases.
isoweeks: ISO 8601 week format yyyy-Www, which is returned only when ISO week-based weekly incidence is computed.
For details about the incidence class
, see the dedicated
vignette:
vignette("incidence_class", package = "incidence")
dates
)Decimal (numeric) dates: will be truncated with a warning
Character dates should be in the unambiguous yyyy-mm-dd
(ISO 8601)
format. Any other format will trigger an error.
interval
)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:
"week" : first day of the ISOweek (i.e. Monday, 2018-05-07)
"month" : first day of the month (i.e. 2018-05-01)
"quarter" : first day of the quarter (i.e. 2018-04-01)
"year" : first day of the calendar year (i.e. 2018-01-01)
Specify standard = FALSE
, which sets the interval to begin at the first
observed case.
Specify a date in the first_date
field.
The main other functions of the package include:
incidence::plot.incidence()
: Plot epicurves from an incidence object.
incidence::fit()
: Fit log-linear model to computed incidence.
incidence::fit_optim_split()
: Find the optimal peak of the epidemic
and fits log-linear models on either side of the peak.
incidence::subset()
: Handling of incidence
objects.
incidence::pool()
: Sum incidence over groups.
incidence::as.data.frame.incidence()
: Convert an incidence
object to a
data.frame
.
The following vignettes are also available:
overview
: Provides an overview of the package's features.
customize_plot
: Provides some tips on finer plot customization.
incidence_class
: Details the content of the incidence
class.
#> <incidence object> #> [10 cases from days 1 to 9] #> #> $counts: matrix with 9 rows and 1 columns #> $n: 10 cases in total #> $dates: 9 dates marking the left-side of bins #> $interval: 1 day #> $timespan: 9 days #> $cumulative: FALSE #>#> <incidence object> #> [10 cases from days 1 to 9] #> #> $counts: matrix with 5 rows and 1 columns #> $n: 10 cases in total #> $dates: 5 dates marking the left-side of bins #> $interval: 2 days #> $timespan: 9 days #> $cumulative: FALSE #>## 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 })}#> > onset <- ebola_sim$linelist$date_of_onset #> > inc <- incidence(onset) #> > inc #> <incidence object> #> [5888 cases from days 2014-04-07 to 2015-04-30] #> #> $counts: matrix with 389 rows and 1 columns #> $n: 5888 cases in total #> $dates: 389 dates marking the left-side of bins #> $interval: 1 day #> $timespan: 389 days #> $cumulative: FALSE #> #> > plot(inc)#> > inc.week <- incidence(onset, interval = 7, standard = FALSE) #> > inc.week #> <incidence object> #> [5888 cases from days 2014-04-07 to 2015-04-27] #> #> $counts: matrix with 56 rows and 1 columns #> $n: 5888 cases in total #> $dates: 56 dates marking the left-side of bins #> $interval: 7 days #> $timespan: 386 days #> $cumulative: FALSE #> #> > plot(inc.week)#> > plot(inc.week, border = "white")#> > inc.isoweek <- incidence(onset, interval = 7, standard = TRUE) #> > inc.isoweek #> <incidence object> #> [5888 cases from days 2014-04-07 to 2015-04-27] #> [5888 cases from ISO weeks 2014-W15 to 2015-W18] #> #> $counts: matrix with 56 rows and 1 columns #> $n: 5888 cases in total #> $dates: 56 dates marking the left-side of bins #> $interval: 7 days #> $timespan: 386 days #> $cumulative: FALSE #> #> > sex <- ebola_sim$linelist$gender #> > inc.week.gender <- incidence(onset, interval = 7, groups = sex, standard = FALSE) #> > inc.week.gender #> <incidence object> #> [5888 cases from days 2014-04-07 to 2015-04-27] #> [2 groups: f, m] #> #> $counts: matrix with 56 rows and 2 columns #> $n: 5888 cases in total #> $dates: 56 dates marking the left-side of bins #> $interval: 7 days #> $timespan: 386 days #> $cumulative: FALSE #> #> > head(inc.week.gender$counts) #> f m #> [1,] 1 0 #> [2,] 0 1 #> [3,] 4 1 #> [4,] 4 0 #> [5,] 9 3 #> [6,] 8 10 #> > plot(inc.week.gender)#> > inc.isoweek.gender <- incidence(onset, interval = 7, groups = sex, standard = TRUE) #> > inc.isoweek.gender #> <incidence object> #> [5888 cases from days 2014-04-07 to 2015-04-27] #> [5888 cases from ISO weeks 2014-W15 to 2015-W18] #> [2 groups: f, m] #> #> $counts: matrix with 56 rows and 2 columns #> $n: 5888 cases in total #> $dates: 56 dates marking the left-side of bins #> $interval: 7 days #> $timespan: 386 days #> $cumulative: FALSE #>