Introducing incidence2

Compute, handle and visualise epicurves.

Tim Taylor

It’s been a few months since our first post, ‘Welcome to the reconverse’, and, coinciding with the release of version 1.2.0, we thought it a good time to introduce you to the incidence2 package (Taylor 2021b).


During a disease outbreak it is important to collect some basic information on cases in a line list; a data structure where each entry describes a unique individual in an epidemiological context. Line lists are typically in a tabular format where each row is an individual with a unique ID, meta-data describing the individual which are fixed in time (e.g., age, sex, occupation, disease outcome) and time-stamped measurements (e.g., date of onset, date of admission, date of disease outcome).

To better understand an outbreak, line lists are often aggregated to produce epidemic curves (epicurves); graphs representing the number of new cases over a given time interval (e.g. days, weeks, months). The process to convert a line list to an epicurve typically involves four stages:

  1. Data cleaning
  2. Time standardisation
  3. Aggregation
  4. Visualisation

To assist with the computing and visualisation of epicurves (stages 2 to 4), the incidence (Kamvar et al. 2019) package was created. Here the term incidence was used to refer to the underlying, aggregated data, not the rate of incidence. Whilst this original implementation worked well it did have some limitations:

incidence2 is a re-imagining of the original package, built to address these limitations.


With incidence2, incidence objects are constructed as a subclass of tibble (Müller and Wickham 2021), where the following class invariants1 hold true:

The names of the columns representing the time index, counts, groups and associated measurements are then stored as as attributes of the object.

By building incidence objects on tibbles (which themselves build upon data frames) we benefit from the rich support for these data structures that is present within both ‘base’ R and the wider package ecosystem.

When constructing incidence objects input can be given as either line list or pre-aggregated data and users have the option to use an “opinionated” approach to date grouping (built on top of the grates package (Taylor 2021a)) or to specify there own date grouping function.

How to use


To illustrate the main package functionality we give two simple examples. The first example of these uses synthetic line list data from the outbreaks package (Jombart et al. 2020) whilst the second example downloads some Covid-19 case data from the UK’s National Health Service via the covidregionaldata package (Palmer et al. 2021).

Required packages

library(outbreaks)         # for example 1
library(covidregionaldata) # for example 2

Example 1 - Line list data

# get the linelist data
dat <- ebola_sim_clean$linelist

# a quick visualising the daily onsets
dat |> incidence(date_of_onset) |> plot()
# calculate the epiweek incidence across hospitals and plot
dat |> 
    date_index = date_of_onset,
    groups = hospital,
    interval = "epiweek",
    na_as_group = FALSE
  ) |> 
  print() |> 
  facet_plot(nrow = 3, color = "white")
An incidence object: 262 x 3
date range: [2014-W15] to [2015-W17]
cases: 4373
interval: 1 (Sunday) week 

   date_index hospital                                     count
       <yrwk> <fct>                                        <int>
 1   2014-W15 Military Hospital                                1
 2   2014-W16 Connaught Hospital                               1
 3   2014-W17 other                                            3
 4   2014-W18 Connaught Hospital                               1
 5   2014-W18 Princess Christian Maternity Hospital (PCMH)     1
 6   2014-W18 Rokupa Hospital                                  1
 7   2014-W19 Connaught Hospital                               3
 8   2014-W19 Military Hospital                                4
 9   2014-W19 other                                            1
10   2014-W19 Princess Christian Maternity Hospital (PCMH)     1
# … with 252 more rows

Example 2 - Pre-aggregated data

# get the data and filter out the nations
dat <- get_regional_data(country = "UK", verbose = FALSE)
nations <- c("England", "Northern Ireland", "Scotland", "Wales")
dat <- subset(dat, !region %in% nations)

# calculate iso-weekly new cases across regions and plot
dat |> 
    date_index = date,
    counts = cases_new,
    groups = region,
    interval = "isoweek",
    na_as_group = FALSE
  ) |> 
  print() |> 
  facet_plot(angle = 45, n.breaks = 6)
An incidence object: 693 x 3
date range: [2020-W05] to [2021-W28]
cases_new: 4509597
interval: 1 (Monday) week 

   date_index region                   cases_new
       <yrwk> <chr>                        <dbl>
 1   2020-W05 East Midlands                    0
 2   2020-W05 East of England                  0
 3   2020-W05 London                           0
 4   2020-W05 North East                       0
 5   2020-W05 North West                       0
 6   2020-W05 South East                       0
 7   2020-W05 South West                       0
 8   2020-W05 West Midlands                    0
 9   2020-W05 Yorkshire and The Humber         1
10   2020-W06 East Midlands                    0
# … with 683 more rows

Final thoughts

Hopefully this short post gave you a taster of what incidence2 is about and why it is useful. For more information, including details on manipulating incidence objects, customizing the default plots, and using custom functions for date grouping, I recommend consulting the vignettes distributed with the package:

Jombart, Thibaut, Simon Frost, Pierre Nouvellet, Finlay Campbell, and Bertrand Sudre. 2020. Outbreaks: A Collection of Disease Outbreak Data.

Kamvar, Zhian N., Jun Cai, Juliet R. C. Pulliam, Jakob Schumacher, and Thibaut Jombart. 2019. “Epidemic Curves Made Easy Using the R Package Incidence.” F1000Research 8 (January): 139.

Müller, Kirill, and Hadley Wickham. 2021. Tibble: Simple Data Frames.

Palmer, Joseph, Katharine Sherratt, Richard Martin-Nielsen, Jonnie Bevan, Hamish Gibbs, Sebastian Funk, and Sam Abbott. 2021. “Covidregionaldata: Subnational Data for Covid-19 Epidemiology.” Journal of Open Source Software 6 (62): 3290.

Taylor, Tim. 2021a. Grates: Grouped Date Classes.

———. 2021b. Incidence2: Compute, Handle and Plot Incidence of Dated Events.

  1. structural information that must remain true for an object to maintain its class when operated on↩︎



Text and figures are licensed under Creative Commons Attribution CC BY 4.0. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".


For attribution, please cite this work as

Taylor (2021, July 13). Reconverse: Introducing incidence2. Retrieved from

BibTeX citation

  author = {Taylor, Tim},
  title = {Reconverse: Introducing incidence2},
  url = {},
  year = {2021}