Point charts

Introduction

Point charts (scatter plots) are versatile tools for exploring relationships between variables in epidemiological data. They can show correlations, identify outliers, and reveal patterns that might not be apparent in other visualisations. The point_chart() function supports various point styles, confidence ribbons, threshold lines, and both static and interactive visualisations.

Prerequisites

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

Example 1: Basic point chart

Basic point charts are ideal for exploring relationships between two continuous variables. This example shows monthly detections over time.

Prepare the data

# Create monthly data (as used in tests)
monthly_data <- epiviz::lab_data %>%
  group_by(specimen_month = lubridate::floor_date(specimen_date, 'month')) %>%
  summarise(detections = n()) %>%
  ungroup()

Create the basic point chart

point_chart(
  dynamic = FALSE,  # Create static ggplot chart
  params = list(
    df = monthly_data,
    x = "specimen_month",        # Date variable for x-axis
    y = "detections",           # Count variable for y-axis
    point_colours = "#007C91",  # Color for points
    point_size = 3,             # Size of points
    x_limit_min = "2023-01-01", # X-axis minimum
    x_limit_max = "2023-12-31", # X-axis maximum
    chart_title = "Detections per Month 2023",
    x_axis_title = "Month of detection",
    y_axis_title = "Number of detections",
    x_axis_date_breaks = "2 months"  # Show every 2 months
  )
)

Monthly detections with point markers across 2023.

Interpretation: This point chart shows the relationship between time and monthly detections, revealing temporal patterns and any outliers in the data.

Example 2: Interactive point chart

Interactive point charts allow users to explore data dynamically, with hover information and zooming capabilities.

Create the interactive point chart

point_chart(
  dynamic = TRUE,   # Create interactive plotly chart
  params = list(
    df = monthly_data,
    x = "specimen_month",
    y = "detections",
    point_colours = "#007C91",
    point_size = 3,
    x_limit_min = "2022-01-01",
    x_limit_max = "2023-12-31",
    chart_title = "Detections per Month 2022-2023",
    x_axis_title = "Month of detection",
    y_axis_title = "Number of detections",
    x_axis_date_breaks = "2 months"
  )
)

Interactive monthly detections with hover detail.

Interpretation: The interactive version allows detailed exploration of the temporal patterns, with hover information showing exact values for each month.

Example 3: Grouped point chart with confidence ribbons

Grouped point charts with confidence ribbons are excellent for comparing multiple categories while showing uncertainty estimates.

Prepare grouped data with confidence intervals

# Create grouped data with confidence intervals (as used in tests)
set.seed(123)
grouped_data <- epiviz::lab_data %>%
  group_by(specimen_month = lubridate::floor_date(specimen_date, 'month'),
           organism_species_name) %>%
  summarise(detections = n()) %>%
  ungroup() %>%
  mutate(
    offset = sample(10:50, n(), replace = TRUE),
    lower_limit = pmax(detections - offset, 0),
    upper_limit = detections + offset
  ) %>%
  select(-offset)

Create the grouped point chart with confidence ribbons

point_chart(
  dynamic = FALSE,  # Create static ggplot chart
  params = list(
    df = grouped_data,
    x = "specimen_month",
    y = "detections",
    group_var = "organism_species_name",  # Group by organism type
    point_colours = c("#007C91", "#8A1B61", "#FF7F32"),  # Colors for each group
    point_size = 3,
    x_limit_min = "2022-01-01",
    x_limit_max = "2023-12-31",
    chart_title = "Detections per Month 2022-2023",
    x_axis_title = "Month of detection",
    y_axis_title = "Number of detections",
    x_axis_date_breaks = "2 months",
    y_axis_break_labels = seq(0, 600, 100),  # Custom y-axis breaks
    x_axis_label_angle = 45,                 # Rotate x-axis labels
    # Confidence interval parameters
    ci = "ribbon",                           # Use ribbon for confidence intervals
    ci_lower = "lower_limit",                # Lower confidence limit column
    ci_upper = "upper_limit",                # Upper confidence limit column
    ci_colours = c("#007C91", "#8A1B61", "#FF7F32")  # Colors for confidence ribbons
  )
)

Grouped monthly detections with confidence ribbons.

Interpretation: This grouped point chart shows detections by organism type over time, with confidence ribbons indicating uncertainty around the estimates.

Example 4: Point chart with threshold lines

Threshold lines help identify data points that exceed or fall below important cutoffs, such as outbreak levels or target values.

Create the point chart with threshold lines

point_chart(
  dynamic = FALSE,  # Create static ggplot chart
  params = list(
    df = grouped_data,
    x = "specimen_month",
    y = "detections",
    group_var = "organism_species_name",
    point_colours = c("#007C91", "#8A1B61", "#FF7F32"),
    point_size = 3,
    x_limit_min = "2022-01-01",
    x_limit_max = "2023-12-31",
    chart_title = "Detections per Month 2022-2023",
    x_axis_title = "Month of detection",
    y_axis_title = "Number of detections",
    x_axis_date_breaks = "2 months",
    y_axis_break_labels = seq(0, 600, 100),
    x_axis_label_angle = 45,
    ci = "ribbon",
    ci_lower = "lower_limit",
    ci_upper = "upper_limit",
    ci_colours = c("#007C91", "#8A1B61", "#FF7F32"),
    # Threshold lines
    hline = c(450, 550),                    # Multiple threshold lines
    hline_colour = c("blue", "red"),        # Colors for each line
    hline_label = c("threshold 1", "threshold 2"),  # Labels for lines
    hline_label_colour = c("blue", "red")   # Label colors
  )
)

Grouped monthly detections with threshold lines.

Interpretation: This point chart includes threshold lines to identify months where detections exceeded specific levels, helping prioritize periods for further investigation.

Example 5: Interactive grouped point chart with all features

Interactive point charts with all features provide the most comprehensive view for surveillance dashboards and exploratory analysis.

Create the comprehensive interactive point chart

point_chart(
  dynamic = TRUE,   # Create interactive plotly chart
  params = list(
    df = grouped_data,
    x = "specimen_month",
    y = "detections",
    group_var = "organism_species_name",
    point_colours = c("#007C91", "#8A1B61", "#FF7F32"),
    point_size = 3,
    x_limit_min = "2022-01-01",
    x_limit_max = "2023-12-31",
    chart_title = "Detections per Month 2022-2023",
    x_axis_title = "Month of detection",
    y_axis_title = "Number of detections",
    x_axis_date_breaks = "2 months",
    y_axis_break_labels = seq(0, 600, 100),
    x_axis_label_angle = 45,
    ci = "ribbon",
    ci_lower = "lower_limit",
    ci_upper = "upper_limit",
    ci_colours = c("#007C91", "#8A1B61", "#FF7F32"),
    hline = c(450, 550),
    hline_colour = c("blue", "red"),
    hline_label = c("threshold 1", "threshold 2"),
    hline_label_colour = c("blue", "red")
  )
)

Interactive grouped point chart with confidence ribbons and thresholds.

Interpretation: This comprehensive interactive point chart combines grouped data visualization with confidence ribbons and threshold lines, providing multiple layers of information for surveillance analysis.

Tips for point charts

1. Data preparation: Always aggregate your data appropriately before passing it to point_chart(). The function expects pre-calculated counts or values.

2. Date handling: Use lubridate::floor_date() to create consistent time periods for aggregation, as shown in the test examples.

3. Confidence intervals: Use ci = "ribbon" with ci_lower and ci_upper parameters to add confidence ribbons around your data points.

4. Threshold lines: Use hline parameters to add horizontal reference lines for alert levels or targets:

   hline = c(450, 550),
   hline_colour = c("blue", "red"),
   hline_label = c("threshold 1", "threshold 2")

5. Grouping: Use group_var to create multiple series for comparison. Each group will get a different color.

6. Point styling: Customize appearance with:

   • point_colours: Colors for points (vector for multiple groups)
   • point_size: Size of points
   • ci_colours: Colors for confidence ribbons

7. Axis limits: Use x_limit_min and x_limit_max to control the x-axis range for better focus on relevant time periods.

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

9. Axis formatting: Use x_axis_date_breaks and y_axis_break_labels to control how dates and values are displayed on the axes.

10. Label rotation: Use x_axis_label_angle to rotate date labels for better readability.

11. Confidence ribbon colors: Ensure ci_colours matches your point_colours for consistent visual representation.

12. Random confidence intervals: In the test examples, confidence intervals are generated randomly. In real applications, use appropriate statistical methods to calculate meaningful confidence intervals.