align_dates_seasonal {ggsurveillance} | R Documentation |
Align dates for seasonal comparison
Description
Standardizes dates from multiple years to enable comparison of epidemic curves and visualization of seasonal patterns in infectious disease surveillance data. Commonly used for creating periodicity plots of respiratory diseases like influenza, RSV, or COVID-19.
Usage
align_dates_seasonal(
x,
dates_from = NULL,
date_resolution = c("week", "isoweek", "epiweek", "day", "month"),
start = NULL,
target_year = NULL,
drop_leap_week = TRUE
)
align_and_bin_dates_seasonal(
x,
n = 1,
dates_from,
population = 1,
fill_gaps = FALSE,
date_resolution = c("week", "isoweek", "epiweek", "day", "month"),
start = NULL,
target_year = NULL,
drop_leap_week = TRUE
)
Arguments
x |
Either a data frame with a date column, or a date vector.
|
dates_from |
Column name containing the dates to align. Used when x is a data.frame. |
date_resolution |
Character string specifying the temporal resolution. One of:
|
start |
Numeric value indicating epidemic season start:
|
target_year |
Numeric value for the reference year to align dates to. The default target year is the start of the most recent season in the data. This way the most recent dates stay unchanged. |
drop_leap_week |
If |
n |
Numeric column with case counts (or weights). Supports quoted and unquoted column names. |
population |
A number or a numeric column with the population size. Used to calculate the incidence. |
fill_gaps |
Logical; If |
Details
This function helps create standardized epidemic curves by aligning surveillance data from different years. This enables:
Comparison of disease patterns across multiple seasons
Identification of typical seasonal trends
Detection of unusual disease activity
Assessment of current season against historical patterns
The alignment can be done at different temporal resolutions (daily, weekly, monthly) with customizable season start points to match different disease patterns or surveillance protocols.
Value
A data frame with standardized date columns:
-
year
: Calendar year from original date -
week/month/day
: Time unit based on chosen resolution -
date_aligned
: Date standardized to target year -
season
: Epidemic season identifier (e.g., "2023/24"), ifstart = 1
this is the year only (e.g. 2023). -
current_season
: Logical flag for most recent season
Binning also creates the columns:
-
n
: Sum of cases in bin -
incidence
: Incidence calculated using n/population
Examples
# Sesonal Visualization of Germany Influenza Surveillance Data
library(ggplot2)
influenza_germany |>
align_dates_seasonal(
dates_from = ReportingWeek, date_resolution = "epiweek", start = 28
) -> df_flu_aligned
ggplot(df_flu_aligned, aes(x = date_aligned, y = Incidence, color = season)) +
geom_line() +
facet_wrap(~AgeGroup) +
theme_bw() +
theme_mod_rotate_x_axis_labels_45()