Visualizes attributable health metrics (e.g., attributable number, fraction, or rate)
derived from attribution_calculation() across different spatial scales and time periods.
The function automatically adapts plots to the selected spatial level (country, region,
or district) and handles both single- and multi-year visualizations.
It supports faceted, grouped, or aggregated visualizations and can optionally
save output plots as PDF files.
plot_attribution_metric(
attr_data,
level = c("country", "region", "district"),
metrics = c("AR_Number", "AR_Fraction", "AR_per_100k"),
filter_year = NULL,
param_term,
case_type,
save_fig = FALSE,
output_dir = NULL
)A named list of ggplot or patchwork plot objects, grouped by metric.
Each element corresponds to one metric ("AR_Number", "AR_Fraction", "AR_per_100k")
and may include one or more plots, depending on the level and year filters.
A data frame or tibble containing attribution results, typically
generated by the attribution_calculation() function. Must include relevant columns
such as year, region, district, AR_Number, AR_Fraction, and AR_per_100k.
Character. The spatial level for plotting. One of "country",
"region", or "district". Determines the type and granularity of plots.
Character vector specifying which metrics to plot.
Options include "AR_Number", "AR_Fraction", and "AR_per_100k". Multiple metrics can be plotted.
Optional integer or vector of integers to restrict the plots
to specific years. Defaults to NULL (all available years are included).
Character. The exposure variable term to evaluate (e.g., "tmax" for
maximum temperature, "rainfall" for precipitation). Used for labeling the plots.
Character. The type of disease that the case column refers to
(e.g., "malaria" or "diarrhea"). Used in titles and y-axis labels.
Logical. If TRUE, saves all generated plots as PDF files
to the specified directory. Defaults to FALSE.
Optional string. Directory path where output PDF files will be saved
when save_fig = TRUE. If the directory does not exist, it will be created automatically.
This function produces publication-ready plots of attributable metrics:
Country level: Time series line plots with 95% confidence ribbons.
Region/District level (no filter): Horizontal bar plots showing aggregated metrics, grouped by administrative unit.
Region/District level (multi-year): Grouped bar plots comparing metrics across years.
The function automatically adjusts y-axis limits, formats numeric labels with commas,
and includes optional text annotations (e.g., showing both attributable numbers and fractions).
When save_fig = TRUE, one PDF file is created per metric and spatial level, and each file
may contain multiple pages if many regions or districts are present.