Column chart — col_chart • epiviz

A function for producing either a static (ggplot) or dynamic (plotly) column chart.

Usage

col_chart(
  dynamic = FALSE,
  params = list(df = NULL, x = NULL, y = NULL, x_time_series = FALSE,
    x_time_series_bar_labels = FALSE, time_period = "day", group_var = NULL,
    group_var_barmode = "stack", fill_colours = "lightblue", bar_border_colour =
    "transparent", bar_labels = NULL, bar_labels_pos = "bar_above", bar_labels_font_size
    = 8, bar_labels_font_colour = "black", bar_labels_angle = 0, bar_labels_percent =
    FALSE, case_boxes = FALSE, case_boxes_colour = "white", axis_flip = FALSE, ci = NULL,
    ci_upper = NULL, ci_lower = NULL, ci_legend = TRUE, 
     ci_legend_title =
    "Confidence interval", ci_colours = "red", errorbar_width = NULL, 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, x_limit_min = NULL, x_limit_max = NULL, y_limit_min =
    NULL, 
     y_limit_max = NULL, x_axis_break_labels = NULL, y_axis_break_labels =
    NULL, x_axis_n_breaks = NULL, y_axis_n_breaks = NULL, x_axis_reverse = FALSE,
    y_percent = FALSE, show_gridlines = TRUE, 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 arguements used to create the plot.

df: A data frame containing data used to create the column chart.
x: character, Name of the variable in df containing the values used to populate the x-axis.
y: character, Name of the variable in df containing the values used to populate the y-axis.)
x_time_series: If x_time_series = TRUE then x-axis data will be aggregated into a time series. x must be a date variable when x_time_series = TRUE. The granularity of the time series can be set using the time_period parameter. If y is not provided, then x_time_series will assume that each row corresponds to a single observation and aggregate accordingly.
x_time_series_bar_labels: If x_time_series_bar_labels = TRUE then labels equalling y-axis values will be added to each bar.
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"). Default = "day"
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: character, Colour of the border around each bar. Default = "transparent", meaning that no border colour is drawn as default.
bar_labels: character, Name of the variable in df containing the labels to be used for each bar. To set bar lables when x_time_series = TRUE, set x_time_series_bar_labels = TRUE and labels will be added to each bar equal to y-axis values.
bar_labels_pos: character, The position on the bars that labels will be plotted, permitted values are c('bar_above','bar_base','bar_centre','above_errorbar'). Default = 'bar_above'.
bar_labels_font_size: numeric, Font size for the bar labels. Default = 8.
bar_labels_font_colour: character, Font colour for the bar labels. Default = 'black'.
bar_labels_angle: numeric, Font angle for the bar labels.
bar_labels_percent: boolean, If bar_labels_percent = TRUE then the values in bar_labels will be converted into a percentage before plotting.
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 case_boxes = TRUE. Default = "white".
axis_flip: boolean, If set to TRUE then x and y axes will be flipped and bars will be drawn hozizontally rather than vertically.
ci: Confidence interval. If ci = "errorbar" then confidence intervals be be plotted with each bar as errorbars. If ci is provided, then ci_upper and ci_lower must also be provided.
ci_upper: character, Name of the variable in df used as the upper confidence limit for each bar. Mandatory when ci is provided.
ci_lower: character, Name of the variable in df used as the lower confidence limit for each bar. Mandatory when ci is provided.
ci_legend: Logical indicating whether a separate legend should be included in the chart for confidence interval parameters. Only applies when group_var is provided. Defaults to FALSE.
ci_legend_title: Text to use as title for separate legend when ci_legend = TRUE. Default = "Confidence interval".
ci_colours: Colour(s) used for plotting errorbars when ci = "errorbar". 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")))
errorbar_width: Horizontal width of the plotted error bars when ci = "errorbar".
chart_title: Text to use as the chart title.
chart_title_size: Font size of chart title. Default = 13.
chart_title_colour: Font colour of chart title. Default = "black".
chart_footer: Text to use as chart footer.
chart_footer_size: Font size of chart footer. Default = 12.
chart_footer_colour: Font colour of chart footer. Default = "black".
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. Default = 11.
y_axis_title_font_size: Font size of the y-axis title. Default = 11.
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. Default = 9.
y_axis_label_font_size: Font size for the y-axis tick labels. Default = 9.
x_limit_min: Lower limit for the x-axis. Default used if not provided.
x_limit_max: Upper limit for the x-axis. Default used if not provided.
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. If x_time_series = TRUE then 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.
x_axis_n_breaks: Scales x-axis with approximately n breaks. Cannot be provided if x_axis_break_labels has also been provided.
y_axis_n_breaks: Scales y-axis with approximately n breaks. Cannot be used if y_axis_break_labels has also been provided.
x_axis_reverse: Reverses x-axis scale if x_axis_reverse = TRUE.
y_percent: Converts y-axis to percentage scale if y_percent = TRUE.
show_gridlines: Logical to show chart gridlines. Default = TRUE.
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. Default = 8.
legend_title_font_size: Font size used for the legend title. Default = 8.
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. Default = "black".
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. Default = 0.5.
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"). Default = "dashed".
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. Default = "black".
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) { # \dontrun{

# Example 1: Basic column chart

# Create a basic column chart using the epiviz::lab_data dataset
library(epiviz)

# Summarise the overall number of detections by region in 2023
detections_by_region_2023 <- lab_data |>
  filter(specimen_date >= as.Date("2023-01-01") & specimen_date <= as.Date("2023-12-31")) |>
  group_by(region) |>
  summarise(detections = n()) |>
  ungroup() |>
  # Place 'Yorkshire and Humber' on multiple lines
  mutate(region = ifelse(region == "Yorkshire and Humber", "Yorkshire and \nHumber", region))

# Create column chart
basic_col_chart <- col_chart(
  params = list(
    df = detections_by_region_2023,
    x = "region",
    y = "detections",
    fill_colours = "#007C91",
    chart_title = "Laboratory Detections by Region 2023",
    x_axis_title = "Region",
    y_axis_title = "Number of detections",
    x_axis_label_angle = -45
  )
)

basic_col_chart




# Example 2: Column chart with bar labels, errorbars, and a horizontal threshold line

# Create a basic column chart using the epiviz::lab_data dataset
library(epiviz)


# Summarise the overall number of detections by region in 2023
detections_by_region_2023 <- lab_data |>
  filter(specimen_date >= as.Date("2023-01-01") & specimen_date <= as.Date("2023-12-31")) |>
  group_by(region) |>
  summarise(detections = n()) |>
  ungroup() |>
  # Place 'Yorkshire and Humber' on multiple lines
  mutate(region = ifelse(region == "Yorkshire and Humber", "Yorkshire and \nHumber", region)) |>
  # Add random error for errorbars
  rowwise() |>
  mutate(lower_limit = detections - sample(50:200,1),
         upper_limit = detections + sample(50:200,1)) |>
  ungroup()


# Create column chart
col_chart <- col_chart(
  params = list(
    df = detections_by_region_2023,
    x = "region",
    y = "detections",
    fill_colours = "#007C91",
    ci = 'errorbar',
    ci_lower = "lower_limit",
    ci_upper = "upper_limit",
    errorbar_width = 0.2,
    bar_labels = 'detections',
    bar_labels_pos = 'bar_base',
    bar_labels_font_size = 12,
    bar_labels_font_colour = 'white',
    chart_title = "Laboratory Detections by Region 2023",
    x_axis_title = "Region",
    y_axis_title = "Number of detections",
    show_gridlines = FALSE,
    hline = 1200,
    hline_colour = 'orange',
    hline_label = 'Threshold',
    hline_label_colour = 'orange'
  )
)

col_chart




# Example 3: Create both static and dynamic column charts using grouped data

library(epiviz)

# Summarise the overall number of detections by species and region in 2023
detections_by_species_region_2023 <- lab_data |>
  filter(specimen_date >= as.Date("2023-01-01") & specimen_date <= as.Date("2023-12-31")) |>
  group_by(region, organism_species_name) |>
  summarise(detections = n()) |>
  ungroup() |>
  # Place the name for 'Yorkshire and Humber' on multiple lines
  mutate(region = ifelse(region == "Yorkshire and Humber", "Yorkshire and \nHumber", region))

# Create parameter list
params_list <- list(
  df = detections_by_species_region_2023,
  x = "region",
  y = "detections",
  group_var = "organism_species_name",
  group_var_barmode = "group",
  fill_colours = c("KLEBSIELLA PNEUMONIAE" = "#007C91",
                   "STAPHYLOCOCCUS AUREUS" = "#8A1B61",
                   "PSEUDOMONAS AERUGINOSA" = "#FF7F32"),
  chart_title = "Laboratory Detections by Region \nand Species 2023",
  chart_footer = "This chart has been created using simulated data.",
  x_axis_title = "Region",
  y_axis_title = "Number of detections",
  chart_title_colour = "#007C91",
  chart_footer_colour = "#007C91",
  show_gridlines = FALSE
)

# Create static column chart
static_chart <- col_chart(params = params_list, dynamic = FALSE)

# Create dynamic epi curve
dynamic_chart <- col_chart(params = params_list, dynamic = TRUE)

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




# Example 4: Create both static and dynamic column charts using grouped data; apply
#              bar labels and present as horizontal column chart.

library(epiviz)

# Summarise the overall number of detections by species and region in 2023
detections_by_species_region_2023 <- lab_data |>
  filter(specimen_date >= as.Date("2023-01-01") & specimen_date <= as.Date("2023-12-31")) |>
  group_by(region, organism_species_name) |>
  summarise(detections = n()) |>
  ungroup() |>
  # Place the name for 'Yorkshire and Humber' on multiple lines
  mutate(region = ifelse(region == "Yorkshire and Humber", "Yorkshire and \nHumber", region))


# Reorder dataframe so that regions with the largest total number of detections will
#    appear at the top.
detections_by_species_region_2023 <- detections_by_species_region_2023 |>
  group_by(region) |>
  mutate(group_detections = sum(detections)) |>
  ungroup() |>
  arrange(group_detections) |>
  mutate(region = factor(region, levels = unique(region)))


# Create parameter list
params_list <- list(
  df = detections_by_species_region_2023,
  x = "region",
  y = "detections",
  group_var = "organism_species_name",
  group_var_barmode = "stack",
  fill_colours = c("KLEBSIELLA PNEUMONIAE" = "#007C91",
                   "STAPHYLOCOCCUS AUREUS" = "#8A1B61",
                   "PSEUDOMONAS AERUGINOSA" = "#FF7F32"),
  bar_labels = 'detections',
  bar_labels_pos = 'bar_centre',
  bar_labels_font_size = 8,
  bar_labels_font_colour = 'white',
  chart_title = "Laboratory Detections by Region \nand Species 2023",
  chart_footer = "This chart has been created using simulated data.",
  x_axis_title = "Region",
  y_axis_title = "Number of detections",
  chart_title_colour = "#007C91",
  chart_footer_colour = "#007C91",
  show_gridlines = FALSE,
  axis_flip = TRUE  # Create horizontal chart using the axis_flip parameter
)


# Create static and dynamic column charts
static_chart <- col_chart(params = params_list, dynamic = FALSE)
dynamic_chart <- col_chart(params = params_list, dynamic = TRUE)


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



# Example 5: Create both static and dynamic column charts using a time-series x-axis
#              and a percentage y-axis.

library(epiviz)

# Create parameter list
params_list <- list(
  df = lab_data,
  x = "specimen_date",
  x_limit_min = "2022-12-01",
  x_limit_max = "2023-03-31",
  # Set x_time_series = TRUE and time_period = "iso_year_week" to aggregate data
  #   into a time series by ISO week (assumes each row in df corresponds to a
  #   single observation).
  x_time_series = TRUE,
  time_period = "iso_year_week",
  x_time_series_bar_labels = TRUE,
  # Set y_percent = TRUE to convert y-axis to percentage scale (when x_time_series
  #   = TRUE this will also convert y values and bar labels to percentages by group).
  y_percent = TRUE,
  group_var = "organism_species_name",
  group_var_barmode = "stack",
  fill_colours = c("KLEBSIELLA PNEUMONIAE" = "#007C91",
                   "STAPHYLOCOCCUS AUREUS" = "#8A1B61",
                   "PSEUDOMONAS AERUGINOSA" = "#FF7F32"),
  bar_labels_pos = 'bar_centre',
  bar_labels_font_size = 8,
  bar_labels_font_colour = 'white',
  chart_title = "Laboratory Detections by ISO week \nand Species, winter 2022-23",
  chart_footer = "This chart has been created using simulated data.",
  x_axis_title = "ISO Week",
  y_axis_title = "Number of detections",
  x_axis_label_angle = -45,
  chart_title_colour = "#007C91",
  chart_footer_colour = "#007C91",
  show_gridlines = FALSE
)


# Create static and dynamic column charts
static_chart <- col_chart(params = params_list, dynamic = FALSE)
dynamic_chart <- col_chart(params = params_list, dynamic = TRUE)


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


} # }