ggsurveillance (version 0.2.0)

geom_epicurve: Create an epidemic curve plot or bin/count observations by date periods

Description

Creates a epicurve plot for visualizing epidemic case counts in outbreaks (epidemiological curves). An epicurve is a bar plot, where every case is outlined. geom_epicurve additionally provides date-based aggregation of cases (e.g. per week or month and many more).

• For week aggregation both isoweek (World + ECDC) and epiweek (US CDC) are supported.

• stat_bin_date and its alias stat_date_count provide date based binning only. After binning the by date, these stats behave like ggplot2::stat_count.

Usage

geom_epicurve(
  mapping = NULL,
  data = NULL,
  stat = "epicurve",
  position = "stack",
  date_resolution = NULL,
  week_start = getOption("lubridate.week.start", 1),
  width = NULL,
  relative.width = 1,
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)
stat_bin_date(
  mapping = NULL,
  data = NULL,
  geom = "line",
  position = "identity",
  date_resolution = NULL,
  week_start = getOption("lubridate.week.start", 1),
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)
stat_date_count(
  mapping = NULL,
  data = NULL,
  geom = "line",
  position = "identity",
  date_resolution = NULL,
  week_start = getOption("lubridate.week.start", 1),
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Value

A ggplot2 geom layer that can be added to a plot

Arguments

mapping

Set of aesthetic mappings created by aes. Commonly used mappings:

• x or y: date or datetime. Numeric is technically supported.

• fill: for colouring groups

• weight: if data is already aggregated (e.g. case counts)

data

The data frame containing the variables for the plot

stat

either "epicurve" for outlines around cases or "bin_date" for outlines around (fill) groups. For large numbers of cases please use "bin_date" to reduce the number of drawn rectangles.

position

Position adjustment. Currently supports "stack" for geom_epicurve().

date_resolution

Character string specifying the time unit for date aggregation. Set to NULL or NA for no date aggregation
Possible values are: "day", "week", "month", "bimonth", "season", "quarter", "halfyear", "year". To special values enforce ISO or US week standard:

• isoweek will force dadte_resolution = week and week_start = 1 (ISO and ECDC Standard)

• epiweek will force date_resolution = week and week_start = 7 (US CDC Standard)

week_start

Integer specifying the start of the week (1 = Monday, 7 = Sunday).
Only used when date_resolution includes weeks. Defaults to 1 (Monday).
For isoweek use week_start = 1 and for epiweek use week_start = 7.

width

Numeric value specifying the width of the bars. If NULL, calculated based on resolution and relative.width

relative.width

Numeric value between 0 and 1 adjusting the relative width of bars. Defaults to 1

...

Other arguments passed to layer. For example:

• colour Colour of the outlines around cases. Disable with colour = NA. Defaults to "white".

• linewidth Width of the case outlines.

na.rm

If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.

show.legend

logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display.

inherit.aes

If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. borders().

geom

The geometric object to use to display the data for this layer. When using a stat_*() function to construct a layer, the geom argument can be used to override the default coupling between stats and geoms.

Details

Epi Curves are a public health tool for outbreak investigation. For more details see the references.

References

• Centers for Disease Control and Prevention. Quick-Learn Lesson: Using an Epi Curve to Determine Mode of Spread. USA. https://www.cdc.gov/training/quicklearns/epimode/

• Dicker, Richard C., Fátima Coronado, Denise Koo, and R. Gibson Parrish. 2006. Principles of Epidemiology in Public Health Practice; an Introduction to Applied Epidemiology and Biostatistics. 3rd ed. USA. https://stacks.cdc.gov/view/cdc/6914

See Also

scale_y_cases_5er(), geom_vline_year()

Examples

# Basic epicurve with dates
library(ggplot2)
set.seed(1)

plot_data_epicurve_imp <- data.frame(
  date = rep(as.Date("2023-12-01") + ((0:300) * 1), times = rpois(301, 0.5))
)

ggplot(plot_data_epicurve_imp, aes(x = date, weight = 2)) +
  geom_vline_year(year_break = "01-01", show.legend = TRUE) +
  geom_epicurve(date_resolution = "week") +
  labs(title = "Epicurve Example") +
  scale_y_cases_5er() +
  scale_x_date(date_breaks = "4 weeks", date_labels = "W%V'%g") + # Correct ISOWeek labels week'year
  coord_equal(ratio = 7) + # Use coord_equal for square boxes. 'ratio' are the days per week.
  theme_bw()

# Categorical epicurve
library(tidyr)
library(outbreaks)

sars_canada_2003 |> # SARS dataset from outbreaks
  pivot_longer(starts_with("cases"), names_prefix = "cases_", names_to = "origin") |>
  ggplot(aes(x = date, weight = value, fill = origin)) +
  geom_epicurve(date_resolution = "week") +
  scale_x_date(date_labels = "W%V'%g", date_breaks = "2 weeks") +
  scale_y_cases_5er() +
  theme_classic()