Time-Series Plot of Aggregated DATASUS Health Outcomes

Produces publication-quality time-series visualisations (epidemic curve, seasonal boxplot, calendar heatmap, or annual trend) from a climasus_df dataset at stage "aggregate" or later. Colour palettes are powered by ggsci::ggsci (Lancet, NEJM, JCO, UChicago). An interactive plotly::plotly widget can be returned with interactive = TRUE.

Usage

sus_data_plot_aggregate_ts(
  df,
  value_col = NULL,
  group_col = NULL,
  facet_col = NULL,
  facet_ncol = 3L,
  plot_type = "epidemic",
  smooth_method = "loess",
  smooth_span = 0.25,
  log_transform = FALSE,
  free_scales = TRUE,
  palette = "lancet",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  theme_style = "publication",
  date_labels = "%b/%y",
  year_breaks = "3 months",
  base_size = 11,
  interactive = FALSE,
  city = NULL,
  use_cache = TRUE,
  cache_dir = "~/.climasus4r_cache/spatial",
  lang = "pt",
  verbose = TRUE
)

Arguments

df

A climasus_df at stage "aggregate" or later (output of sus_data_aggregate()).

value_col

Character. Name of the outcome column to plot. If NULL (default), the function auto-detects the first matching column from: n_obitos, n_internacoes, n_nascimentos, n_casos, n_procedimentos, n_estabelecimentos, and their English / Spanish equivalents.

group_col

Character. Optional column used for colour-grouping in "epidemic" and "seasonal" plots.

facet_col

Character. Optional column for facet_wrap() panels.

facet_ncol

Integer. Number of facet columns. Default 3L.

plot_type

Character. One or more of "epidemic", "seasonal", "heatmap", "trend". When multiple types are supplied, plots are assembled with patchwork::patchwork (one per row). Default: "epidemic".

smooth_method

Character. Smoothing method for the "epidemic" plot: "loess" (default), "gam", or "lm".

smooth_span

Numeric. Span for LOESS smoothing. Default 0.25.

log_transform

Logical. Apply log1p transformation on the y-axis for "epidemic" and "seasonal" plots, and to the fill scale in "heatmap". Default FALSE.

free_scales

Logical. Allow free y-axis scales in faceted plots. Default TRUE.

palette

Character. Colour palette. One of "lancet" (default), "nejm", "jco", "uchicago", or "viridis".

title

Character. Plot title. Auto-generated if NULL.

subtitle

Character. Plot subtitle. NULL auto-generates one from row count, outcome column name and date range.

caption

Character. Figure caption. NULL uses the DATASUS source string for the selected language.

theme_style

Character. Reserved for future theme variants. Currently only "publication" (default) is implemented.

date_labels

Character. strftime format string for x-axis date labels. Default "%b/%y".

year_breaks

Character. date_breaks string for the x-axis. Default "3 months".

base_size

Numeric. Base font size for the ggplot2 theme. Default 11.

interactive

Logical. Return a plotly::ggplotly() widget instead of a static ggplot2 object. Default FALSE.

city

Character vector of municipality names or 6-/7-digit IBGE codes. When supplied, the plot is filtered to those municipalities before rendering. Names are resolved through municipio_meta, with accent tolerance, using the same cache as sus_data_filter_demographics().

use_cache

Logical. Cache municipality metadata to disk when city filtering or municipality labels are needed. Default TRUE.

cache_dir

Character. Directory for municipality metadata cache. Default "~/.climasus4r_cache/spatial".

lang

Character. Language for labels and messages: "pt" (default), "en", or "es".

verbose

Logical. Print progress messages. Default TRUE.

Value

Invisibly returns the ggplot2 object (or plotly widget when interactive = TRUE). Side effect: prints the plot in the active graphics device.

Supported systems

Automatically adapts y-axis labels and titles to SINAN, SIM, SIH, SINASC, SIA, and CNES via outcome column auto-detection.

Examples

if (FALSE) { # \dontrun{
# Epidemic curve, Portuguese labels
sus_data_plot_aggregate_ts(df_agg, lang = "pt")

# Seasonal boxplot, log-transformed
sus_data_plot_aggregate_ts(
  df_agg,
  plot_type     = "seasonal",
  log_transform = TRUE,
  lang          = "en"
)

# Calendar heatmap by group
sus_data_plot_aggregate_ts(
  df_agg,
  plot_type  = "heatmap",
  facet_col  = "municipio",
  facet_ncol = 2L,
  lang       = "pt"
)

# Multi-panel: epidemic + trend
sus_data_plot_aggregate_ts(
  df_agg,
  plot_type = c("epidemic", "trend"),
  lang      = "en"
)

# Interactive plotly widget
sus_data_plot_aggregate_ts(df_agg, interactive = TRUE)
} # }