Epi curves

Introduction

Epi curves are fundamental tools in epidemiological surveillance and outbreak investigation. They display the distribution of cases over time, helping identify the source, transmission patterns, and progression of disease outbreaks. The epi_curve() function supports various time periods, grouping options, rolling averages, cumulative lines, and both static and interactive visualizations.

Prerequisites

library(epiviz)
library(dplyr)
library(lubridate)

Example 1: Basic epi curve with rolling average

Basic epi curves with rolling averages help smooth out daily fluctuations and identify underlying trends in surveillance data.

Create the basic epi curve

epi_curve(
  dynamic = FALSE,  # Create static ggplot chart
  params = list(
    df = epiviz::lab_data,
    date_var = "specimen_date",     # Date variable in the dataset
    date_start = "2020-01-01",      # Start date for the curve
    date_end = "2023-12-31",        # End date for the curve
    time_period = "year_month",     # Monthly aggregation
    fill_colours = "#007C91",       # Color for bars
    # Rolling average parameters
    rolling_average_line = TRUE,                    # Include rolling average line
    rolling_average_line_lookback = 3,             # 3-month rolling average
    rolling_average_line_legend_label = "3-month rolling average",  # Legend label
    chart_title = "Laboratory Detections per Month",
    x_axis_title = "Year - Month",
    y_axis_title = "Number of detections",
    x_axis_label_angle = -90
  )
)

Monthly epi curve with a three-month rolling average.

Interpretation: This epi curve shows monthly detections with a 3-month rolling average line that smooths out month-to-month variations to reveal underlying trends.

Example 2: Grouped epi curve with stacked bars

Grouped epi curves allow comparison of different categories (e.g., organism types) over time, showing both individual patterns and overall trends.

Create the grouped epi curve

# Define custom week breaks for better x-axis display
week_seq <- seq(as.Date("2021-01-01"), as.Date("2022-05-31"), by = '2 week')
week_breaks <- paste0(lubridate::isoyear(week_seq), '-W', lubridate::isoweek(week_seq))

epi_curve(
  dynamic = FALSE,  # Create static ggplot chart
  params = list(
    df = epiviz::lab_data,
    date_var = "specimen_date",
    date_start = "2021-01-01",
    date_end = "2022-05-31",
    time_period = "iso_year_week",  # Weekly aggregation using ISO weeks
    group_var = "organism_species_name",  # Group by organism type
    group_var_barmode = "stack",    # Stack bars to show total and composition
    fill_colours = c("KLEBSIELLA PNEUMONIAE" = "#007C91",
                     "STAPHYLOCOCCUS AUREUS" = "#8A1B61",
                     "PSEUDOMONAS AERUGINOSA" = "#FF7F32"),  # Named color mapping
    rolling_average_line = TRUE,
    rolling_average_line_legend_label = "7-week rolling average",
    chart_title = "Laboratory detections by species \n 2021-01 - 2022-05",
    chart_footer = "This chart has been created using simulated data.",
    x_axis_title = "Year - ISO Week",
    y_axis_title = "Number of detections",
    x_axis_label_angle = -90,
    x_axis_break_labels = week_breaks,  # Custom week labels
    y_axis_break_labels = seq(0, 250, 20),  # Custom y-axis breaks
    chart_title_colour = "#007C91",
    chart_footer_colour = "#007C91"
  )
)

Stacked weekly epi curve by organism species with seven-week rolling average.

Interpretation: This stacked epi curve shows both the total weekly detections and the relative contribution of each organism type, revealing patterns in the overall burden and individual organism trends.

Example 3: Daily epi curve with case boxes and cumulative line

Daily epi curves with case boxes and cumulative lines are essential for outbreak investigation, providing detailed temporal resolution and cumulative case tracking.

Create the detailed daily epi curve

epi_curve(
  dynamic = FALSE,  # Create static ggplot chart
  params = list(
    df = epiviz::lab_data,
    date_var = "specimen_date",
    date_start = "2021-06-01",
    date_end = "2021-07-31",
    time_period = "day",            # Daily aggregation for detailed analysis
    group_var = "organism_species_name",
    group_var_barmode = "stack",
    fill_colours = c("#007C91", "#8A1B61", "#FF7F32"),
    # Advanced features
    case_boxes = TRUE,              # Enable case boxes
    rolling_average_line = TRUE,
    rolling_average_line_legend_label = "7-day rolling average",
    cumulative_sum_line = TRUE,     # Add cumulative line
    # Threshold line
    hline = c(35),                  # Threshold value
    hline_label = "Threshold",
    hline_width = 0.5,
    hline_colour = "orange",
    hline_label_colour = "orange",
    hline_type = "dotdash",
    # Styling
    chart_title = "Laboratory detections by species \n June - July 2021",
    chart_title_colour = "#007C91",
    legend_title = "Detected organisms",
    legend_pos = "right",
    y_limit_max = 40,               # Set y-axis maximum
    x_axis_break_labels = as.character(seq(as.Date("2021-06-01"),
                                           as.Date("2021-07-31"),
                                           by = '2 days')),  # Every 2 days
    y_axis_break_labels = seq(0, 40, 5),  # Every 5 units
    x_axis_title = "Date",
    y_axis_title = "Number of detections",
    x_axis_label_angle = -90,
    y_axis_label_angle = 90
  )
)

Daily epi curve with stacked bars, case boxes, cumulative line, and threshold indicator.

Interpretation: This comprehensive daily epi curve includes case boxes for highlighting specific data points, a rolling average for trend identification, a cumulative line for total case tracking, and a threshold line for alert levels.

Example 4: Pre-aggregated data with rolling and cumulative lines

When working with pre-aggregated data, you can still add rolling averages and cumulative lines for trend analysis.

Prepare pre-aggregated data

# Create pre-aggregated data by date
pre_agg_data <- epiviz::lab_data %>%
  group_by(specimen_date) %>%
  summarise(detections = n()) %>%
  ungroup()

Create the pre-aggregated epi curve

epi_curve(
  dynamic = FALSE,  # Create static ggplot chart
  params = list(
    df = pre_agg_data,
    y = "detections",               # Specify the count column
    date_var = "specimen_date",
    date_start = "2021-10-01",
    date_end = "2022-03-31",
    time_period = "iso_year_week",  # Weekly aggregation
    # Rolling and cumulative lines
    rolling_average_line = TRUE,
    rolling_average_line_lookback = 3,
    rolling_average_line_legend_label = "3-week rolling average",
    rolling_average_line_colour = "#007C91",
    rolling_average_line_width = 1.5,
    cumulative_sum_line = TRUE,     # Add cumulative line
    cumulative_sum_line_colour = "orange",
    chart_title = "Laboratory Detections by Region \nWinter 2021-22",
    chart_title_colour = "#007C91",
    legend_pos = "right",
    y_axis_break_labels = seq(0, 300, 50),
    x_axis_title = "ISO Week",
    y_axis_title = "Number of detections",
    x_axis_label_angle = -90,
    hover_labels = "<b>Week:</b> %{x}<br><b>Count:</b> %{y}"  # Custom hover text
  )
)

Weekly epi curve from pre-aggregated counts with rolling average and cumulative total.

Interpretation: This epi curve uses pre-aggregated data with both rolling average and cumulative lines, providing multiple perspectives on the temporal trends in detections.

Example 5: Interactive grouped epi curve

Interactive epi curves are ideal for surveillance dashboards, allowing users to explore data dynamically, zoom into specific time periods, and hover for detailed information.

Create the interactive grouped epi curve

epi_curve(
  dynamic = TRUE,   # Create interactive plotly chart
  params = list(
    df = epiviz::lab_data,
    date_var = "specimen_date",
    date_start = "2021-01-01",
    date_end = "2022-05-31",
    time_period = "iso_year_week",
    group_var = "organism_species_name",
    group_var_barmode = "stack",
    fill_colours = c("KLEBSIELLA PNEUMONIAE" = "#007C91",
                     "STAPHYLOCOCCUS AUREUS" = "#8A1B61",
                     "PSEUDOMONAS AERUGINOSA" = "#FF7F32"),
    rolling_average_line = TRUE,
    rolling_average_line_legend_label = "7-week rolling average",
    chart_title = "Laboratory detections by species \n 2021-01 - 2022-05",
    chart_footer = "This chart has been created using simulated data.",
    x_axis_title = "Year - ISO Week",
    y_axis_title = "Number of detections",
    x_axis_label_angle = -90,
    x_axis_break_labels = week_breaks,
    y_axis_break_labels = seq(0, 250, 20),
    chart_title_colour = "#007C91",
    chart_footer_colour = "#007C91"
  )
)

Interactive stacked epi curve with weekly aggregation and rolling average.

Interpretation: The interactive epi curve allows detailed exploration of weekly patterns, with hover information showing exact values and the ability to zoom into specific time periods for closer analysis.

Tips for epi curves

1. Time period selection: Choose the appropriate time period based on your analysis needs:

   • "day" for outbreak investigation
   • "iso_year_week" for weekly surveillance
   • "year_month" for monthly trends
   • "year" for annual comparisons

2. Rolling averages: Use rolling averages to smooth out fluctuations and identify underlying trends:

   • rolling_average_line_lookback controls the window size
   • Customize colors and line styles for better visibility

3. Cumulative lines: Add cumulative_sum_line = TRUE to track total cases over time, useful for outbreak progression analysis.

4. Case boxes: Enable case_boxes = TRUE for interactive charts to highlight specific data points of interest.

5. Threshold lines: Use hline parameters to add horizontal reference lines for alert levels or outbreak thresholds.

6. Pre-aggregated data: When using pre-aggregated data, specify the y parameter to indicate which column contains the counts.

7. Custom breaks: Use x_axis_break_labels and y_axis_break_labels to control axis tick marks for better readability.

8. Color mapping: Use named color vectors for grouped data to ensure consistent colors across charts.

9. Interactive features: Set dynamic = TRUE for interactive charts with zooming, hovering, and filtering capabilities.

10. Chart styling: Use chart_title_colour and chart_footer_colour to customize text colors and maintain visual consistency.

11. Hover labels: Customize hover_labels for interactive charts to show specific information when hovering over data points.

12. Axis limits: Use y_limit_max to set maximum y-axis values for better focus on relevant data ranges.