Skip to contents

Visualise Demographic Profiles from DATASUS Systems

Source: R/sus_data_plot_demographics.R
sus_data_plot_demographics.Rd

Produces publication-quality tables, charts, and composite dashboards summarising the demographic and climate-risk composition of any standardised climasus_df dataset (SIM, SIH, SINAN, CNES, SIA, SINASC). Visual style follows The Lancet / Nature Medicine guidelines. Colour palettes are powered by ggsci::ggsci.

Usage

sus_data_plot_demographics(
  df,
  type = "table",
  var = NULL,
  time_unit = "month",
  fill_var = NULL,
  palette = "lancet",
  heatmap_row = NULL,
  heatmap_col = NULL,
  fill_metric = "pct_row",
  show_ci = FALSE,
  benchmark = NULL,
  interactive = FALSE,
  base_size = 11,
  lang = "pt",
  subtitle = NULL,
  caption = NULL,
  theme_style = "publication",
  caption_suffix = NULL,
  save_path = NULL,
  width = NULL,
  height = NULL,
  dpi = 300,
  verbose = TRUE,
  ...
)

Arguments

df

A climasus_df object at stage "filter_demo" or later (output of sus_data_filter_demographics()).

type

Character. Visualisation type. One of:

  • "table" – Frequency table (gt / DT).

  • "bar" – Horizontal bar chart for one variable.

  • "pyramid" – Age-sex population pyramid.

  • "heatmap" – Cross-demographic tile matrix (two variables).

  • "temporal" – Epidemic curve / time-series.

  • "climate" – Climate-risk group distribution (bar + season heatmap).

  • "race_equity"– Race/colour equity diverging plot vs. IBGE 2022 Census.

  • "dashboard" – Composite Lancet-layout panel.

var

Character. Demographic variable (required for "bar" and single-variable "table"). One of "sex", "race", "age_group", "education", "climate_risk", "region".

time_unit

Character. Temporal resolution for type = "temporal". One of "month" (default), "epi_week", "year", "quarter", "semester".

fill_var

Character. Optional stratification variable for temporal plots (e.g., "sex", "age_group", "climate_risk_group").

palette

Character. Colour palette powered by ggsci::ggsci. One of "lancet" (default), "nature", "nejm", "jco", "aaas", "sus", "viridis", "colorblind".

heatmap_row

Character. Row variable for type = "heatmap". One of "age_group", "sex", "race", "education", "climate_risk", "region". Defaults to "age_group" (auto-detected).

heatmap_col

Character. Column variable for type = "heatmap". Defaults to "race" (auto-detected). Must differ from heatmap_row.

fill_metric

Character. What to show in each tile for type = "heatmap". One of "pct_row" (default – % within each row, e.g. % of each age group that is Parda), "pct_col" (% within each column), "pct_total" (% of all records), "count" (raw count).

show_ci

Logical. Add 95% Poisson confidence intervals in temporal plots. Default FALSE.

benchmark

Numeric named vector. Reference proportions for the race-equity plot. If NULL (default), IBGE 2022 Census proportions are used where available.

interactive

Logical. Return interactive plotly::ggplotly() widget instead of static ggplot2/gt objects. Default FALSE.

base_size

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

lang

Character. Language for labels and messages. One of "pt" (default), "en", "es".

subtitle

Character. Figure subtitle. NULL uses no subtitle.

caption

Character. Figure caption. NULL auto-generates a DATASUS source string for the selected language.

theme_style

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

caption_suffix

Character. Additional text appended to the figure caption (e.g., study period, DOI). Default NULL.

save_path

Character. File path to save output (PNG, PDF, SVG, or HTML). Default NULL (no file saved).

width, height

Numeric. Output dimensions in inches. Defaults: 7 x 5 for single plots; 12 x 9 for dashboards.

dpi

Numeric. Resolution for raster output. Default 300.

verbose

Logical. Print progress messages. Default TRUE.

...

Additional arguments passed to underlying plot helpers.

Value

Invisibly returns the primary plot or list of plots. Side effect: renders in the active graphics device (or interactive widget).

Systems supported

Automatically adapts column detection to SINAN, SIM, SIH, CNES, SIA, and SINASC. Run sus_data_create_variables() before this function to generate age_group, year, month, epidemiological_week, and climate_risk_group.

Climate integration

When climate_risk_group is present (created by sus_data_create_variables()), type = "climate" produces a combined bar + seasonal heatmap designed for climate-health submissions to The Lancet Planetary Health.

Examples

if (FALSE) { # \dontrun{
# Age-sex pyramid (Lancet palette, Portuguese)
sus_data_plot_demographics(df, type = "pyramid", lang = "pt")

# Composite dashboard saved as PDF
sus_data_plot_demographics(
  df,
  type      = "dashboard",
  palette   = "lancet",
  lang      = "en",
  save_path = "figures/fig1_demographics.pdf",
  width = 12, height = 9
)

# Epidemic curve stratified by climate risk group (with CI)
sus_data_plot_demographics(
  df,
  type      = "temporal",
  time_unit = "epi_week",
  fill_var  = "climate_risk_group",
  show_ci   = TRUE,
  lang      = "pt"
)

# Race equity diverging plot
sus_data_plot_demographics(df, type = "race_equity", lang = "pt")

# Cross-demographic heatmap: age group x race, % within each age group
sus_data_plot_demographics(
  df,
  type        = "heatmap",
  heatmap_row = "age_group",
  heatmap_col = "race",
  fill_metric = "pct_row",
  lang        = "pt"
)

# Cross-demographic heatmap: education x climate risk (absolute counts)
sus_data_plot_demographics(
  df,
  type        = "heatmap",
  heatmap_row = "education",
  heatmap_col = "climate_risk",
  fill_metric = "count",
  palette     = "nejm"
)
} # }