Skip to contents

Visualise Climate-Health Aggregate Data

Source: R/sus_climate_plot_aggregate.R
sus_climate_plot_aggregate.Rd

sus_climate_plot_aggregate() produces exploratory visualisations for the output of sus_climate_aggregate(). Six complementary plot types cover the full exploratory workflow before modelling: time-series overlay, scatter with smooth, cross-correlation (CCF), distribution, correlation matrix, and seasonal patterns. Modelling-specific plots (DLNM surfaces, residual diagnostics, RR tables) are deliberately excluded to avoid duplication with the dedicated sus_mod_plot_* family.

Usage

sus_climate_plot_aggregate(
  df,
  outcome_col = NULL,
  climate_cols = NULL,
  plot_type = "timeseries",
  smooth_method = "loess",
  max_lag = 30L,
  alpha = 0.05,
  interactive = FALSE,
  lang = "pt",
  verbose = TRUE,
  title = NULL,
  source = NULL
)

Arguments

df

A climasus_df at stage = "climate" produced by sus_climate_aggregate(). Must contain at least date, code_muni, a health outcome column, and one or more climate exposure columns.

outcome_col

Character. Name of the health-outcome column (e.g. "n_obitos", "n_internacoes"). If NULL (default) the first integer column that is not a climate variable is used.

climate_cols

Character vector of climate column names to visualise. If NULL (default) all columns that match the naming conventions of sus_climate_aggregate() are detected automatically (lag*, mvwin*, off*to*, gdd*, _lag*, or known INMET variable names).

plot_type

Character. One of:

"timeseries"

Dual-axis time-series: rescaled climate exposure (ribbon) overlaid on health outcome (line + points). When multiple climate columns are provided and patchwork is installed, one panel per variable is stacked vertically via patchwork::wrap_plots(). Falls back to the first column only when patchwork is not available.

"scatter"

Scatter plot with loess/GAM smooth: climate exposure on x-axis, health outcome on y-axis. Shows the marginal association ignoring temporal structure.

"ccf"

Cross-Correlation Function bars from \(-30\) to +max_lag days. Highlights lags with significant correlation (|r| > 2/sqrt(n)) in a contrasting colour. Useful for identifying the optimal lag before modelling.

"distribution"

Histogram + density overlay of each climate column. For discrete_lag outputs the multiple lag columns are overlaid for comparison.

"corr_matrix"

Heatmap of Spearman correlations between all climate columns and the outcome. Especially informative when the input was produced with temporal_strategy = "discrete_lag".

"seasonal"

Monthly boxplots of the climate exposure and the outcome incidence, side-by-side, to reveal seasonal co-variation.

Default "timeseries".

smooth_method

Character. Smoothing method for the scatter plot: "loess" (default) or "gam".

max_lag

Integer. Maximum lag (days) shown in the CCF plot. Default 30L.

alpha

Numeric. Confidence level for CCF significance bounds (default 0.05; bounds drawn at \(\pm 2/\sqrt{n}\)).

interactive

Logical. If TRUE, returns a plotly interactive version built with plotly::plot_ly() for proper dual-axis support (plotly::ggplotly() is avoided as it breaks secondary axes for "timeseries"). Requires plotly to be installed. Default FALSE.

lang

Character. Language for axis labels and titles: "pt" (default), "en", "es".

verbose

Logical. Print progress messages. Default TRUE.

title

Character or NULL. Override the auto-generated plot title. Default NULL uses the built-in multilingual title.

source

Character or NULL. Data source attribution prepended to the plot caption. Default NULL.

Value

A ggplot2 object, a patchwork object (when multiple climate columns are supplied and patchwork is installed for "timeseries" or "scatter" plot types), or a plotly object when interactive = TRUE.

See also

sus_climate_aggregate(), sus_climate_plot_fill(), sus_climate_plot_heatwaves(), sus_mod_plot_dlnm()

Examples

if (FALSE) { # \dontrun{
# Build aggregate data (exact strategy)
df_agg <- sus_climate_aggregate(
  health_data       = sf_sim_spatial,
  climate_data      = df_inmet,
  climate_var       = "tair_dry_bulb_c",
  temporal_strategy = "exact"
)

# Time-series overlay
sus_climate_plot_aggregate(df_agg, plot_type = "timeseries", lang = "pt")

# Discrete lag: correlation matrix across all lag columns
df_lag <- sus_climate_aggregate(
  health_data       = sf_sim_spatial,
  climate_data      = df_inmet,
  climate_var       = "tair_dry_bulb_c",
  temporal_strategy = "discrete_lag",
  lag_days          = c(7, 14, 21)
)
sus_climate_plot_aggregate(df_lag, plot_type = "corr_matrix", lang = "en")

# Cross-correlation
sus_climate_plot_aggregate(df_agg, plot_type = "ccf", max_lag = 21L)
} # }