Visualizes average monthly attributable health metrics (e.g., attributable number,
fraction, or rate) derived from attribution analyses across different spatial scales.
The function automatically adapts plots to the selected spatial level (country,
region, or district) and summarizes seasonal patterns using monthly aggregation.
Optionally, corresponding monthly climate variables can be overlaid on a secondary
axis to support joint interpretation of health impacts and climate seasonality.
plot_avg_monthly(
attr_data,
level = c("country", "region", "district"),
metrics = c("AR_Number", "AR_per_100k", "AR_Fraction"),
c_data,
param_term,
case_type,
filter_year = NULL,
save_fig = FALSE,
output_dir = NULL
)A named list of ggplot objects. Each element corresponds to the country or an
individual region or district and contains a monthly attribution plot. The list
is returned invisibly when plots are saved to file.
A data frame or tibble containing attributable health metrics, typically
generated by an attribution workflow. Must include at least month and the selected
metric column (AR_Number, AR_Fraction, or AR_per_100k), as well as spatial
identifiers (region or district) when applicable.
Character. The spatial level for plotting. One of "country",
"region", or "district". Determines whether a single national plot or multiple
subnational plots are produced.
Character. The attributable metrics to visualize. One or more of
"AR_Number", "AR_Fraction", or "AR_per_100k". Controls aggregation rules,
axis labeling, and numeric formatting.
A data frame containing monthly climate variables corresponding
to the same spatial and temporal resolution as attr_data. When provided together with
param_term, climate information is overlaid on a secondary y-axis.
Character string specifying the climate exposure variable
(e.g., "tmax" for maximum temperature or "rainfall" for precipitation). Used for
climate extraction and axis labeling.
Optional integer or vector of integers to restrict the analysis
to specific years prior to monthly aggregation. Defaults to NULL, in which case
all available years are included.
Logical. If TRUE, saves the generated plots as a PDF file.
Defaults to FALSE.
Optional character string specifying the directory where output
PDF files will be saved when save_fig = TRUE. The directory is created automatically
if it does not exist.
This function produces publication-ready visualizations of average monthly attributable health metrics:
Country level: A single bar plot summarizing national average monthly attribution patterns.
Region/District level: One bar plot per administrative unit, showing average monthly attribution, with automatic pagination when many units are present.
Climate overlay (optional): Monthly climate exposure plotted as a line on a secondary y-axis to facilitate comparison with seasonal health impacts.
Metric-specific aggregation rules (sum or mean) and numeric formatting are applied
automatically. Axis limits and breaks are dynamically adjusted to improve readability.
When save_fig = TRUE, a single PDF file is created per metric and spatial level,
with multiple pages used for region- or district-level outputs when necessary.