epi_curve — epi_curve • epiviz

A function for producing either a static (ggplot) or dynamic (plotly) epidemic curve.

Usage

epi_curve(
  dynamic = FALSE,
  params = list(df = NULL, y = NULL, date_var = NULL, date_start = NULL, date_end = NULL,
    time_period = "use_date_var", group_var = NULL, group_var_barmode = "stack",
    fill_colours = "lightblue", bar_border_colour = "transparent", case_boxes = FALSE,
    case_boxes_colour = "white", rolling_average_line = FALSE,
    rolling_average_line_lookback = 7, rolling_average_line_colour = "red",
    rolling_average_line_width = 1, rolling_average_line_legend_label =
    "Rolling average", cumulative_sum_line = FALSE, cumulative_sum_line_colour =
    "darkblue", 
     cumulative_sum_line_width = 1, cumulative_sum_line_legend_label =
    "Cumulative sum", cumulative_sum_line_axis_title = "Cumulative Sum", chart_title =
    NULL, chart_title_size = 13, chart_title_colour = "black", chart_footer = NULL,
    chart_footer_size = 12, chart_footer_colour = "black", x_axis_title = NULL,
    y_axis_title = NULL, x_axis_title_font_size = 11, y_axis_title_font_size = 11,
    x_axis_label_angle = NULL, y_axis_label_angle = NULL, x_axis_label_font_size = 9,
    y_axis_label_font_size = 9, y_limit_min = NULL, 
     y_limit_max = NULL,
    x_axis_break_labels = NULL, y_axis_break_labels = NULL, y_axis_n_breaks = NULL,
    show_gridlines = FALSE, show_axislines = TRUE, legend_title = "", legend_pos =
    "right", legend_font_size = 8, legend_title_font_size = 8, hline = NULL, hline_colour
    = "black", hline_width = 0.5, hline_type = "dashed", hline_label = NULL,
    hline_label_colour = "black", hover_labels = NULL)
)

Arguments

dynamic

Logical indicating whether to produce a dynamic (plotly) output. Default is FALSE, which will return a static ggplot output.

params

A named list containing arguments used to create the plot.

df: A data frame containing data used to create the epi curve.
date_var: character, Name of the variable in df containing the dates used to populate the x-axis.
y: If data is pre-aggregated, the name of the variable in df containing the aggregated values (i.e. the values used to populate the y-axis.)
date_start: A date that will determine the minimum value along the x-axis. Any rows with date_var < date_start will be excluded from aggregates.
date_end: A date that will determine the maximum value along the x-axis. Any rows with date_var > date_end will be excluded from aggregates.
time_period: The time period to be used along the x-axis. Options include c("day","year","month","quarter","year_month","year_quarter", "iso_year","iso_week","start_iso_year_week","iso_year_week", "use_date_var"). Default = "use_date_var", which indicates that the dates as they appear in the date_var column will be used to populate the x-axis.
group_var: Name of the variable in df used to define separate groups within each bar, e.g. species or region.
group_var_barmode: Indicates how grouped bar data should be plotted. Options include c("group","stack"). Default = "stack".
fill_colours: Colours used to fill bars on chart. If group_var has not been provided, then fill_colours must be a character containing a single colour (default = "lightblue"). If group_var has been provided, then fill_colours must be a character vector of colours with a number of elements equal to the number of unique groups in group_var. If a named character vector is provided where the names are values within group_var, then each colour will be mapped to it's corresponding value in group_var on the output chart and legend (e.g. c("KLEBSIELLA PNEUMONIAE" = "#007C91", "STAPHYLOCOCCUS AUREUS" = "#8A1B61", "PSEUDOMONAS AERUGINOSA" = "#FF7F32") or setNames(c("#007C91", "#8A1B61","#FF7F32"), c("KLEBSIELLA PNEUMONIAE","STAPHYLOCOCCUS AUREUS","PSEUDOMONAS AERUGINOSA")))
bar_border_colour: Colour of the border around each bar. No border colour is drawn as default.
case_boxes: boolean, If case_boxes = TRUE then a boundary box will be drawn around each case within each bar. Defaults to case_boxes = FALSE.
case_boxes_colour: The colour of the border around each case box if if case_boxes = TRUE. Default = "white".
rolling_average_line: boolean, If rolling_average_line = TRUE, then a line showing the rolling mean will be added to the plot. Default = FALSE.
rolling_average_line_lookback: Integer denoting the lookback window across which the rolling mean will be calculated (including the current time interval). Each integer denotes a division within time_period, e.g. if time_period = "year_month" and rolling_average_line_lookback = 3 then the rolling mean will be calculated using values from the current month and the previous 2 months, and if time_period = "day" and rolling_average_line_lookback = 7 then the rolling mean will be calculated using values from the previous 7 days including the current day. If there are less values within the lookback window than rolling_average_line_lookback, then the mean will be calculated from an incomplete window using the values available (i.e. if rolling_average_line_lookback = 7 and time_period = "day" but there are only 4 values within the previous 7 days, then the rolling mean will be calculated from the 4 available values.)
rolling_average_line_colour: character Colour of the rolling average line. Default = "red".
rolling_average_line_width: numeric Width of the rolling average line. Default = 1.
rolling_average_line_legend_label: character Label to be used for the rolling average line in the chart legend.
cumulative_sum_line: boolean, If cumulative_sum_line_line = TRUE, then a line showing the cumulative sum will be added to the plot. Default = FALSE. Values for the cumulative sum will be plotted on the secondary y-axis.
cumulative_sum_line_colour: character Colour of the cumulative line. Default = "darkblue".
cumulative_sum_line_width: numeric Width of the cumulative sum line. Default = 1.
cumulative_sum_line_legend_label: character Label to be used for the cumulative sum line in the chart legend.
cumulative_sum_line_axis_title: character Axis title for the cumulative sum line secondary axis.
chart_title: Text to use as chart title.
chart_title_size: Font size of chart title.
chart_title_colour: Font colour of chart title.
chart_footer: Text to use as chart footer.
chart_footer_size: Font size of chart footer.
chart_footer_colour: Font colour of chart footer.
x_axis_title: Text used for x-axis title. Defaults to name of x-variable if not stated.
y_axis_title: Text used for y-axis title. Defaults to name of y-variable if not stated.
x_axis_title_font_size: Font size of the x-axis title.
y_axis_title_font_size: Font size of the y-axis title.
x_axis_label_angle: Angle for x-axis label text.
y_axis_label_angle: Angle for y-axis label text.
x_axis_label_font_size: Font size for the x-axis tick labels.
y_axis_label_font_size: Font size for the y-axis tick labels.
y_limit_min: Lower limit for the y-axis. Default used if not provided.
y_limit_max: Upper limit for the y-axis. Default used if not provided.
x_axis_break_labels: Vector of values to use for x-axis breaks. Defaults used if not provided. Values provided must match the formatting of time_period.
y_axis_break_labels: Vector of values to use for y-axis breaks. Defaults used if not provided.
y_axis_n_breaks: Scales y-axis with approximately n breaks. Cannot be used if y_axis_break_labels is also provided.
show_gridlines: Logical to show chart gridlines. Default = FALSE.
show_axislines: Logical to show chart axis lines. Default = TRUE.
legend_title: Text used for legend title.
legend_pos: Position of the legend. Permitted values = c("top","bottom","right","left")
legend_font_size: Font size used in the legend.
legend_title_font_size: Font size used for the legend title.
hline: Adds horizontal line across the chart at the corresponding y-value. Multiple values may be provided as a vector to add multiple horizontal lines.
hline_colour: Colour of the horizontal lines if hline is provided. A vector of colours can be provided to colour individual hlines if multiple hlines have been provided.
hline_width: Numerical width of the horizontal lines if hline is provided. A vector of numerical widths can be provided for individual hlines if multiple hlines have been provided.
hline_type: Line style of the horizontal lines if hline is provided. A vector of line styles can be provided to style hlines if multiple hlines have been provided. Permitted values = c("solid", "dotted", "dashed", "longdash", "dotdash").
hline_label: Text to label the horizontal lines if hline is provided. A vector of text strings can be provided to label individual hlines if multiple hlines have been provided.
hline_label_colour: Colour of the horizontal line labels if hline_labels is provided. A vector of colours can be provided to colour individual hline_labels if multiple hline_labels have been provided.
hover_labels: string, Text to be used in the hover-over labels in a dynamic chart. Accepts html, use '%{x}' to reference corresponding x-axis values (i.e. date intervals) and '%{y}' to reference y-axis values, e.g. hover_labels = "Date: %{x} Count: %{y}".

Value

A ggplot or plotly object.

Examples


if (FALSE) {

# Example 1: Basic epi curve

# Create a basic epi curve using the epiviz::lab_data dataset
library(epiviz)

basic_epi_curve <- epi_curve(
  params = list(
    df = lab_data,
    date_var = "specimen_date",
    date_start = "2020-01-01",
    date_end = "2023-12-31",
    time_period = "year_month",
    fill_colours = "#007C91",
    rolling_average_line = TRUE,
    rolling_average_line_lookback = 3,
    rolling_average_line_legend_label = "3-month rolling average",
    chart_title = "Laboratory Detections per Month",
    x_axis_title = "Year - Month",
    y_axis_title = "Number of detections",
    x_axis_label_angle = -90
  )
)

basic_epi_curve




# Example 2: Create both static and dynamic epi curves using grouped data

library(epiviz)

# Define list of date breaks for x-axis; use every other ISO week in date range
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))

# Create parameter list
params_list <- list(
  df = 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"
)

# Create static epi curve
static_curve <- epi_curve(params = params_list, dynamic = FALSE)

# Create dynamic epi curve
dynamic_curve <- epi_curve(params = params_list, dynamic = TRUE)

# View both simultaneously using shiny app
library(shiny)
library(plotly)
ui <- fluidPage(
  plotOutput('static_curve'),
  plotlyOutput('dynamic_curve')
)
server <- function(input, output, session) {
  output$static_curve <- renderPlot(static_curve)
  output$dynamic_curve <- renderPlotly(dynamic_curve)
}
shinyApp(ui, server)




# Example 3: Create static and dynamic curves using grouped data, include cumulative
# sum line and boxes around each case

library(epiviz)

# Create parameter list
params_cases <- list(
  df = lab_data,
  date_var = "specimen_date",
  date_start = "2021-06-01",
  date_end = "2021-07-31",
  time_period = "day",
  group_var = "organism_species_name",
  group_var_barmode = "stack",
  fill_colours = c("#007C91","#8A1B61","#FF7F32"),
  case_boxes = TRUE,
  rolling_average_line = TRUE,
  rolling_average_line_legend_label = "7-day rolling average",
  cumulative_sum_line = TRUE,
  chart_title = "Laboratory detections by species \n June - July 2021",
  chart_title_colour = "#007C91",
  hline = c(35),
  hline_label = "Threshold",
  hline_width = 0.5,
  hline_colour = "orange",
  hline_label_colour = "orange",
  hline_type = "dotdash",
  legend_title = "Detected organisms",
  legend_pos = "right",
  y_limit_max = 40,
  x_axis_break_labels = as.character(seq(as.Date("2021-06-01"),
                                         as.Date("2021-07-31"),
                                         by = '2 days')),
  y_axis_break_labels = seq(0, 40, 5),
  x_axis_title = "Date",
  y_axis_title = "Number of detections",
  x_axis_label_angle = -90,
  y_axis_label_angle = 90
)


# Create static and dynamic curves
static_curve <- epi_curve(params = params_cases, dynamic = FALSE)
dynamic_curve <- epi_curve(params = params_cases, dynamic = TRUE)

# View both simultaneously using shiny app
library(shiny)
library(plotly)
ui <- fluidPage(
  plotOutput('static_curve'),
  plotlyOutput('dynamic_curve')
)
server <- function(input, output, session) {
  output$static_curve <- renderPlot(static_curve)
  output$dynamic_curve <- renderPlotly(dynamic_curve)
}
shinyApp(ui, server)




# Example 4: Create static and dynamic curves using pre-aggregated data

library(epiviz)

# Define a dataframe containing the number of detections by region
regional_detections <- lab_data |>
  group_by(specimen_date, region) |>
  summarise(detections = n()) |>
  ungroup()


# Create parameter list
params_regions <- list(
  df = regional_detections,
  y = "detections",
  date_var = "specimen_date",
  date_start = "2021-10-01",
  date_end = "2022-03-31",
  time_period = "iso_year_week",
  group_var = "region",
  group_var_barmode = "stack",
  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,
  cumulative_sum_line_colour = "orange",
  chart_title = "Laboratory Detections by Region \nWinter 2021-22",
  chart_title_colour = "#007C91",
  legend_title = "Region",
  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}"
)


# Create static and dynamic curves
static_curve <- epi_curve(params = params_regions, dynamic = FALSE)
dynamic_curve <- epi_curve(params = params_regions, dynamic = TRUE)

# View both simultaneously using shiny app
library(shiny)
library(plotly)
ui <- fluidPage(
  plotOutput('static_curve'),
  plotlyOutput('dynamic_curve')
)
server <- function(input, output, session) {
  output$static_curve <- renderPlot(static_curve)
  output$dynamic_curve <- renderPlotly(dynamic_curve)
}
shinyApp(ui, server)


}