Plot Municipal Map of Aggregated Health Data

Renders a bubble or choropleth map showing the spatial distribution of health events (counts or incidence rates) at the Brazilian municipal level. Designed for data produced by sus_data_aggregate().

Bubble map (map_type = "bubble") places proportionally sized, colour-encoded circles at each municipality centroid. State boundaries are drawn as a background polygon layer.

Choropleth map (map_type = "choropleth") fills municipality polygons downloaded via geobr::read_municipality(). Requires geobr and sf. If these packages are unavailable the function falls back to a bubble map with a warning.

Usage

sus_data_plot_aggregate_map(
  df,
  value_col = NULL,
  map_type = c("bubble", "choropleth", "quantile_choropleth"),
  rate_per_100k = FALSE,
  period = NULL,
  city = NULL,
  top_n = NULL,
  state_borders = TRUE,
  show_labels = TRUE,
  palette = "YlOrRd",
  log_scale = TRUE,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  theme_style = "publication",
  base_size = 11,
  interactive = FALSE,
  return_sf = FALSE,
  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 health-count column to map. If NULL (default) the column is auto-detected using the same priority order as sus_climate_plot_aggregate(): n_obitos, n_internacoes, n_nascimentos, n_casos, n_procedimentos, n_estabelecimentos and their English / Spanish equivalents.
map_type: Character. "bubble" (default), "choropleth" or "quantile_choropleth"
rate_per_100k: Logical. If TRUE, divides total_cases by pop_25 (from municipio_meta) and multiplies by 1e5 to compute incidence per 100,000 inhabitants. Default FALSE.
period: Date scalar or c(start, end) vector. When supplied, rows in df whose date column falls outside the interval are removed before aggregation. NULL (default) uses all rows.
city: Character vector of municipality names or 6-/7-digit IBGE codes. When supplied, the map is restricted to those municipalities. Names are resolved through municipio_meta with accent tolerance.
top_n: Integer. If supplied, only the top N municipalities by total_cases are labelled on the map. NULL disables top-N labels.
state_borders: Logical. Overlay state boundary polygons (downloaded via geobr). Default TRUE.
show_labels: Logical. Annotate capital cities with text labels (bubble map only). Default TRUE.
palette: Character. Colour palette for the fill / bubble fill scale. Any RColorBrewer::brewer.pal() sequential/diverging palette name (e.g. "YlOrRd", "Blues", "RdYlBu") or one of the ggsci aliases "lancet" / "nejm". Default "YlOrRd".
log_scale: Logical. Apply log1p transformation to the colour scale. Default TRUE.
title: Character. Map title. NULL uses a built-in multilingual default.
subtitle: Character. Map subtitle. NULL auto-generates one from the number of municipalities, metric and period.
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.
base_size: Numeric. Base font size for theme_void(). Default 11.
interactive: Logical. If TRUE, returns a leaflet widget (pan, zoom, click-for-popup) built from the same municipality data instead of the static ggplot2 map. Requires leaflet and, at view time, an internet connection to load the basemap tiles. Default FALSE.
return_sf: Logical. If TRUE, return the underlying sf object used to build the map (municipality points for map_type = "bubble", polygons for "choropleth" / "quantile_choropleth") instead of the ggplot2 object. Pipe the result into sus_data_export() to write it as a shapefile, GeoPackage, GeoJSON or GeoParquet file. Default FALSE.
use_cache: Logical. Cache municipality metadata to disk. Default TRUE.
cache_dir: Character. Directory for the disk cache. Default "~/.climasus4r_cache/spatial".
lang: Character. Language for messages and axis labels: "pt" (default), "en", "es".
verbose: Logical. Print progress messages. Default TRUE.

Value

A ggplot2 object (class "gg" / "ggplot"), a leaflet widget when interactive = TRUE, or an sf object when return_sf = TRUE. The function does not modify df or advance the pipeline stage. When a plain ggplot2 object is returned, it also carries the underlying sf data as a "climasus_sf" attribute (attr(p, "climasus_sf")) for callers that want to export it without a second return_sf = TRUE call.

Examples

if (FALSE) { # \dontrun{
library(climasus4r)

# Monthly deaths by municipality
df_agg <- sus_data_import(uf = "RN", year = 2022, system = "SIM-DO") |>
  sus_data_standardize() |>
  sus_data_aggregate(time_unit = "month",
                     group_by  = "codigo_municipio_residencia")

# Default bubble map (Portuguese labels)
sus_data_plot_aggregate_map(df_agg, lang = "pt")

# Choropleth with incidence rate per 100k, English labels
sus_data_plot_aggregate_map(
  df_agg,
  map_type      = "choropleth",
  rate_per_100k = TRUE,
  palette       = "Blues",
  lang          = "en"
)

# Interactive leaflet bubble map
sus_data_plot_aggregate_map(df_agg, interactive = TRUE, lang = "pt")

# Get the map data as sf and export it as GeoPackage
sus_data_plot_aggregate_map(df_agg, map_type = "choropleth",
                             return_sf = TRUE) |>
  sus_data_export(file_path = "map_data.gpkg", format = "gpkg")
} # }

Usage

Arguments

Value

See also

Examples